diff --git a/.agents/skills/subminer-release/SKILL.md b/.agents/skills/subminer-release/SKILL.md
new file mode 100644
index 00000000..89f68d71
--- /dev/null
+++ b/.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.
diff --git a/.github/workflows/docs-pages.yml b/.github/workflows/docs-pages.yml
index 9f5a4976..477fa1d8 100644
--- a/.github/workflows/docs-pages.yml
+++ b/.github/workflows/docs-pages.yml
@@ -2,6 +2,11 @@ name: Docs Pages
 
 on:
   workflow_dispatch:
+    inputs:
+      rebuild_archives:
+        description: 'Stable tags to rebuild in R2 (comma-separated, or "all"); archives are otherwise built once'
+        required: false
+        default: ''
   push:
     branches:
       - main
@@ -10,6 +15,8 @@ on:
     paths:
       - 'docs-site/**'
       - 'scripts/docs-versioning.ts'
+      - 'scripts/docs-versioned-assets.ts'
+      - 'scripts/docs-archive-store.ts'
       - 'scripts/build-versioned-docs.ts'
       - '.github/workflows/docs-pages.yml'
       - 'package.json'
@@ -32,9 +39,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
@@ -52,20 +61,21 @@ jobs:
           bun install --frozen-lockfile
           cd docs-site && bun install --frozen-lockfile
 
-      - name: Cache versioned docs archives
-        if: steps.tag_guard.outputs.stable_tag != 'false'
-        uses: actions/cache@v4
-        with:
-          path: .tmp/docs-versioned-archive-cache
-          key: docs-versioned-archives-${{ runner.os }}-${{ hashFiles('docs-site/.vitepress/**', 'docs-site/public/assets/fonts/**', 'docs-site/package.json', 'docs-site/bun.lock', 'scripts/build-versioned-docs.ts', 'scripts/docs-versioning.ts') }}
-
       - name: Test docs
         if: steps.tag_guard.outputs.stable_tag != 'false'
         run: bun run docs:test
 
+      # Builds only archives missing from R2 (plus any requested rebuilds), then the
+      # root and /main/ builds that make up the Pages deployment.
       - name: Build versioned docs
         if: steps.tag_guard.outputs.stable_tag != 'false'
-        run: bun run docs:build:versioned
+        env:
+          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+          DOCS_ARCHIVE_R2_ACCESS_KEY_ID: ${{ secrets.DOCS_ARCHIVE_R2_ACCESS_KEY_ID }}
+          DOCS_ARCHIVE_R2_SECRET_ACCESS_KEY: ${{ secrets.DOCS_ARCHIVE_R2_SECRET_ACCESS_KEY }}
+          DOCS_ARCHIVE_R2_BUCKET: ${{ vars.DOCS_ARCHIVE_R2_BUCKET }}
+          REBUILD_ARCHIVES: ${{ inputs.rebuild_archives }}
+        run: bun run scripts/build-versioned-docs.ts --require-archives "--rebuild-archives=${REBUILD_ARCHIVES}"
 
       - name: Deploy docs to Cloudflare Pages
         if: steps.tag_guard.outputs.stable_tag != 'false'
@@ -73,4 +83,6 @@ jobs:
         with:
           apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
           accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
-          command: pages deploy .tmp/docs-versioned-site --project-name "${{ vars.CLOUDFLARE_PAGES_PROJECT_NAME }}" --branch main
+          # Run from docs-site so Wrangler bundles docs-site/functions (the /v/* archive server).
+          workingDirectory: docs-site
+          command: pages deploy ../.tmp/docs-versioned-site --project-name "${{ vars.CLOUDFLARE_PAGES_PROJECT_NAME }}" --branch main
diff --git a/.github/workflows/package-release.yml b/.github/workflows/package-release.yml
new file mode 100644
index 00000000..c04894ca
--- /dev/null
+++ b/.github/workflows/package-release.yml
@@ -0,0 +1,238 @@
+name: Package release
+
+on:
+  workflow_call:
+    secrets:
+      CSC_LINK:
+        required: true
+      CSC_KEY_PASSWORD:
+        required: true
+      APPLE_ID:
+        required: true
+      APPLE_APP_SPECIFIC_PASSWORD:
+        required: true
+      APPLE_TEAM_ID:
+        required: true
+      # Project TMDB key baked into release artifacts; builds stay valid without it.
+      SUBMINER_TMDB_API_KEY:
+        required: false
+
+permissions:
+  contents: read
+
+jobs:
+  build-linux:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          submodules: true
+          persist-credentials: false
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: 1.3.5
+
+      - name: Cache dependencies
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.bun/install/cache
+            node_modules
+            stats/node_modules
+            vendor/texthooker-ui/node_modules
+            vendor/subminer-yomitan/node_modules
+          key: ${{ runner.os }}-${{ runner.arch }}-bun-${{ hashFiles('bun.lock', 'stats/bun.lock', 'vendor/texthooker-ui/bun.lock', 'vendor/subminer-yomitan/package-lock.json') }}
+          restore-keys: |
+            ${{ runner.os }}-${{ runner.arch }}-bun-
+
+      - name: Install dependencies
+        run: |
+          bun install --frozen-lockfile
+          cd stats && bun install --frozen-lockfile
+
+      - name: Build texthooker-ui
+        run: |
+          cd vendor/texthooker-ui
+          bun install --frozen-lockfile
+          bun run build
+
+      - name: Build AppImage
+        run: bun run build:appimage
+        env:
+          SUBMINER_TMDB_API_KEY: ${{ secrets.SUBMINER_TMDB_API_KEY }}
+
+      - name: Build unversioned AppImage
+        run: |
+          shopt -s nullglob
+          appimages=(release/SubMiner-*.AppImage)
+          if [ "${#appimages[@]}" -eq 0 ]; then
+            echo "No versioned AppImage found to create unversioned artifact."
+            ls -la release
+            exit 1
+          fi
+          cp "${appimages[0]}" release/SubMiner.AppImage
+
+      - name: Smoke packaged runtime assets
+        shell: bash
+        run: xvfb-run -a bun run test:package "release/linux-unpacked/resources"
+
+      - name: Upload AppImage artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: appimage
+          path: |
+            release/*.AppImage
+            release/latest*.yml
+            release/*.blockmap
+          if-no-files-found: error
+
+  build-macos:
+    runs-on: macos-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          submodules: true
+          persist-credentials: false
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: 1.3.5
+
+      - name: Cache dependencies
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.bun/install/cache
+            node_modules
+            stats/node_modules
+            vendor/texthooker-ui/node_modules
+            vendor/subminer-yomitan/node_modules
+          key: ${{ runner.os }}-${{ runner.arch }}-bun-${{ hashFiles('bun.lock', 'stats/bun.lock', 'vendor/texthooker-ui/bun.lock', 'vendor/subminer-yomitan/package-lock.json') }}
+          restore-keys: |
+            ${{ runner.os }}-${{ runner.arch }}-bun-
+
+      - name: Validate macOS signing/notarization secrets
+        run: |
+          missing=0
+          for name in CSC_LINK CSC_KEY_PASSWORD APPLE_ID APPLE_APP_SPECIFIC_PASSWORD APPLE_TEAM_ID; do
+            if [ -z "${!name}" ]; then
+              echo "Missing required secret: $name"
+              missing=1
+            fi
+          done
+          if [ "$missing" -ne 0 ]; then
+            echo "Set all required macOS signing/notarization secrets and rerun."
+            exit 1
+          fi
+        env:
+          CSC_LINK: ${{ secrets.CSC_LINK }}
+          CSC_KEY_PASSWORD: ${{ secrets.CSC_KEY_PASSWORD }}
+          APPLE_ID: ${{ secrets.APPLE_ID }}
+          APPLE_APP_SPECIFIC_PASSWORD: ${{ secrets.APPLE_APP_SPECIFIC_PASSWORD }}
+          APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
+
+      - name: Install dependencies
+        run: |
+          bun install --frozen-lockfile
+          cd stats && bun install --frozen-lockfile
+
+      - name: Build texthooker-ui
+        run: |
+          cd vendor/texthooker-ui
+          bun install --frozen-lockfile
+          bun run build
+
+      - name: Build signed + notarized macOS artifacts
+        run: bun run build:mac
+        env:
+          SUBMINER_TMDB_API_KEY: ${{ secrets.SUBMINER_TMDB_API_KEY }}
+          CSC_LINK: ${{ secrets.CSC_LINK }}
+          CSC_KEY_PASSWORD: ${{ secrets.CSC_KEY_PASSWORD }}
+          APPLE_ID: ${{ secrets.APPLE_ID }}
+          APPLE_APP_SPECIFIC_PASSWORD: ${{ secrets.APPLE_APP_SPECIFIC_PASSWORD }}
+          APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
+
+      - name: Smoke packaged runtime assets
+        shell: bash
+        run: bun run test:package "release/mac-arm64/SubMiner.app/Contents/Resources"
+
+      - name: Upload macOS artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: macos
+          path: |
+            release/*.dmg
+            release/*.zip
+            release/latest*.yml
+            release/*.blockmap
+          if-no-files-found: error
+
+  build-windows:
+    runs-on: windows-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          submodules: true
+          persist-credentials: false
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: 1.3.5
+
+      - name: Cache dependencies
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.bun/install/cache
+            node_modules
+            stats/node_modules
+            vendor/texthooker-ui/node_modules
+            vendor/subminer-yomitan/node_modules
+          key: ${{ runner.os }}-${{ runner.arch }}-bun-${{ hashFiles('bun.lock', 'stats/bun.lock', 'vendor/texthooker-ui/bun.lock', 'vendor/subminer-yomitan/package-lock.json') }}
+          restore-keys: |
+            ${{ runner.os }}-${{ runner.arch }}-bun-
+
+      - name: Install dependencies
+        run: |
+          bun install --frozen-lockfile
+          cd stats && bun install --frozen-lockfile
+
+      - name: Build texthooker-ui
+        shell: powershell
+        run: |
+          Set-Location vendor/texthooker-ui
+          bun install --frozen-lockfile
+          bun run build
+
+      - name: Verify managed Windows launcher
+        run: bun test src/main/runtime/managed-launcher.test.ts
+
+      - name: Verify Windows launcher bootstrap
+        run: bun test src/main/runtime/windows-launcher-bootstrap.test.ts
+
+      - name: Build unsigned Windows artifacts
+        run: bun run build:win:unsigned
+        env:
+          SUBMINER_TMDB_API_KEY: ${{ secrets.SUBMINER_TMDB_API_KEY }}
+
+      - name: Smoke packaged runtime assets
+        shell: bash
+        run: bun run test:package "release/win-unpacked/resources"
+
+      - name: Upload Windows artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: windows
+          path: |
+            release/*.exe
+            release/*.zip
+            release/latest*.yml
+            release/*.blockmap
+          if-no-files-found: error
diff --git a/.github/workflows/prerelease.yml b/.github/workflows/prerelease.yml
index 7888110c..6135476e 100644
--- a/.github/workflows/prerelease.yml
+++ b/.github/workflows/prerelease.yml
@@ -16,201 +16,21 @@ jobs:
       contents: read
     uses: ./.github/workflows/quality-gate.yml
 
-  build-linux:
+  package:
     needs: [quality-gate]
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-        with:
-          submodules: true
-
-      - name: Setup Bun
-        uses: oven-sh/setup-bun@v2
-        with:
-          bun-version: 1.3.5
-
-      - name: Cache dependencies
-        uses: actions/cache@v4
-        with:
-          path: |
-            ~/.bun/install/cache
-            node_modules
-            stats/node_modules
-            vendor/texthooker-ui/node_modules
-            vendor/subminer-yomitan/node_modules
-          key: ${{ runner.os }}-${{ runner.arch }}-bun-${{ hashFiles('bun.lock', 'stats/bun.lock', 'vendor/texthooker-ui/package.json', 'vendor/subminer-yomitan/package-lock.json') }}
-          restore-keys: |
-            ${{ runner.os }}-${{ runner.arch }}-bun-
-
-      - name: Install dependencies
-        run: |
-          bun install --frozen-lockfile
-          cd stats && bun install --frozen-lockfile
-
-      - name: Build texthooker-ui
-        run: |
-          cd vendor/texthooker-ui
-          bun install
-          bun run build
-
-      - name: Build AppImage
-        run: bun run build:appimage
-
-      - name: Build unversioned AppImage
-        run: |
-          shopt -s nullglob
-          appimages=(release/SubMiner-*.AppImage)
-          if [ "${#appimages[@]}" -eq 0 ]; then
-            echo "No versioned AppImage found to create unversioned artifact."
-            ls -la release
-            exit 1
-          fi
-          cp "${appimages[0]}" release/SubMiner.AppImage
-
-      - name: Upload AppImage artifact
-        uses: actions/upload-artifact@v4
-        with:
-          name: appimage
-          path: |
-            release/*.AppImage
-            release/latest*.yml
-            release/*.blockmap
-          if-no-files-found: error
-
-  build-macos:
-    needs: [quality-gate]
-    runs-on: macos-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-        with:
-          submodules: true
-
-      - name: Setup Bun
-        uses: oven-sh/setup-bun@v2
-        with:
-          bun-version: 1.3.5
-
-      - name: Cache dependencies
-        uses: actions/cache@v4
-        with:
-          path: |
-            ~/.bun/install/cache
-            node_modules
-            stats/node_modules
-            vendor/texthooker-ui/node_modules
-            vendor/subminer-yomitan/node_modules
-          key: ${{ runner.os }}-${{ runner.arch }}-bun-${{ hashFiles('bun.lock', 'stats/bun.lock', 'vendor/texthooker-ui/package.json', 'vendor/subminer-yomitan/package-lock.json') }}
-          restore-keys: |
-            ${{ runner.os }}-${{ runner.arch }}-bun-
-
-      - name: Validate macOS signing/notarization secrets
-        run: |
-          missing=0
-          for name in CSC_LINK CSC_KEY_PASSWORD APPLE_ID APPLE_APP_SPECIFIC_PASSWORD APPLE_TEAM_ID; do
-            if [ -z "${!name}" ]; then
-              echo "Missing required secret: $name"
-              missing=1
-            fi
-          done
-          if [ "$missing" -ne 0 ]; then
-            echo "Set all required macOS signing/notarization secrets and rerun."
-            exit 1
-          fi
-        env:
-          CSC_LINK: ${{ secrets.CSC_LINK }}
-          CSC_KEY_PASSWORD: ${{ secrets.CSC_KEY_PASSWORD }}
-          APPLE_ID: ${{ secrets.APPLE_ID }}
-          APPLE_APP_SPECIFIC_PASSWORD: ${{ secrets.APPLE_APP_SPECIFIC_PASSWORD }}
-          APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
-
-      - name: Install dependencies
-        run: |
-          bun install --frozen-lockfile
-          cd stats && bun install --frozen-lockfile
-
-      - name: Build texthooker-ui
-        run: |
-          cd vendor/texthooker-ui
-          bun install
-          bun run build
-
-      - name: Build signed + notarized macOS artifacts
-        run: bun run build:mac
-        env:
-          CSC_LINK: ${{ secrets.CSC_LINK }}
-          CSC_KEY_PASSWORD: ${{ secrets.CSC_KEY_PASSWORD }}
-          APPLE_ID: ${{ secrets.APPLE_ID }}
-          APPLE_APP_SPECIFIC_PASSWORD: ${{ secrets.APPLE_APP_SPECIFIC_PASSWORD }}
-          APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
-
-      - name: Upload macOS artifacts
-        uses: actions/upload-artifact@v4
-        with:
-          name: macos
-          path: |
-            release/*.dmg
-            release/*.zip
-            release/latest*.yml
-            release/*.blockmap
-          if-no-files-found: error
-
-  build-windows:
-    needs: [quality-gate]
-    runs-on: windows-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-        with:
-          submodules: true
-
-      - name: Setup Bun
-        uses: oven-sh/setup-bun@v2
-        with:
-          bun-version: 1.3.5
-
-      - name: Cache dependencies
-        uses: actions/cache@v4
-        with:
-          path: |
-            ~/.bun/install/cache
-            node_modules
-            stats/node_modules
-            vendor/texthooker-ui/node_modules
-            vendor/subminer-yomitan/node_modules
-          key: ${{ runner.os }}-${{ runner.arch }}-bun-${{ hashFiles('bun.lock', 'stats/bun.lock', 'vendor/texthooker-ui/package.json', 'vendor/subminer-yomitan/package-lock.json') }}
-          restore-keys: |
-            ${{ runner.os }}-${{ runner.arch }}-bun-
-
-      - name: Install dependencies
-        run: |
-          bun install --frozen-lockfile
-          cd stats && bun install --frozen-lockfile
-
-      - name: Build texthooker-ui
-        shell: powershell
-        run: |
-          Set-Location vendor/texthooker-ui
-          bun install
-          bun run build
-
-      - name: Build unsigned Windows artifacts
-        run: bun run build:win:unsigned
-
-      - name: Upload Windows artifacts
-        uses: actions/upload-artifact@v4
-        with:
-          name: windows
-          path: |
-            release/*.exe
-            release/*.zip
-            release/latest*.yml
-            release/*.blockmap
-          if-no-files-found: error
+    permissions:
+      contents: read
+    uses: ./.github/workflows/package-release.yml
+    secrets:
+      CSC_LINK: ${{ secrets.CSC_LINK }}
+      CSC_KEY_PASSWORD: ${{ secrets.CSC_KEY_PASSWORD }}
+      APPLE_ID: ${{ secrets.APPLE_ID }}
+      APPLE_APP_SPECIFIC_PASSWORD: ${{ secrets.APPLE_APP_SPECIFIC_PASSWORD }}
+      APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
+      SUBMINER_TMDB_API_KEY: ${{ secrets.SUBMINER_TMDB_API_KEY }}
 
   release:
-    needs: [build-linux, build-macos, build-windows]
+    needs: [package]
     runs-on: ubuntu-latest
     permissions:
       contents: write
@@ -256,11 +76,11 @@ jobs:
       - name: Install dependencies
         run: bun install --frozen-lockfile
 
-      - name: Build Bun subminer wrapper
+      - name: Build launcher runtime artifacts
         run: make build-launcher
 
-      - name: Verify Bun subminer wrapper
-        run: dist/launcher/subminer --help >/dev/null
+      - name: Smoke launcher bundle
+        run: bun dist/launcher/subminer.js --help >/dev/null
 
       - name: Enforce generated launcher workflow
         run: bash scripts/verify-generated-launcher.sh
@@ -274,12 +94,17 @@ jobs:
             config.example.jsonc \
             plugin/subminer \
             plugin/subminer.conf \
-            assets/themes/subminer.rasi
+            assets/themes/subminer.rasi \
+            assets/thumbnailers/subminer-ffmpegthumbnailer.thumbnailer \
+            resources/bun/licenses
+
+      - name: Package Bun corresponding source
+        run: bun scripts/package-bun-source.mjs
 
       - name: Generate checksums
         run: |
           shopt -s nullglob
-          files=(release/*.AppImage release/*.dmg release/*.exe release/*.zip release/*.tar.gz release/latest*.yml release/*.blockmap dist/launcher/subminer)
+          files=(release/*.AppImage release/*.dmg release/*.exe release/*.zip release/*.tar.gz release/latest*.yml release/*.blockmap dist/launcher/subminer dist/launcher/subminer.cmd)
           if [ "${#files[@]}" -eq 0 ]; then
             echo "No release artifacts found for checksum generation."
             exit 1
@@ -296,15 +121,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
 
@@ -315,10 +147,12 @@ jobs:
             release/*.exe
             release/*.zip
             release/*.tar.gz
+            release/*.tar.gz.sha256
             release/latest*.yml
             release/*.blockmap
             release/SHA256SUMS.txt
             dist/launcher/subminer
+            dist/launcher/subminer.cmd
           )
 
           if [ "${#artifacts[@]}" -eq 0 ]; then
@@ -326,27 +160,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
diff --git a/.github/workflows/quality-gate.yml b/.github/workflows/quality-gate.yml
index bb5c0d1d..9339ff36 100644
--- a/.github/workflows/quality-gate.yml
+++ b/.github/workflows/quality-gate.yml
@@ -7,6 +7,34 @@ permissions:
   contents: read
 
 jobs:
+  launcher-runtime:
+    strategy:
+      matrix:
+        os: [windows-latest, macos-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: 1.3.5
+
+      - name: Verify native runtime staging
+        run: bun test src/main/runtime/managed-launcher.test.ts
+
+      - name: Verify Windows launcher bootstrap
+        run: bun test src/main/runtime/windows-launcher-bootstrap.test.ts
+
+      - name: Verify native mpv process launch
+        run: bun test src/main/runtime/mpv-process.test.ts
+
+      - name: Verify POSIX launcher bootstrap
+        run: bun test src/main/runtime/posix-launcher-bootstrap.test.ts
+
   quality-gate:
     runs-on: ubuntu-latest
     steps:
@@ -60,17 +88,28 @@ jobs:
 
       - name: Install Lua
         run: |
-          sudo apt-get update
-          sudo apt-get install -y lua5.4
+          # Lua needs only Ubuntu sources; unrelated runner repositories can be unavailable.
+          test -f /etc/apt/sources.list.d/ubuntu.sources
+          apt_sources=(-o Dir::Etc::sourcelist=sources.list.d/ubuntu.sources -o Dir::Etc::sourceparts=-)
+          sudo apt-get "${apt_sources[@]}" update
+          sudo apt-get "${apt_sources[@]}" install -y lua5.4
           sudo ln -sf /usr/bin/lua5.4 /usr/local/bin/lua
           lua -v
 
-      - name: Test suite (source)
-        run: bun run test:fast
+      - name: Launcher unit and script suites
+        run: bun run test:launcher:unit:src && bun run test:scripts
 
       - name: Environment suite
         run: bun run test:env
 
+      - name: Upload launcher smoke artifacts (on failure)
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: launcher-smoke
+          path: .tmp/launcher-smoke/**
+          if-no-files-found: ignore
+
       - name: Coverage suite (maintained source lane)
         run: bun run test:coverage:src
 
@@ -84,17 +123,6 @@ jobs:
       - name: Stats UI tests
         run: bun run test:stats
 
-      - name: Launcher smoke suite (source)
-        run: bun run test:launcher:smoke:src
-
-      - name: Upload launcher smoke artifacts (on failure)
-        if: failure()
-        uses: actions/upload-artifact@v4
-        with:
-          name: launcher-smoke
-          path: .tmp/launcher-smoke/**
-          if-no-files-found: ignore
-
       - name: Build (bundle)
         run: bun run build
 
@@ -107,11 +135,11 @@ jobs:
       - name: Security audit
         run: bun audit --audit-level high
 
-      - name: Build Bun subminer wrapper
+      - name: Build launcher runtime artifacts
         run: make build-launcher
 
-      - name: Verify Bun subminer wrapper
-        run: dist/launcher/subminer --help >/dev/null
+      - name: Smoke launcher bundle
+        run: bun dist/launcher/subminer.js --help >/dev/null
 
       - name: Enforce generated launcher workflow
         run: bash scripts/verify-generated-launcher.sh
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index e3fa97ae..1bb0e414 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -17,199 +17,21 @@ jobs:
       contents: read
     uses: ./.github/workflows/quality-gate.yml
 
-  build-linux:
+  package:
     needs: [quality-gate]
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-        with:
-          submodules: true
-
-      - name: Setup Bun
-        uses: oven-sh/setup-bun@v2
-        with:
-          bun-version: 1.3.5
-
-      - name: Cache dependencies
-        uses: actions/cache@v4
-        with:
-          path: |
-            ~/.bun/install/cache
-            node_modules
-            stats/node_modules
-            vendor/texthooker-ui/node_modules
-            vendor/subminer-yomitan/node_modules
-          key: ${{ runner.os }}-bun-${{ hashFiles('bun.lock', 'stats/bun.lock', 'vendor/texthooker-ui/package.json', 'vendor/subminer-yomitan/package-lock.json') }}
-          restore-keys: |
-            ${{ runner.os }}-bun-
-
-      - name: Install dependencies
-        run: |
-          bun install --frozen-lockfile
-          cd stats && bun install --frozen-lockfile
-
-      - name: Build texthooker-ui
-        run: |
-          cd vendor/texthooker-ui
-          bun install
-          bun run build
-
-      - name: Build AppImage
-        run: bun run build:appimage
-
-      - name: Build unversioned AppImage
-        run: |
-          shopt -s nullglob
-          appimages=(release/SubMiner-*.AppImage)
-          if [ "${#appimages[@]}" -eq 0 ]; then
-            echo "No versioned AppImage found to create unversioned artifact."
-            ls -la release
-            exit 1
-          fi
-          cp "${appimages[0]}" release/SubMiner.AppImage
-
-      - name: Upload AppImage artifact
-        uses: actions/upload-artifact@v4
-        with:
-          name: appimage
-          path: |
-            release/*.AppImage
-            release/latest*.yml
-            release/*.blockmap
-
-  build-macos:
-    needs: [quality-gate]
-    runs-on: macos-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-        with:
-          submodules: true
-
-      - name: Setup Bun
-        uses: oven-sh/setup-bun@v2
-        with:
-          bun-version: 1.3.5
-
-      - name: Cache dependencies
-        uses: actions/cache@v4
-        with:
-          path: |
-            ~/.bun/install/cache
-            node_modules
-            stats/node_modules
-            vendor/texthooker-ui/node_modules
-            vendor/subminer-yomitan/node_modules
-          key: ${{ runner.os }}-bun-${{ hashFiles('bun.lock', 'stats/bun.lock', 'vendor/texthooker-ui/package.json', 'vendor/subminer-yomitan/package-lock.json') }}
-          restore-keys: |
-            ${{ runner.os }}-bun-
-
-      - name: Validate macOS signing/notarization secrets
-        run: |
-          missing=0
-          for name in CSC_LINK CSC_KEY_PASSWORD APPLE_ID APPLE_APP_SPECIFIC_PASSWORD APPLE_TEAM_ID; do
-            if [ -z "${!name}" ]; then
-              echo "Missing required secret: $name"
-              missing=1
-            fi
-          done
-          if [ "$missing" -ne 0 ]; then
-            echo "Set all required macOS signing/notarization secrets and rerun."
-            exit 1
-          fi
-        env:
-          CSC_LINK: ${{ secrets.CSC_LINK }}
-          CSC_KEY_PASSWORD: ${{ secrets.CSC_KEY_PASSWORD }}
-          APPLE_ID: ${{ secrets.APPLE_ID }}
-          APPLE_APP_SPECIFIC_PASSWORD: ${{ secrets.APPLE_APP_SPECIFIC_PASSWORD }}
-          APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
-
-      - name: Install dependencies
-        run: |
-          bun install --frozen-lockfile
-          cd stats && bun install --frozen-lockfile
-
-      - name: Build texthooker-ui
-        run: |
-          cd vendor/texthooker-ui
-          bun install
-          bun run build
-
-      - name: Build signed + notarized macOS artifacts
-        run: bun run build:mac
-        env:
-          CSC_LINK: ${{ secrets.CSC_LINK }}
-          CSC_KEY_PASSWORD: ${{ secrets.CSC_KEY_PASSWORD }}
-          APPLE_ID: ${{ secrets.APPLE_ID }}
-          APPLE_APP_SPECIFIC_PASSWORD: ${{ secrets.APPLE_APP_SPECIFIC_PASSWORD }}
-          APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
-
-      - name: Upload macOS artifacts
-        uses: actions/upload-artifact@v4
-        with:
-          name: macos
-          path: |
-            release/*.dmg
-            release/*.zip
-            release/latest*.yml
-            release/*.blockmap
-
-  build-windows:
-    needs: [quality-gate]
-    runs-on: windows-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-        with:
-          submodules: true
-
-      - name: Setup Bun
-        uses: oven-sh/setup-bun@v2
-        with:
-          bun-version: 1.3.5
-
-      - name: Cache dependencies
-        uses: actions/cache@v4
-        with:
-          path: |
-            ~/.bun/install/cache
-            node_modules
-            stats/node_modules
-            vendor/texthooker-ui/node_modules
-            vendor/subminer-yomitan/node_modules
-          key: ${{ runner.os }}-bun-${{ hashFiles('bun.lock', 'stats/bun.lock', 'vendor/texthooker-ui/package.json', 'vendor/subminer-yomitan/package-lock.json') }}
-          restore-keys: |
-            ${{ runner.os }}-bun-
-
-      - name: Install dependencies
-        run: |
-          bun install --frozen-lockfile
-          cd stats && bun install --frozen-lockfile
-
-      - name: Build texthooker-ui
-        shell: powershell
-        run: |
-          Set-Location vendor/texthooker-ui
-          bun install
-          bun run build
-
-      - name: Build unsigned Windows artifacts
-        run: bun run build:win:unsigned
-
-      - name: Upload Windows artifacts
-        uses: actions/upload-artifact@v4
-        with:
-          name: windows
-          path: |
-            release/*.exe
-            release/*.zip
-            release/latest*.yml
-            release/*.blockmap
-          if-no-files-found: error
+    permissions:
+      contents: read
+    uses: ./.github/workflows/package-release.yml
+    secrets:
+      CSC_LINK: ${{ secrets.CSC_LINK }}
+      CSC_KEY_PASSWORD: ${{ secrets.CSC_KEY_PASSWORD }}
+      APPLE_ID: ${{ secrets.APPLE_ID }}
+      APPLE_APP_SPECIFIC_PASSWORD: ${{ secrets.APPLE_APP_SPECIFIC_PASSWORD }}
+      APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
+      SUBMINER_TMDB_API_KEY: ${{ secrets.SUBMINER_TMDB_API_KEY }}
 
   release:
-    needs: [build-linux, build-macos, build-windows]
+    needs: [package]
     runs-on: ubuntu-latest
     permissions:
       contents: write
@@ -255,11 +77,11 @@ jobs:
       - name: Install dependencies
         run: bun install --frozen-lockfile
 
-      - name: Build Bun subminer wrapper
+      - name: Build launcher runtime artifacts
         run: make build-launcher
 
-      - name: Verify Bun subminer wrapper
-        run: dist/launcher/subminer --help >/dev/null
+      - name: Smoke launcher bundle
+        run: bun dist/launcher/subminer.js --help >/dev/null
 
       - name: Enforce generated launcher workflow
         run: bash scripts/verify-generated-launcher.sh
@@ -273,12 +95,17 @@ jobs:
             config.example.jsonc \
             plugin/subminer \
             plugin/subminer.conf \
-            assets/themes/subminer.rasi
+            assets/themes/subminer.rasi \
+            assets/thumbnailers/subminer-ffmpegthumbnailer.thumbnailer \
+            resources/bun/licenses
+
+      - name: Package Bun corresponding source
+        run: bun scripts/package-bun-source.mjs
 
       - name: Generate checksums
         run: |
           shopt -s nullglob
-          files=(release/*.AppImage release/*.dmg release/*.exe release/*.zip release/*.tar.gz release/latest*.yml release/*.blockmap dist/launcher/subminer)
+          files=(release/*.AppImage release/*.dmg release/*.exe release/*.zip release/*.tar.gz release/latest*.yml release/*.blockmap dist/launcher/subminer dist/launcher/subminer.cmd)
           if [ "${#files[@]}" -eq 0 ]; then
             echo "No release artifacts found for checksum generation."
             exit 1
@@ -295,33 +122,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
 
@@ -332,10 +166,12 @@ jobs:
             release/*.exe
             release/*.zip
             release/*.tar.gz
+            release/*.tar.gz.sha256
             release/latest*.yml
             release/*.blockmap
             release/SHA256SUMS.txt
             dist/launcher/subminer
+            dist/launcher/subminer.cmd
           )
 
           if [ "${#artifacts[@]}" -eq 0 ]; then
@@ -344,7 +180,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:
@@ -417,39 +253,52 @@ jobs:
           echo "skip=true" >> "$GITHUB_OUTPUT"
 
       - name: Download release assets for AUR
+        id: aur_assets
         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 \
-            --pattern "SubMiner-${version#v}.AppImage" \
-            --pattern "subminer" \
-            --pattern "subminer-assets.tar.gz"
+          for asset in "SubMiner-${version#v}.AppImage" subminer subminer-assets.tar.gz; do
+            destination=".tmp/aur-release-assets/$asset"
+            if ! curl --fail --silent --show-error --location \
+              --retry 3 --retry-delay 1 --retry-all-errors \
+              --connect-timeout 30 --max-time 600 \
+              --output "$destination.partial" \
+              "$GITHUB_SERVER_URL/$GITHUB_REPOSITORY/releases/download/$version/$asset"; then
+              echo "::warning::Unable to download $asset after retries; skipping automated AUR publish."
+              echo "skip=true" >> "$GITHUB_OUTPUT"
+              exit 0
+            fi
+            mv "$destination.partial" "$destination"
+          done
+          echo "skip=false" >> "$GITHUB_OUTPUT"
 
       - name: Update AUR packaging metadata
-        if: steps.aur_prereqs.outputs.skip != 'true' && steps.aur_ssh.outputs.skip != 'true' && steps.aur_clone.outputs.skip != 'true'
+        if: steps.aur_prereqs.outputs.skip != 'true' && steps.aur_ssh.outputs.skip != 'true' && steps.aur_clone.outputs.skip != 'true' && steps.aur_assets.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"
 
       - name: Commit and push AUR update
-        if: steps.aur_prereqs.outputs.skip != 'true' && steps.aur_ssh.outputs.skip != 'true' && steps.aur_clone.outputs.skip != 'true'
+        if: steps.aur_prereqs.outputs.skip != 'true' && steps.aur_ssh.outputs.skip != 'true' && steps.aur_clone.outputs.skip != 'true' && steps.aur_assets.outputs.skip != 'true'
         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 +308,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
diff --git a/.gitignore b/.gitignore
index 2f4cd81a..fbba9131 100644
--- a/.gitignore
+++ b/.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
diff --git a/CHANGELOG.md b/CHANGELOG.md
index a32fa520..f064625f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,213 @@
 # Changelog
 
+## v0.20.0 (2026-09-23)
+
+### Added
+- **Japanese Subtitle Generation**:
+  - Generate Japanese SRT subtitles locally with whisper.cpp. Start it from a new modal (Ctrl+Shift+G), from the generate button in an empty subtitle sidebar, or with `subminer generate-subs`.
+  - Generation shows progress, can be cancelled, and loads the finished subtitles into mpv automatically.
+  - Pick an official multilingual Whisper model, including quantized variants, with size and accuracy guidance. You can download it in the app or point Settings at a model you already have.
+  - `large-v3-turbo` is recommended when CUDA support is detected, and `small` otherwise.
+  - whisper-cli, ffmpeg, and ffprobe are found on PATH unless you override them. SubMiner names any missing tools before a download starts.
+  - An optional "Focus on spoken dialogue" mode uses a separately downloaded Silero VAD model. It keeps audible sections it is unsure about, so dialogue under music is not dropped, but songs may also be transcribed.
+  - Long passages are split near speech starts or quiet pauses to reduce subtitles that appear too early. When an eligible embedded or external subtitle track is loaded in mpv, it guides the split points.
+  - Each passage runs in a fresh Whisper process, which prevents repeated-character output.
+- **Subtitle Selection Modal**:
+  - An optional modal for choosing primary and secondary mpv subtitle tracks.
+  - Turn it on in Settings under Behavior, then press g followed by s to open it. Turning it off restores mpv's own subtitle selection binding.
+  - Single-key actions take priority over configured key sequence prefixes.
+  - Conflicting sequences are disabled with a warning, and the existing y commands stay reserved.
+- **Subtitle Sidebar Copy**:
+  - Select dialogue across several sidebar rows and copy it without timestamps using Ctrl/Cmd+C or the Copy button.
+  - Selecting text does not seek playback and does not require mining a card.
+- **Media Timing Review Screenshot Picker**:
+  - Choose the still screenshot separately from the audio range, with a live preview and its own time slider.
+  - Step through decoded frames one at a time to get the exact frame you want.
+  - Works with local video and with seekable remote streams such as Jellyfin.
+- **mpv Keybindings in the Overlay**:
+  - The overlay now picks up keyboard bindings from mpv defaults, `input.conf`, and loaded scripts when they do not conflict with SubMiner.
+  - SubMiner controls and bindings you explicitly disabled take precedence.
+  - These bindings apply only to the current session and are not listed in the help menu.
+- **Jimaku Live Action Search**: The Jimaku modal has new Anime and Live action tabs, so you can search Jimaku's live action catalogue as well as anime. Use Arrow Left and Arrow Right to switch tabs.
+- **TMDB Live-Action Library**:
+  - Live-action dramas and movies in the stats Library now get posters, synopses, and titles from TMDB.
+  - Release builds include a project key. Setting `tmdb.apiKey` or `tmdb.apiKeyCommand` overrides it, and one of them is required when running from source.
+  - Titles that AniList cannot match are looked up on TMDB automatically when the parsed filename exactly matches a Japanese live-action title. For everything else, use the new **Link to TMDB** action.
+  - Entries linked to the same TMDB title merge into one card, and the Library kind selector has a new Live Action option.
+  - If a replacement download fails during provider reassignment, the previous link and artwork are kept. Merges and sync keep AniList and TMDB identities separate, and the merge dialog explains mixed selections instead of failing.
+- **YouTube Library Kind**:
+  - YouTube channels are now their own Library media kind. Existing channel entries migrate automatically, and viewing history and manual video assignments are unchanged.
+  - New All Titles, Anime, and YouTube Library filters.
+  - Channels are excluded from AniList matching, season repair, and duplicate recommendations.
+  - Merges and video moves can no longer combine an anime entry with a YouTube channel.
+
+### Changed
+- **Launcher Uses Bundled Bun**:
+  - Every installed and downloadable launcher now runs on the Bun runtime that ships with SubMiner. A system Bun is no longer needed.
+  - Recognized legacy launchers migrate automatically.
+  - Windows gets a `subminer.cmd` launcher download.
+  - First-run setup is reduced to one optional launcher control. Runtime repair guidance appears only when it is needed.
+- **Faster Sync Transfers**:
+  - Sync between compatible macOS and Linux machines now uses compressed, incremental rsync transfers.
+  - The last snapshot received from each peer is cached, which reduces traffic on later syncs.
+  - Machines without a compatible rsync, including Windows, fall back to compressed scp.
+  - Older peers still work without the upload cache.
+  - Transfers abort after 30 minutes.
+- **Stats Server Request Safety**:
+  - The stats server now accepts loopback hosts only and rejects requests from browser origins other than its own.
+  - Requests that change data must send an `application/json` body. Scripts that POST to the server need to set a JSON content type.
+  - The in-app stats overlay now loads from the local server, so it gets the same protection.
+  - Dashboards served through a reverse proxy or Tailscale Serve are no longer supported.
+- **Smaller Downloads**:
+  - Installers and unpacked apps are smaller. Demo media, source maps, TypeScript sources, test fixtures, and unused Koffi binaries are no longer packaged.
+  - All windows now share one Japanese UI font.
+  - Release builds publish package size reports that compare against the previous release.
+- **Bundled Yomitan**: Updated with upstream Yomitan 26.9.8 changes, including historical Japanese kana transformations, Ukrainian language support, and improvements to Anki duplicate searches and audio retrieval.
+
+### Fixed
+- **Jellyfin 12 Compatibility**:
+  - Playback, subtitle, artwork, and remote-control requests now authenticate with the `ApiKey` query parameter, so the integration works on Jellyfin 12, where legacy authorization is off by default.
+  - "Play on SubMiner" stays available. The cast connection now answers keep-alive requests and reconnects when the server stops responding, instead of silently dying after about a minute.
+  - The Jellyfin "now playing" bar clears when you close or finish a cast video instead of running on to the end of the episode.
+  - Cards mined during Jellyfin playback get the episode title in the misc info field again instead of "Unknown media".
+- **Jellyfin Privacy and Playback**:
+  - Jellyfin streams no longer leak titles taken from the stream URL, or stream URLs that contain credentials, into metadata lookups, Anki source fields, Discord presence, stats, or AniList retries.
+  - Previously cached metadata that contained credentials is cleaned up. Watch history and library assignments are not touched.
+  - Jellyfin playback and casting now use your configured mpv executable, so they work when mpv is installed outside PATH. Portable plugins next to that executable are detected.
+- **Anki Mining**:
+  - New `ankiConnect.fields.wordAudio` setting reads word audio separately from the sentence audio field. This fixes animated images that started moving immediately when `fields.audio` pointed to `SentenceAudio`. Existing animated images need to be regenerated to pick up the fix.
+  - Sentence furigana on word cards stays in sync with the full stats-search context and with expanded timing review selections. Stale readings are cleared if regeneration fails.
+  - Closing the overlay while media timing review is still loading now cancels the review, resumes playback if the review paused it, and cleans up the hidden preview player.
+  - `ankiConnect.media.maxMediaDuration: 0` now means unlimited when mining from the stats dashboard, matching overlay mining.
+  - Invalid AnkiConnect, Kiku, and Senren settings are now rejected with a warning and fall back to defaults.
+- **Stats Server Stability**:
+  - A port conflict is now reported in a status notification instead of crashing SubMiner.
+  - Simultaneous startup requests share one server start. Stopping the background server no longer disconnects dashboards open in the foreground.
+  - Shutdown waits only a limited time for active requests to finish.
+  - Malformed resource IDs, and ID lists with any invalid entries, are rejected before Library changes or cover backfills run.
+- **Subtitle Sidebar**:
+  - Clicking a cue no longer leaves the row focused, and Space no longer seeks back to a focused cue. Enter still seeks to the focused cue, and Space keeps its configured playback action.
+  - The sidebar stays near the current playback position during gaps when the subtitle file has a cue that starts at zero.
+- **Settings Save Feedback**:
+  - Settings marked LIVE no longer show false restart warnings, including for notifications and subtitle generation.
+  - When a save mixes live and restart-only changes, the live changes apply right away and only the changed sections that need a restart are listed.
+- **Overlay Windows**:
+  - On Hyprland, recovery dialogs stay above SubMiner windows so overlay placement updates no longer cover their Wait and Close buttons.
+  - On Linux, a delayed close callback during teardown can no longer reopen the overlay.
+- **First Launch on macOS**: SubMiner no longer exits on first launch when the config directory does not exist yet.
+
+### Docs
+- **Launcher**: Documented the launcher install that uses the bundled runtime, migration from legacy launchers, package-managed updates, and the bundled Bun runtime's MIT and LGPL notices. The AUR package installs these notices under `/usr/share/licenses/subminer-bin`, and they are also included in `subminer-assets.tar.gz`.
+- **Subtitle Generation**: Documented model choice, VAD behavior, splitting guided by a reference track, fallback behavior, and known limits.
+- **Subtitle Selection**: Documented the subtitle selector setting, its shortcut override, and the primary and secondary track controls.
+- **Settings**: Clarified save feedback for live settings, warnings for saves that mix live and restart-only changes, and how subtitle generation settings reload.
+- **Jellyfin**:
+  - Clarified that Windows mpv playback and Jellyfin casting can use a configured executable path instead of PATH.
+  - Documented how Jellyfin media titles and stats identities keep stream credentials out of metadata.
+- **Stats Library**:
+  - Documented TMDB linking, provider reassignment, merge compatibility, and caching of the credential command's output.
+  - Documented YouTube channel filtering and video statistics in the Library.
+- **Mining**:
+  - Documented choosing the screenshot separately in media timing review.
+  - Documented the separate word audio field mapping, including that existing animated images need to be regenerated.
+- **Sync**: Documented compressed transfers, where the incremental sync cache is stored, and compatibility with older peers.
+
+<details>
+<summary>Internal changes</summary>
+
+### Internal
+- Removed duplicate source and launcher smoke runs from the reusable CI quality gate. Every distinct test lane and failure artifact is kept.
+- Replaced mislabeled dist source reruns with a small Electron-runtime smoke check. It covers compiled stats startup, the HTTP service, native SQLite, port conflicts, and cleanup.
+
+</details>
+
+## v0.19.6 (2026-09-04)
+
+### Added
+
+- **Card Timing Review**:
+  - Optional pre-generation timing review for word, sentence, and audio cards, with a speech-weighted waveform that flattens background noise so dialogue edges stand out clearly.
+  - The clip end automatically snaps back to where the line's dialogue actually ends once the waveform loads, with drag and keyboard adjustments available.
+  - Audio preview includes a sweeping playhead that plays the clip to its true end, even on high-latency outputs like Bluetooth headphones.
+  - Previous and next subtitle lines can be pulled onto the card with `P`/`N` (or the Prev/Next steppers) and removed with Shift; the sentence preview and waveform markers update automatically.
+  - Cancelling lets you keep a card without media, and the review can be toggled on or off for the session.
+- **Senren Field Grouping**:
+  - Enable `ankiConnect.isSenren` to merge duplicate mined cards using Senren's scene-switching markup, grouping sentence, furigana, audio, picture, and misc-info fields.
+  - Supports the same auto/manual/disabled modes as Kiku, including the manual merge modal; only one of Senren or Kiku can be enabled at a time.
+
+### Changed
+
+- **Remote Stream Mining Performance**: Mining a card from a remote stream (Jellyfin and other HTTP sources) now downloads the clip window once and reuses it for the timing review waveform, audio preview, audio extraction, and screenshot, instead of re-fetching the stream at each step; the temporary file is cleaned up after ten minutes of inactivity or on exit.
+- **TsukiHime Release Filtering**: The TsukiHime modal's Japanese and secondary-language tabs now filter the release list by the subtitle languages each release actually carries, and report when no release has subtitles for the active tab.
+
+### Fixed
+
+- **Subtitle & Mining Accuracy**:
+  - Broadcast-style captions that split one sentence across two on-screen rows (e.g. Crunchyroll Japanese subs) now merge into a single line for the sidebar and mined cards, while separate speakers, sound effects, and labeled turns still stay on their own lines.
+  - Mining from the overlay no longer pulls in a lingering row from the previous caption; the mined sentence and clip timing now match what's actually on screen.
+  - Multi-line copy and mining now select lines backward in timeline order after seeking, instead of in playback encounter order.
+  - Copying a subtitle, mining a sentence, or recording immersion stats no longer includes the separate furigana line that broadcast ASS captions place above a word.
+- **Card Update Notifications**: Dismissed lingering overlay card-update progress when notification settings switch to OSD before an update finishes.
+- **Overlay Stability on Hyprland**: Opening a modal window (timing review, Jimaku, session help, and others) while mpv is fullscreen no longer causes the overlay to flicker while the modal loads; the overlay now stays on screen untouched until the modal is ready.
+- **Jellyfin Subtitle Sync**: Jellyfin subtitle files now load with zero mpv delay instead of inferring and saving an offset from Japanese and English cue timelines.
+- **Secondary Subtitle Visibility**: Native mpv secondary subtitles stay hidden when switching secondary subtitle tracks during playback.
+
+## 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
diff --git a/Makefile b/Makefile
index dfb5ccfc..59adc5e3 100644
--- a/Makefile
+++ b/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
@@ -158,14 +160,8 @@ build-macos-unsigned: deps
 	@bun run build:mac:unsigned
 
 build-launcher:
-	@printf '%s\n' "[INFO] Bundling launcher script"
-	@install -d "$(dir $(LAUNCHER_OUT))"
-	@bun build ./launcher/main.ts --target=bun --packages=bundle --outfile="$(LAUNCHER_OUT)"
-	@if ! head -1 "$(LAUNCHER_OUT)" | grep -q '^#!/usr/bin/env bun'; then \
-		{ printf '#!/usr/bin/env bun\n'; cat "$(LAUNCHER_OUT)"; } > "$(LAUNCHER_OUT).tmp" && mv "$(LAUNCHER_OUT).tmp" "$(LAUNCHER_OUT)"; \
-	fi
-	@chmod +x "$(LAUNCHER_OUT)"
-	@printf '%s\n' "[INFO] Launcher artifact: $(LAUNCHER_OUT)"
+	@printf '%s\n' "[INFO] Building launcher runtime artifacts"
+	@bun run build:launcher
 
 clean:
 	@printf '%s\n' "[INFO] Removing build artifacts"
@@ -221,11 +217,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 +232,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 +273,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"
diff --git a/README.md b/README.md
index b3fef966..3437e354 100644
--- a/README.md
+++ b/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>
 
@@ -90,6 +90,10 @@ Browse sibling episode files and the active mpv queue in one overlay modal. Open
     <td><b>Jimaku</b></td>
     <td>Search and download Japanese subtitles</td>
   </tr>
+  <tr>
+    <td><b>Local Subtitle Generation</b></td>
+    <td>Generate Japanese subtitles from local audio in a standalone modal (<code>Ctrl+Shift+G</code>), the sidebar button, or launcher, with progress and optional managed model downloads. Requires whisper.cpp and FFmpeg. Optional Silero speech detection prioritizes dialogue in separately timed passages. <a href="https://docs.subminer.moe/main/subtitle-generation">Setup guide</a></td>
+  </tr>
   <tr>
     <td><b>TsukiHime</b></td>
     <td>Search and download subtitles extracted from anime releases, with Japanese and secondary-language tabs (<code>Ctrl+Shift+T</code>) — no API key, requires <code>xz</code> on your <code>PATH</code></td>
@@ -191,7 +195,9 @@ wget https://github.com/ksyasuda/SubMiner/releases/latest/download/SubMiner.AppI
  && chmod +x ~/.local/bin/SubMiner.AppImage
 ```
 
-The AppImage is all you need. The optional `subminer` command-line launcher runs on [Bun](https://bun.sh), and first-run setup can install both for you. To grab it manually instead, install Bun first, then:
+The AppImage is all you need. First-run setup can install the optional `subminer` command-line launcher. Every current launcher uses Bun included with the app, so you do not need Bun installed or on `PATH`.
+
+You can also download the launcher wrapper directly:
 
 ```bash
 wget https://github.com/ksyasuda/SubMiner/releases/latest/download/subminer -O ~/.local/bin/subminer \
@@ -212,6 +218,8 @@ Download the latest DMG from [GitHub Releases](https://github.com/ksyasuda/SubMi
 
 Download and run the latest installer (`.exe`) from [GitHub Releases](https://github.com/ksyasuda/SubMiner/releases/latest).
 
+For terminal use, download `subminer.cmd`. It locates the installed app and uses its private Bun runtime.
+
 </details>
 
 <details>
@@ -223,14 +231,14 @@ See the [build-from-source guide](https://docs.subminer.moe/installation#from-so
 
 ### 2. Launch & Set Up
 
-Run SubMiner and the first-run setup wizard will guide you through importing Yomitan dictionaries and optionally installing the `subminer` command-line launcher.
+Run the installed app and the first-run setup wizard will guide you through importing Yomitan dictionaries and optionally installing the `subminer` command-line launcher. Setup records a custom app location when needed, and the wrapper runs with the app's private Bun runtime.
 
 ```bash
 # Linux
-subminer app --setup
+~/.local/bin/SubMiner.AppImage --setup
 
-# macOS — open SubMiner.app, or:
-subminer app --setup
+# macOS
+open -a SubMiner --args --setup
 ```
 
 On **Windows**, just run `SubMiner.exe` and the setup will open automatically on first launch.
@@ -262,6 +270,7 @@ SubMiner builds on the work of these open-source projects:
 | [Anacreon-Script](https://github.com/friedrich-de/Anacreon-Script)                          | Inspiration for the mining workflow                                     |
 | [asbplayer](https://github.com/killergerbah/asbplayer)                                      | Inspiration for subtitle sidebar and logic for YouTube subtitle parsing |
 | [Bee's Character Dictionary](https://github.com/bee-san/Japanese_Character_Name_Dictionary) | Character name recognition in subtitles                                 |
+| [Bun](https://github.com/oven-sh/bun)                                                       | Bundled runtime for the `subminer` command-line launcher                |
 | [GameSentenceMiner](https://github.com/bpwhelan/GameSentenceMiner)                          | Inspiration for Electron overlay with Yomitan integration               |
 | [jellyfin-mpv-shim](https://github.com/jellyfin/jellyfin-mpv-shim)                          | Jellyfin integration                                                    |
 | [Jimaku.cc](https://jimaku.cc)                                                              | Japanese subtitle search and downloads                                  |
@@ -271,4 +280,6 @@ SubMiner builds on the work of these open-source projects:
 
 ## License
 
-[GNU General Public License v3.0](LICENSE)
+SubMiner is released under the [GNU General Public License v3.0](LICENSE).
+
+Release packages also bundle an unmodified copy of [Bun](https://github.com/oven-sh/bun), which is MIT licensed and statically links JavaScriptCore (LGPL 2.0) and TinyCC (LGPL 2.1). Its license texts and third-party notices ship inside the app under `resources/bun/licenses`, and each release publishes `bun-v1.3.5-source.tar.gz` with the corresponding source. See [Bundled Bun runtime](https://docs.subminer.moe/installation#bundled-bun-runtime).
diff --git a/assets/minecard-poster.jpg b/assets/minecard-poster.jpg
deleted file mode 100644
index b33b3688..00000000
Binary files a/assets/minecard-poster.jpg and /dev/null differ
diff --git a/assets/minecard.gif b/assets/minecard.gif
deleted file mode 100644
index 989212b3..00000000
Binary files a/assets/minecard.gif and /dev/null differ
diff --git a/assets/minecard.jpg b/assets/minecard.jpg
deleted file mode 100644
index 0734e8b1..00000000
Binary files a/assets/minecard.jpg and /dev/null differ
diff --git a/assets/minecard.mp4 b/assets/minecard.mp4
index 1865a6de..94773a6a 100644
Binary files a/assets/minecard.mp4 and b/assets/minecard.mp4 differ
diff --git a/assets/minecard.webm b/assets/minecard.webm
deleted file mode 100644
index eaf7e42a..00000000
Binary files a/assets/minecard.webm and /dev/null differ
diff --git a/assets/minecard.webp b/assets/minecard.webp
index 97400630..f064dda6 100644
Binary files a/assets/minecard.webp and b/assets/minecard.webp differ
diff --git a/assets/thumbnailers/subminer-ffmpegthumbnailer.thumbnailer b/assets/thumbnailers/subminer-ffmpegthumbnailer.thumbnailer
new file mode 100644
index 00000000..c9bb492f
--- /dev/null
+++ b/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;
diff --git a/build/bun-runtime-manifest.json b/build/bun-runtime-manifest.json
new file mode 100644
index 00000000..e0dcd726
--- /dev/null
+++ b/build/bun-runtime-manifest.json
@@ -0,0 +1,31 @@
+{
+  "schemaVersion": 1,
+  "version": "1.3.5",
+  "bunRevision": "1e86cebd74a5723e818b5c0555276b646bcf0e4c",
+  "releaseTagCommit": "fa5a5bbe556a4bda5bde77b4013aa6c3bb4ec9ab",
+  "artifacts": {
+    "darwin-arm64": {
+      "file": "bun-darwin-aarch64.zip",
+      "sha256": "db17588a4aea8804856825d4bead3f05e1f37276ca606f37e369b4f72f35d3fb"
+    },
+    "darwin-x64": {
+      "file": "bun-darwin-x64-baseline.zip",
+      "sha256": "34b9a56b851058dafa1bc9d61233f2c383aa996889bba30b3180f5ccc2cff1b2"
+    },
+    "linux-arm64": {
+      "file": "bun-linux-aarch64.zip",
+      "sha256": "ed01000f85bd97785228ad2845dc92a1860b8054856826d7317690ac8f8ee74b"
+    },
+    "linux-x64": {
+      "file": "bun-linux-x64-baseline.zip",
+      "sha256": "6bddacd6a65855698b9816f2d74871eda4dd0b7fa921140c6445248f94a742fd"
+    },
+    "win32-x64": {
+      "file": "bun-windows-x64-baseline.zip",
+      "sha256": "bf447dcc3b06aba9b9706a9db46fcd65e06a4d47d31439922313825d06eb47ca"
+    }
+  },
+  "licenseInventoryStatus": "source-and-notices-pinned-to-binary-revision",
+  "sourceManifest": "build/bun-source-manifest.json",
+  "correspondingSourceAsset": "bun-v1.3.5-source.tar.gz"
+}
diff --git a/build/bun-source-manifest.json b/build/bun-source-manifest.json
new file mode 100644
index 00000000..23b4864b
--- /dev/null
+++ b/build/bun-source-manifest.json
@@ -0,0 +1,148 @@
+{
+  "schemaVersion": 1,
+  "version": "1.3.5",
+  "releaseTag": "bun-v1.3.5",
+  "releaseTagCommit": "fa5a5bbe556a4bda5bde77b4013aa6c3bb4ec9ab",
+  "bunRevision": "1e86cebd74a5723e818b5c0555276b646bcf0e4c",
+  "archiveName": "bun-v1.3.5-source.tar.gz",
+  "sources": [
+    {
+      "name": "bun",
+      "repository": "oven-sh/bun",
+      "revision": "1e86cebd74a5723e818b5c0555276b646bcf0e4c",
+      "destination": "bun",
+      "sha256": "3a766087902a62a4920e5ac5452dbc7143ff97ea19721f945146629fc9f2d82c",
+      "licensePaths": ["LICENSE.md"]
+    },
+    {
+      "name": "WebKit",
+      "repository": "oven-sh/WebKit",
+      "revision": "6d0f3aac0b817cc01a846b3754b21271adedac12",
+      "destination": "bun/vendor/WebKit",
+      "transport": "git-sparse",
+      "exclude": ["JSTests", "LayoutTests", "ManualTests", "PerformanceTests", "WebDriverTests"],
+      "licensePaths": ["Source/JavaScriptCore/COPYING.LIB"]
+    },
+    {
+      "name": "boringssl",
+      "repository": "oven-sh/boringssl",
+      "revision": "f1ffd9e83d4f5c28a9c70d73f9a4e6fcf310062f",
+      "destination": "bun/vendor/boringssl",
+      "sha256": "af8fd325793bb261c70114d09a24f36092fbe252be8ec040f0054ec9455f0ea3",
+      "licensePaths": ["LICENSE"]
+    },
+    {
+      "name": "brotli",
+      "repository": "google/brotli",
+      "revision": "ed738e842d2fbdf2d6459e39267a633c4a9b2f5d",
+      "upstreamReference": "v1.1.0",
+      "destination": "bun/vendor/brotli",
+      "sha256": "aaa739962a45b508b2e783b915e6b2b57ed3b12bd4b0feac73acfb144dffa54f",
+      "licensePaths": ["LICENSE"]
+    },
+    {
+      "name": "cares",
+      "repository": "c-ares/c-ares",
+      "revision": "3ac47ee46edd8ea40370222f91613fc16c434853",
+      "destination": "bun/vendor/cares",
+      "sha256": "8c94116cb366ae4a44e487da4d9f7e736287d329efa6f88fdf077cd2d0a2e4b8",
+      "licensePaths": ["LICENSE.md"]
+    },
+    {
+      "name": "hdrhistogram",
+      "repository": "HdrHistogram/HdrHistogram_c",
+      "revision": "be60a9987ee48d0abf0d7b6a175bad8d6c1585d1",
+      "destination": "bun/vendor/hdrhistogram",
+      "sha256": "811c5e5ae5303a75ade50688880af6aad5d2f951ec5785f68186bd18635cdfc9",
+      "licensePaths": ["COPYING.txt", "LICENSE.txt"]
+    },
+    {
+      "name": "highway",
+      "repository": "google/highway",
+      "revision": "ac0d5d297b13ab1b89f48484fc7911082d76a93f",
+      "destination": "bun/vendor/highway",
+      "sha256": "a7a816f4b62a0414ff0d39c0a8875847468dd6f7c9ad71781a24469a756cdea7",
+      "licensePaths": ["LICENSE"]
+    },
+    {
+      "name": "libarchive",
+      "repository": "libarchive/libarchive",
+      "revision": "9525f90ca4bd14c7b335e2f8c84a4607b0af6bdf",
+      "destination": "bun/vendor/libarchive",
+      "sha256": "944db9ab58a3cbdb5d947db4f04a3cc15f83b3147fcf7830ada592ba8d4a102c",
+      "licensePaths": ["COPYING"]
+    },
+    {
+      "name": "libdeflate",
+      "repository": "ebiggers/libdeflate",
+      "revision": "c8c56a20f8f621e6a966b716b31f1dedab6a41e3",
+      "destination": "bun/vendor/libdeflate",
+      "sha256": "1e5cc06bdbf3e1245d8b89c9e3588f507e3c8bc53fe8b8229770a9e8661dea81",
+      "licensePaths": ["COPYING"]
+    },
+    {
+      "name": "libuv",
+      "repository": "libuv/libuv",
+      "revision": "f3ce527ea940d926c40878ba5de219640c362811",
+      "destination": "bun/vendor/libuv",
+      "sha256": "46040d51e8aa86a7c84e377e224d427c35022ec6e3ed8ed399493b0d8574d0cf",
+      "licensePaths": ["LICENSE"]
+    },
+    {
+      "name": "lolhtml",
+      "repository": "cloudflare/lol-html",
+      "revision": "d64457d9ff0143deef025d5df7e8586092b9afb7",
+      "destination": "bun/vendor/lolhtml",
+      "sha256": "893b77b460f4c4f4634c973f72cf35e38ebe30646d14a92db3f50ee7e586c0ad",
+      "licensePaths": ["LICENSE"]
+    },
+    {
+      "name": "lshpack",
+      "repository": "litespeedtech/ls-hpack",
+      "revision": "8905c024b6d052f083a3d11d0a169b3c2735c8a1",
+      "destination": "bun/vendor/lshpack",
+      "sha256": "07d8bf901bb1b15543f38eabd23938519e1210eebadb52f3d651d6ef130ef973",
+      "licensePaths": ["LICENSE"]
+    },
+    {
+      "name": "mimalloc",
+      "repository": "oven-sh/mimalloc",
+      "revision": "1beadf9651a7bfdec6b5367c380ecc3fe1c40d1a",
+      "destination": "bun/vendor/mimalloc",
+      "sha256": "317ec2a83462ece78c344c4955c6fee103b412a8e6a0d6ddf9ec8963ed9c0881",
+      "licensePaths": ["LICENSE"]
+    },
+    {
+      "name": "picohttpparser",
+      "repository": "h2o/picohttpparser",
+      "revision": "066d2b1e9ab820703db0837a7255d92d30f0c9f5",
+      "destination": "bun/vendor/picohttpparser",
+      "sha256": "637ff2ab6f5c7f7e05a5b5dc393d5cf2fea8d4754fcaceaaf935ffff5c1323ee",
+      "licensePaths": ["picohttpparser.c", "picohttpparser.h"]
+    },
+    {
+      "name": "tinycc",
+      "repository": "oven-sh/tinycc",
+      "revision": "29985a3b59898861442fa3b43f663fc1af2591d7",
+      "destination": "bun/vendor/tinycc",
+      "sha256": "813cc09aafd6cea9c1ae6b745781e6b27576a0c103f49b63b5c8a732bbe3d290",
+      "licensePaths": ["COPYING"]
+    },
+    {
+      "name": "zlib",
+      "repository": "cloudflare/zlib",
+      "revision": "886098f3f339617b4243b286f5ed364b9989e245",
+      "destination": "bun/vendor/zlib",
+      "sha256": "14bf449df8308696af52f87de88f54c9eb9c91ec5e280587f9d37f7a3f6ed9bb",
+      "licensePaths": ["LICENSE"]
+    },
+    {
+      "name": "zstd",
+      "repository": "facebook/zstd",
+      "revision": "f8745da6ff1ad1e7bab384bd1f9d742439278e99",
+      "destination": "bun/vendor/zstd",
+      "sha256": "4b0bd1f0cfb25e61b9103c35f27395530ff5b4c0d2513a00fd745849e85ea52c",
+      "licensePaths": ["COPYING", "LICENSE"]
+    }
+  ]
+}
diff --git a/bun.lock b/bun.lock
index 6b35b0d6..ffc6190f 100644
--- a/bun.lock
+++ b/bun.lock
@@ -18,10 +18,11 @@
         "ws": "^8.21.0",
       },
       "devDependencies": {
+        "@electron/asar": "3.4.1",
         "@types/node": "^24.10.0",
         "@types/ws": "^8.18.1",
-        "electron": "43.4.1",
-        "electron-builder": "26.15.3",
+        "electron": "43.7.2",
+        "electron-builder": "26.16.1",
         "esbuild": "^0.25.12",
         "eslint": "^10.8.0",
         "prettier": "^3.8.1",
@@ -34,14 +35,14 @@
     "@discordjs/rest@2.6.1": "patches/@discordjs%2Frest@2.6.1.patch",
   },
   "overrides": {
-    "@xmldom/xmldom": "0.8.13",
-    "app-builder-lib": "26.15.3",
+    "@xmldom/xmldom": "0.8.15",
+    "app-builder-lib": "26.16.1",
     "brace-expansion": "5.0.9",
-    "electron-builder-squirrel-windows": "26.15.3",
-    "fast-uri": "3.1.5",
+    "electron-builder-squirrel-windows": "26.16.1",
+    "fast-uri": "3.1.6",
     "form-data": "4.0.6",
     "ip-address": "10.2.0",
-    "js-yaml": "4.3.1",
+    "js-yaml": "4.3.2",
     "lodash": "4.18.0",
     "minimatch": "10.2.5",
     "picomatch": "4.0.4",
@@ -180,7 +181,7 @@
 
     "@neon-rs/load": ["@neon-rs/load@0.0.4", "", {}, "sha512-kTPhdZyTQxB+2wpiRcFWrDcejc4JI6tkPuS7UZCG4l6Zvc5kU/gGQ/ozvHTh1XR5tS+UlfAfGuPajjzQjCiHCw=="],
 
-    "@noble/hashes": ["@noble/hashes@2.2.0", "", {}, "sha512-IYqDGiTXab6FniAgnSdZwgWbomxpy9FtYvLKs7wCUs2a8RkITG+DFGO1DM9cr+E3/RgADRpFjrKVaJ1z6sjtEg=="],
+    "@noble/hashes": ["@noble/hashes@1.8.0", "", {}, "sha512-jCs9ldd7NwzpgXDIf6P3+NrHh9/sD6CQdxHyjQI+h/6rDNo88ypBxxz45UDuZHz9r3tNz7N/VInSVoVdtXEI4A=="],
 
     "@peculiar/asn1-schema": ["@peculiar/asn1-schema@2.8.0", "", { "dependencies": { "@peculiar/utils": "^2.0.2", "asn1js": "^3.0.10", "tslib": "^2.8.1" } }, "sha512-7YT0U/ze0tF2QOBbE15gKZwy5tvgGyLRiRHLzhlbOpf7BT032oBSd0haZqXn5W6l26WLlu3dyxzjM+2638/z2Q=="],
 
@@ -226,7 +227,7 @@
 
     "@xhayper/discord-rpc": ["@xhayper/discord-rpc@1.3.4", "", { "dependencies": { "@discordjs/rest": "^2.6.1", "@vladfrangu/async_event_emitter": "^2.4.7", "discord-api-types": "^0.38.47", "ws": "^8.20.0" } }, "sha512-ff0uEXuibh9wi+l4vOj7xInLUjtlTaQBje/SCyQkeXZ0j2V0y+Zge5PQIQFRHH9TjjGaYJkTofEcQhncM2q7/w=="],
 
-    "@xmldom/xmldom": ["@xmldom/xmldom@0.8.13", "", {}, "sha512-KRYzxepc14G/CEpEGc3Yn+JKaAeT63smlDr+vjB8jRfgTBBI9wRj/nkQEO+ucV8p8I9bfKLWp37uHgFrbntPvw=="],
+    "@xmldom/xmldom": ["@xmldom/xmldom@0.8.15", "", {}, "sha512-/5NV/vDALVFDXgLmfsy9TRCBlKwO2LNBFzpzvb9iIj+jR+eSc6DLYYvVOdivT/jm7MtU6TebYuRmzEOI7w40UA=="],
 
     "abbrev": ["abbrev@4.0.0", "", {}, "sha512-a1wflyaL0tHtJSmLSOVybYhy22vRih4eduhhrkcjgrWGnRfrZtovJ2FRjxuTtkkj47O/baf0R86QU5OuYpz8fA=="],
 
@@ -242,7 +243,7 @@
 
     "ansi-styles": ["ansi-styles@4.3.0", "", { "dependencies": { "color-convert": "^2.0.1" } }, "sha512-zbB9rCJAT1rbjiVDb2hqKFHNYLxgtk8NURxZ3IZwD3F6NtxbXZQCnnSi1Lkx+IDohdPlFp222wVALIheZJQSEg=="],
 
-    "app-builder-lib": ["app-builder-lib@26.15.3", "", { "dependencies": { "@electron/asar": "3.4.1", "@electron/fuses": "^1.8.0", "@electron/get": "^3.0.0", "@electron/notarize": "2.5.0", "@electron/osx-sign": "1.3.3", "@electron/rebuild": "^4.0.4", "@electron/universal": "2.0.3", "@malept/flatpak-bundler": "^0.4.0", "@noble/hashes": "^2.2.0", "@peculiar/webcrypto": "^1.7.1", "@types/fs-extra": "9.0.13", "ajv": "^8.18.0", "asn1js": "^3.0.10", "async-exit-hook": "^2.0.1", "builder-util": "26.15.3", "builder-util-runtime": "9.7.0", "chromium-pickle-js": "^0.2.0", "ci-info": "4.3.1", "debug": "^4.3.4", "dotenv": "^16.4.5", "dotenv-expand": "^11.0.6", "ejs": "^3.1.8", "electron-publish": "26.15.3", "fs-extra": "^10.1.0", "hosted-git-info": "^4.1.0", "isbinaryfile": "^5.0.0", "jiti": "^2.4.2", "js-yaml": "^4.1.0", "json5": "^2.2.3", "lazy-val": "^1.0.5", "minimatch": "^10.2.5", "pkijs": "^3.4.0", "plist": "3.1.0", "proper-lockfile": "^4.1.2", "resedit": "^1.7.0", "semver": "~7.7.3", "tar": "^7.5.7", "temp-file": "^3.4.0", "tiny-async-pool": "1.3.0", "unzipper": "^0.12.3", "which": "^5.0.0" }, "peerDependencies": { "dmg-builder": "26.15.3", "electron-builder-squirrel-windows": "26.15.3" } }, "sha512-2VnyWkqsP5v5XbBhL3tD5Syx8iNPBYsoU7kY4S2fz7wg8Rj/nztWKCUzGKaFRTv0Xwf3/H058CR1Kvtd/3lRow=="],
+    "app-builder-lib": ["app-builder-lib@26.16.1", "", { "dependencies": { "@electron/asar": "3.4.1", "@electron/fuses": "^1.8.0", "@electron/get": "^3.0.0", "@electron/notarize": "2.5.0", "@electron/osx-sign": "1.3.3", "@electron/rebuild": "^4.0.4", "@electron/universal": "2.0.3", "@malept/flatpak-bundler": "^0.4.0", "@noble/hashes": "^1.8.0", "@peculiar/webcrypto": "^1.7.1", "@types/fs-extra": "9.0.13", "ajv": "^8.18.0", "asn1js": "^3.0.10", "async-exit-hook": "^2.0.1", "builder-util": "26.16.0", "builder-util-runtime": "9.7.0", "chromium-pickle-js": "^0.2.0", "ci-info": "4.3.1", "debug": "^4.3.4", "dotenv": "^16.4.5", "dotenv-expand": "^11.0.6", "ejs": "^3.1.8", "electron-publish": "26.16.0", "fs-extra": "^10.1.0", "hosted-git-info": "^4.1.0", "isbinaryfile": "^5.0.0", "jiti": "^2.4.2", "js-yaml": "^4.1.0", "json5": "^2.2.3", "lazy-val": "^1.0.5", "minimatch": "^10.2.5", "pkijs": "^3.4.0", "plist": "3.1.0", "proper-lockfile": "^4.1.2", "resedit": "^1.7.0", "semver": "~7.7.3", "tar": "^7.5.7", "temp-file": "^3.4.0", "tiny-async-pool": "1.3.0", "unzipper": "^0.12.3", "which": "^5.0.0" }, "peerDependencies": { "dmg-builder": "26.16.1", "electron-builder-squirrel-windows": "26.16.1" } }, "sha512-FhaO6YOup01ZfQW0Z6gt3AyukJjv1gW4uFK47jTgwcHZKqyN/fSlK2LqPf9tAeZYLP2bRJLDzeOkRImsw2X4Pg=="],
 
     "argparse": ["argparse@2.0.1", "", {}, "sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q=="],
 
@@ -272,7 +273,7 @@
 
     "buffer-from": ["buffer-from@1.1.2", "", {}, "sha512-E+XQCRwSbaaiChtv6k6Dwgc+bx+Bs6vuKJHHl5kox/BaKbhiXzqQOwK4cO22yElGp2OCmjwVhT3HmxgyPGnJfQ=="],
 
-    "builder-util": ["builder-util@26.15.3", "", { "dependencies": { "@types/debug": "^4.1.6", "builder-util-runtime": "9.7.0", "chalk": "^4.1.2", "cross-spawn": "^7.0.6", "debug": "^4.3.4", "fs-extra": "^10.1.0", "http-proxy-agent": "^7.0.0", "https-proxy-agent": "^7.0.0", "js-yaml": "^4.1.0", "sanitize-filename": "^1.6.3", "source-map-support": "^0.5.19", "stat-mode": "^1.0.0", "temp-file": "^3.4.0", "tiny-async-pool": "1.3.0" } }, "sha512-q2hn7Mbo2nFNkVekPiHFx6Nfo3hURmES3tfBn+k5Pqxl2RkmP3QGqZUhH/q9Pch/4G05NRhPjDlVj1O8q4Txvw=="],
+    "builder-util": ["builder-util@26.16.0", "", { "dependencies": { "@types/debug": "^4.1.6", "builder-util-runtime": "9.7.0", "chalk": "^4.1.2", "cross-spawn": "^7.0.6", "debug": "^4.3.4", "fs-extra": "^10.1.0", "http-proxy-agent": "^7.0.0", "https-proxy-agent": "^7.0.0", "js-yaml": "^4.1.0", "sanitize-filename": "^1.6.3", "source-map-support": "^0.5.19", "stat-mode": "^1.0.0", "temp-file": "^3.4.0", "tiny-async-pool": "1.3.0" } }, "sha512-RLyJhB7Si3YkzKR9ubQslWuXW3Vhs3CGe1i+SeixBZ0qTd1mk3XBmssvY22TlB6CS5blyko8Gu1JzpYk8UkYAg=="],
 
     "builder-util-runtime": ["builder-util-runtime@9.7.0", "", { "dependencies": { "debug": "^4.3.4", "sax": "^1.2.4" } }, "sha512-g/kR520giAFYkSXTzcmF3kqQq7wi8F6N6SzeDgZrqTBN+VHdmgWOyTdD1yD7AATDId/yXLvuP34CxW46/BwCdw=="],
 
@@ -334,7 +335,7 @@
 
     "discord-api-types": ["discord-api-types@0.38.49", "", {}, "sha512-XnqcWmnFZFAE8ZM8SHAw9DIV8D3Or00rMQ8iQLotrEA2PmXhl+ykaf6L6q4l474hrSUH1JaYcv+iOMRWp2p6Tg=="],
 
-    "dmg-builder": ["dmg-builder@26.15.3", "", { "dependencies": { "app-builder-lib": "26.15.3", "builder-util": "26.15.3", "fs-extra": "^10.1.0", "js-yaml": "^4.1.0" } }, "sha512-O3zJUFUYHJKgzPqioHxfxzBzlSC1eXCSr79gMSBKBP5AgjjpmrydMsMLotEg9fAJF36vdUncb+4ndRNxoPdlSQ=="],
+    "dmg-builder": ["dmg-builder@26.16.1", "", { "dependencies": { "app-builder-lib": "26.16.1", "builder-util": "26.16.0", "fs-extra": "^10.1.0", "js-yaml": "^4.1.0" } }, "sha512-pnI/3Qb24Uk+rMTgIUrsVUKosVgwmBUdF8Zeb8TexOSbpq8MWc7v6l+n+FrEqVkjNZwzBN+XpDS9ENgZ/rkWAw=="],
 
     "dotenv": ["dotenv@16.6.1", "", {}, "sha512-uBq4egWHTcTt33a72vpSG0z3HnPuIl6NqYcTrKEg2azoEyl2hpW0zqlxysq2pK9HlDIHyHyakeYaYnSAwd8bow=="],
 
@@ -346,13 +347,13 @@
 
     "ejs": ["ejs@3.1.10", "", { "dependencies": { "jake": "^10.8.5" }, "bin": { "ejs": "bin/cli.js" } }, "sha512-UeJmFfOrAQS8OJWPZ4qtgHyWExa088/MtK5UEyoJGFH67cDEXkZSviOiKRCZ4Xij0zxI3JECgYs3oKx+AizQBA=="],
 
-    "electron": ["electron@43.4.1", "", { "dependencies": { "@electron-internal/extract-zip": "^1.0.1", "@electron/get": "^5.0.0", "@types/node": "^24.9.0" }, "bin": { "electron": "cli.js", "install-electron": "install.js" } }, "sha512-5b+EuiwkgG5iRcsEL34rimgRpkYp15SsfZOa0pC5kXs0Tb82TH4n95rpQzTZa7yRCbA7tm0WoEbuBL6NaAhAcA=="],
+    "electron": ["electron@43.7.2", "", { "dependencies": { "@electron-internal/extract-zip": "^1.0.1", "@electron/get": "^5.0.0", "@types/node": "^24.9.0" }, "bin": { "electron": "cli.js", "install-electron": "install.js" } }, "sha512-xUvboWe2LuBPFHucVrAFA9V4Z1ywdnP+B7imE59gsOxnFmQtumuicyjOOxOq1gyT6MbnuhGeM2wNBMh1xKs5VA=="],
 
-    "electron-builder": ["electron-builder@26.15.3", "", { "dependencies": { "app-builder-lib": "26.15.3", "builder-util": "26.15.3", "builder-util-runtime": "9.7.0", "chalk": "^4.1.2", "ci-info": "^4.2.0", "dmg-builder": "26.15.3", "fs-extra": "^10.1.0", "lazy-val": "^1.0.5", "simple-update-notifier": "2.0.0", "yargs": "^17.6.2" }, "bin": { "electron-builder": "./cli.js", "install-app-deps": "./install-app-deps.js" } }, "sha512-a1KM5heqS3gQCZzizXEI8RjJy3QVogULPdeSknt76uLDpBIW/HDGsMg/XgP0riP6PI9COsRvFITKKGDqA8fJxA=="],
+    "electron-builder": ["electron-builder@26.16.1", "", { "dependencies": { "app-builder-lib": "26.16.1", "builder-util": "26.16.0", "builder-util-runtime": "9.7.0", "chalk": "^4.1.2", "ci-info": "^4.2.0", "dmg-builder": "26.16.1", "fs-extra": "^10.1.0", "lazy-val": "^1.0.5", "simple-update-notifier": "2.0.0", "yargs": "^17.6.2" }, "bin": { "electron-builder": "./cli.js", "install-app-deps": "./install-app-deps.js" } }, "sha512-LrLK65QX5PUYYODXqp23FKrV7CILTtVY7mrJckNknO9jLNSMiqFkKbSMiDRw4CjOADMPVDdWLxY4mezOZWswxg=="],
 
-    "electron-builder-squirrel-windows": ["electron-builder-squirrel-windows@26.15.3", "", { "dependencies": { "app-builder-lib": "26.15.3", "builder-util": "26.15.3", "electron-winstaller": "5.4.0" } }, "sha512-Jc19XPV9y9+2bAdZPkXuVNGNIEFBq9poHC61l8Kv6FdK7DRG3+Ic0rerC0DXOaeHNz8yW0fg/JnF8GQROOF5MA=="],
+    "electron-builder-squirrel-windows": ["electron-builder-squirrel-windows@26.16.1", "", { "dependencies": { "app-builder-lib": "26.16.1", "builder-util": "26.16.0", "electron-winstaller": "5.4.0" } }, "sha512-w0y44wSaT1l6R7CAGmeHn4nHPfvzDyCAU1xJyi1w9SbPYJpYn76SmHDzqHf8Y7l91cPWTdPYBpGQtB2T5mJ08A=="],
 
-    "electron-publish": ["electron-publish@26.15.3", "", { "dependencies": { "@types/fs-extra": "^9.0.11", "aws4": "^1.13.2", "builder-util": "26.15.3", "builder-util-runtime": "9.7.0", "chalk": "^4.1.2", "form-data": "^4.0.5", "fs-extra": "^10.1.0", "lazy-val": "^1.0.5", "mime": "^2.5.2" } }, "sha512-g/2bn8YTavY4cuS5F+jOS7zmZbXXBV8KZ8yHKfJjFPoKtzBqrpCdNPxBd3tqdBwP7BVd0lGzf7Bk2s0KesWZ4Q=="],
+    "electron-publish": ["electron-publish@26.16.0", "", { "dependencies": { "@types/fs-extra": "^9.0.11", "aws4": "^1.13.2", "builder-util": "26.16.0", "builder-util-runtime": "9.7.0", "chalk": "^4.1.2", "form-data": "^4.0.5", "fs-extra": "^10.1.0", "lazy-val": "^1.0.5", "mime": "^2.5.2" } }, "sha512-Vt3KzQIiw9BImvNOYtndg9Mjki+tl4+1sQiC/+G5j8khWaENOJFWodiB+sUl6yyHwtd37avehskdtPw7f8y/+Q=="],
 
     "electron-updater": ["electron-updater@6.8.9", "", { "dependencies": { "builder-util-runtime": "9.7.0", "fs-extra": "^10.1.0", "js-yaml": "^4.1.0", "lazy-val": "^1.0.5", "lodash.escaperegexp": "^4.1.2", "lodash.isequal": "^4.5.0", "semver": "~7.7.3", "tiny-typed-emitter": "^2.1.0" } }, "sha512-ZhVxM9iGONUpZGI1FxdMRgJjUFXi7AYGVa5PwKlO1tV1/4zDxQmfKpXOHVztKrd6L9rLcFjERvi1Mf2vxyTkig=="],
 
@@ -406,7 +407,7 @@
 
     "fast-levenshtein": ["fast-levenshtein@2.0.6", "", {}, "sha512-DCXu6Ifhqcks7TZKY3Hxp3y6qphY5SJZmrWMDrKcERSOXWQdMhU9Ig/PYrzyw/ul9jOIyh0N4M0tbC5hodg8dw=="],
 
-    "fast-uri": ["fast-uri@3.1.5", "", {}, "sha512-gHwA1O9LDIcKunMKhObS/HimwtehO1nPUECKAu5TpKgaO19fcWEl4bliWe1jWxVFvIXztJjjQ4L8XQ1EU9f7Jw=="],
+    "fast-uri": ["fast-uri@3.1.6", "", {}, "sha512-7Ical1vFEMr0onbVzEDIreM22I4khW+fzyQPwvAFWBp1iwdshSZRsL4jjRvPG9JP1uiqMHRto+YU6R2/CzDz5Q=="],
 
     "fdir": ["fdir@6.5.0", "", { "peerDependencies": { "picomatch": "^3 || ^4" }, "optionalPeers": ["picomatch"] }, "sha512-tIbYtZbucOs0BRGqPJkshJUYdL+SDH7dVM8gjy+ERp3WAUjLEFJE+02kanyHtwjWOnwrKYBiwAmM0p4kLJAnXg=="],
 
@@ -498,7 +499,7 @@
 
     "jiti": ["jiti@2.6.1", "", { "bin": { "jiti": "lib/jiti-cli.mjs" } }, "sha512-ekilCSN1jwRvIbgeg/57YFh8qQDNbwDb9xT/qu2DAHbFFZUicIl4ygVaAvzveMhMVr3LnpSKTNnwt8PoOfmKhQ=="],
 
-    "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=="],
+    "js-yaml": ["js-yaml@4.3.2", "", { "dependencies": { "argparse": "^2.0.1" }, "bin": { "js-yaml": "bin/js-yaml.js" } }, "sha512-SFNOvSJ+Dgf/9An904Yx+CgSlIPCkIpao4qo51lpee25TIRejdH3rhR4EZMGoNx3/TP3O+wzWuiTFl4sqbltzA=="],
 
     "json-buffer": ["json-buffer@3.0.1", "", {}, "sha512-4bV5BfR2mqfQTJm+V5tPPdf+ZpuhiIvTuAB5g8kcrXOZpTT/QwwVRWBywX1ozr6lEuPdbHxwaJlm9G6mI2sfSQ=="],
 
diff --git a/changes/README.md b/changes/README.md
index 667c6845..a3eb3989 100644
--- a/changes/README.md
+++ b/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
diff --git a/changes/ass-canonical-animation-lines.md b/changes/ass-canonical-animation-lines.md
deleted file mode 100644
index 4805bbc8..00000000
--- a/changes/ass-canonical-animation-lines.md
+++ /dev/null
@@ -1,5 +0,0 @@
-type: fixed
-area: subtitles
-
-- Typeset ASS karaoke and animated signs no longer flood the primary overlay, subtitle sidebar, immersion history, or sentence mining with repeated glyph fragments or full-line color phases. Matching timed comments and full-line boundary events recover the complete authored line without merging ordinary repeated dialogue or separately positioned signs, and dialogue spoken while a song's animation is on screen is kept intact instead of being replaced by the lyric. Entrance and exit frames that run past the authored line timing still resolve to the clean line during lyric transitions, and dialogue spoken while a song's animation is on screen enters immersion and subtitle history without the fragment lines beside it.
-- The secondary subtitle overlay drops layered duplicate lines from animated tracks, so a short stack of repeated words collapses to its distinct lines even when the full karaoke heuristic does not apply.
diff --git a/changes/audio-generation-network-mounts.md b/changes/audio-generation-network-mounts.md
deleted file mode 100644
index 30221c75..00000000
--- a/changes/audio-generation-network-mounts.md
+++ /dev/null
@@ -1,4 +0,0 @@
-type: fixed
-area: Anki media
-
-- Fixed sentence-audio generation timing out on slow network-mounted MKV files with many subtitle and font-attachment streams. Selected audio tracks now use bounded FFmpeg probing and a two-minute extraction budget, and missing output reports a clear FFmpeg error instead of raw `ENOENT`.
diff --git a/changes/dictionary-freeze-and-appimage-notifications.md b/changes/dictionary-freeze-and-appimage-notifications.md
deleted file mode 100644
index 5bc6e4c9..00000000
--- a/changes/dictionary-freeze-and-appimage-notifications.md
+++ /dev/null
@@ -1,5 +0,0 @@
-type: fixed
-area: dictionary
-
-- Character dictionary generation, merged rebuilds, and imports no longer freeze the app (and trigger the compositor's "application not responding" dialog) on large dictionaries; snapshot reads/writes, archive building, and the character image/name lookup caches now do their heavy work off the UI's critical path.
-- Desktop progress notifications now update in place on Linux AppImage installs too: the AppImage's bundled libraries broke the system notify-send helper, which silently forced the flickering close-and-reopen notification fallback.
diff --git a/changes/docs-site-index-hygiene.md b/changes/docs-site-index-hygiene.md
deleted file mode 100644
index d988658f..00000000
--- a/changes/docs-site-index-hygiene.md
+++ /dev/null
@@ -1,5 +0,0 @@
-type: internal
-area: docs
-
-- Excluded the `/main/` and `/v/<version>/` docs trees from search indexing with a self-referential canonical, `noindex,follow`, and a matching `X-Robots-Tag` header, so crawlers spend their budget on the current docs instead of ~30 archived copies of every page.
-- Restored `<lastmod>` dates in the docs sitemap, which were silently dropped because production builds render from an untracked release snapshot.
diff --git a/changes/docs-site-simplify.md b/changes/docs-site-simplify.md
new file mode 100644
index 00000000..542271e8
--- /dev/null
+++ b/changes/docs-site-simplify.md
@@ -0,0 +1,6 @@
+type: docs
+area: docs
+
+- Rewrote the docs site to be shorter and easier to scan: pages lead with setup and use, reference material lives in compact tables, and internal detail was cut from user pages.
+- The configuration reference now has a short explanation and a key/default table for each config block.
+- Fixed docs that no longer matched current behavior.
diff --git a/changes/duplicate-line-stats-cleanup.md b/changes/duplicate-line-stats-cleanup.md
deleted file mode 100644
index e6389cfd..00000000
--- a/changes/duplicate-line-stats-cleanup.md
+++ /dev/null
@@ -1,5 +0,0 @@
-type: fixed
-area: stats
-
-- Typeset subtitles no longer flood the stats. Karaoke openings and animated signs are authored as one subtitle event per animation frame, and immersion tracking counted every frame, which was enough to put an OP lyric at the top of "Top Repeated Words" for good. Lines are now collapsed on the way in using the same rules the subtitle sidebar already applies: matching parsed timings record exactly the cues the sidebar shows, while shifted, changing, or unparsed sources use a strict fallback where identical, contiguous, sub-0.1s lines stop counting after a few frames. Ordinary repeated dialogue and rewatches are unaffected.
-- Added a cleanup for stats already affected. The Vocabulary tab has a **Duplicates** button that scans a chosen window (7 days through all time), shows the bursts it found and the word and kanji counts they added, 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>`. Only subtitle lines and the vocabulary counts they feed are touched; watch time and lines-seen totals are left as recorded.
diff --git a/changes/electron43-profile-storage-safety.md b/changes/electron43-profile-storage-safety.md
index a1787751..e323241e 100644
--- a/changes/electron43-profile-storage-safety.md
+++ b/changes/electron43-profile-storage-safety.md
@@ -1,6 +1,6 @@
 type: fixed
 area: dictionary
 
-- Upgraded the desktop runtime to Electron 43.4.1 and added profile guards that block unsupported runtimes and Electron downgrades before Yomitan storage is loaded.
+- Upgraded the desktop runtime to Electron 43.7.2 and added profile guards that block unsupported runtimes and Electron downgrades before Yomitan storage is loaded.
 - Development launches now use a separate `SubMiner-dev` profile unless production-profile access is explicitly requested.
 - Automatic character-dictionary changes now stop when a previously non-empty Yomitan profile suddenly reports zero dictionaries.
diff --git a/changes/fix-macos-fullscreen-modal-spaces.md b/changes/fix-macos-fullscreen-modal-spaces.md
deleted file mode 100644
index d8ef0f17..00000000
--- a/changes/fix-macos-fullscreen-modal-spaces.md
+++ /dev/null
@@ -1,5 +0,0 @@
-type: fixed
-area: overlay
-
-- Dedicated overlay modals are prewarmed on macOS and Windows so shortcuts open them promptly on the first press. Windows now refreshes the hidden modal renderer between sessions to keep later modals interactive. On macOS, reused modals and the in-app stats window also open above fullscreen mpv on its current Space instead of appearing on another desktop or forcing a Space change.
-- Updated subtitle ASS observation to mpv's current `sub-text/ass` property, removing its deprecation warning.
diff --git a/changes/fix-mpv-ipc-connect-stall.md b/changes/fix-mpv-ipc-connect-stall.md
deleted file mode 100644
index 8a28dc31..00000000
--- a/changes/fix-mpv-ipc-connect-stall.md
+++ /dev/null
@@ -1,4 +0,0 @@
-type: fixed
-area: overlay
-
-- Fixed the overlay getting stuck on "Overlay loading" forever when startup stalls: mpv IPC connection attempts now time out and retry, switching sockets aborts obsolete attempts, and the plugin replaces its spinner with an actionable error if overlay content is still not ready after 30 seconds.
diff --git a/changes/fix-native-wayland-overlay-file-drop.md b/changes/fix-native-wayland-overlay-file-drop.md
deleted file mode 100644
index d368159f..00000000
--- a/changes/fix-native-wayland-overlay-file-drop.md
+++ /dev/null
@@ -1,4 +0,0 @@
-type: fixed
-area: overlay
-
-- 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.
diff --git a/changes/fix-primary-ass-layer-duplication.md b/changes/fix-primary-ass-layer-duplication.md
deleted file mode 100644
index e7495921..00000000
--- a/changes/fix-primary-ass-layer-duplication.md
+++ /dev/null
@@ -1,4 +0,0 @@
-type: fixed
-area: subtitles
-
-- Primary ASS subtitles now use the active parsed cue when it fully accounts for mpv's live text, preventing fill, border, blur, and shadow copies of the same full-span lyric from appearing repeatedly while preserving unmatched overlapping dialogue and signs.
diff --git a/changes/fix-secondary-subtitle-duplication.md b/changes/fix-secondary-subtitle-duplication.md
deleted file mode 100644
index 07682311..00000000
--- a/changes/fix-secondary-subtitle-duplication.md
+++ /dev/null
@@ -1,4 +0,0 @@
-type: fixed
-area: overlay
-
-- Secondary subtitles now parse the selected ASS/SRT/VTT source with the primary subtitle deduplication pipeline, preventing layered animation text from appearing several times in the overlay, mined cards, and statistics. Live mpv text remains the fallback for unreadable tracks.
diff --git a/changes/fix-windows-system-mouse-lag.md b/changes/fix-windows-system-mouse-lag.md
deleted file mode 100644
index 178e4f78..00000000
--- a/changes/fix-windows-system-mouse-lag.md
+++ /dev/null
@@ -1,4 +0,0 @@
-type: fixed
-area: overlay
-
-- Fixed system-wide mouse lag on Windows while SubMiner is running: the overlay no longer installs Electron's global mouse hook for click-through forwarding, and the mpv window tracker no longer blocks the app on repeated PowerShell command-line lookups.
diff --git a/changes/hide-feature-demos.md b/changes/hide-feature-demos.md
deleted file mode 100644
index 63c1a6dd..00000000
--- a/changes/hide-feature-demos.md
+++ /dev/null
@@ -1,4 +0,0 @@
-type: docs
-area: documentation
-
-- Hid the unfinished feature demos page from the documentation sidebar while keeping its direct URL available.
diff --git a/changes/jellyfin-fast-subtitle-selection.md b/changes/jellyfin-fast-subtitle-selection.md
new file mode 100644
index 00000000..0bd9bec5
--- /dev/null
+++ b/changes/jellyfin-fast-subtitle-selection.md
@@ -0,0 +1,5 @@
+type: fixed
+area: jellyfin
+
+- Jellyfin playback now selects the Japanese subtitle track, and starts subtitle annotations, as soon as that track downloads instead of waiting for every other subtitle track. Tracks now download in parallel, so a slow embedded track Jellyfin has to extract no longer delays the primary subtitles.
+- Jellyfin episodes with image-based embedded subtitles (PGS, DVD, DVB) now auto-select the Japanese and English tracks. SubMiner no longer requests those tracks as text, and a subtitle track that fails to download no longer cancels selection of the others.
diff --git a/changes/jellyfin-review-audio-track.md b/changes/jellyfin-review-audio-track.md
new file mode 100644
index 00000000..f4eeffa4
--- /dev/null
+++ b/changes/jellyfin-review-audio-track.md
@@ -0,0 +1,4 @@
+type: fixed
+area: jellyfin
+
+- Timing review previews and mined card audio now use the audio track you are playing on Jellyfin direct-play streams, instead of the track Jellyfin marks as default.
diff --git a/changes/library-merge-and-move.md b/changes/library-merge-and-move.md
deleted file mode 100644
index a1668592..00000000
--- a/changes/library-merge-and-move.md
+++ /dev/null
@@ -1,6 +0,0 @@
-type: added
-area: stats
-
-- Library: duplicate cards for the same show can now be combined. Press "Select" above the library grid, tick the cards, and use "Merge Selected"; the dialog picks which entry to keep and moves every episode onto it. Sessions, mined cards, and watch time are preserved, the emptied entries disappear, and remembered title aliases keep future episodes on the merged card.
-- Library: episodes can be reassigned to another library entry from the "→" button on an episode row, which is the fix when one file lands under a stray title (e.g. an episode name parsed as the series). Manual assignments now survive later filename parsing, Jellyfin refreshes, and season repair. Local episodes in the same directory reuse a uniquely corrected destination unless they parse to a title that already has its own library entry, while conflicting seasons or manual destinations are not forced together. Emptying an entry this way removes it and returns to the grid.
-- Library: exact AniList title matches with compatible seasons fold duplicate cards automatically. Fuzzy same-AniList matches appear as dismissible "Possible duplicate" reviews instead of changing the library without confirmation; conflicting explicit seasons are left alone.
diff --git a/changes/linux-notification-in-place-replace.md b/changes/linux-notification-in-place-replace.md
deleted file mode 100644
index 39d9dd56..00000000
--- a/changes/linux-notification-in-place-replace.md
+++ /dev/null
@@ -1,4 +0,0 @@
-type: fixed
-area: notifications
-
-- Character dictionary progress notifications on Linux now update in place instead of flickering off and reappearing on every status change.
diff --git a/changes/mining-clip-range-snapshot.md b/changes/mining-clip-range-snapshot.md
deleted file mode 100644
index d31d6176..00000000
--- a/changes/mining-clip-range-snapshot.md
+++ /dev/null
@@ -1,4 +0,0 @@
-type: fixed
-area: anki
-
-- Mined audio and animated AVIF clips now capture the subtitle line that was actually mined. The clip range is snapshotted once at Yomitan lookup time (and reused for both audio and image), instead of each generator reading the live mpv subtitle when it starts — which clipped whatever line was on screen after slow audio extraction finished, producing too-short or misaligned AVIF clips.
diff --git a/changes/remove-package-size-reports.md b/changes/remove-package-size-reports.md
new file mode 100644
index 00000000..e21b3c44
--- /dev/null
+++ b/changes/remove-package-size-reports.md
@@ -0,0 +1,4 @@
+type: changed
+area: release
+
+- Removed package-size JSON reports from future releases and their CI size comparisons. Package-content validation remains enabled.
diff --git a/changes/stats-delete-fast-incremental.md b/changes/stats-delete-fast-incremental.md
deleted file mode 100644
index 76f27342..00000000
--- a/changes/stats-delete-fast-incremental.md
+++ /dev/null
@@ -1,9 +0,0 @@
-type: fixed
-area: stats
-
-- Stats deletes no longer freeze the stats dashboard: the delete worker module now resolves when running from source, so deletes actually run off the serving thread instead of silently falling back to it.
-- Deletes now subtract their exact contribution from lifetime summaries instead of rebuilding them from retained sessions, making delete cost proportional to what is deleted and preserving lifetime totals older than the session retention window.
-- If the delete worker crashes, the delete now retries on the current thread instead of failing.
-- Library merges, video moves, AniList reassignments, and `subminer stats cleanup -l` also stopped rebuilding lifetime summaries from retained sessions; they now recompute from per-episode history, so those operations are faster and no longer erase lifetime totals older than the session retention window.
-- Deleting content that contains very common words no longer rescans every occurrence of those words across the whole library; first/last-seen dates are refreshed with index seeks instead.
-- Session deletes on large databases dropped from minutes to milliseconds: an index on the subtitle-line event reference now prevents each deleted session event from scanning the whole subtitle-line table for foreign-key enforcement.
diff --git a/changes/stats-vocabulary-summary-totals.md b/changes/stats-vocabulary-summary-totals.md
deleted file mode 100644
index 4d48ddab..00000000
--- a/changes/stats-vocabulary-summary-totals.md
+++ /dev/null
@@ -1,8 +0,0 @@
-type: fixed
-area: stats
-
-- Fixed Vocabulary totals and charts counting only the first browsing page instead of all tracked vocabulary, without delaying the rest of the page.
-- New-word history now uses permanent daily lexical rollups that apply the same vocabulary filters as the totals and normalize legacy second/millisecond timestamps; versioned background rebuilds repair existing history across legacy rollup-state schemas without dropping playback writes or clearing watch-time, activity, efficiency, and library charts.
-- Calendar-day chart labels now preserve the recorded local date in time zones west of UTC.
-- Vocabulary summary cards and charts refresh automatically after the word exclusion list changes, and failed or unfinished loads use bounded retries before showing an inline error with a Retry control.
-- Rapid exclusion edits no longer race each other; writes are sent in order so a slower earlier save cannot overwrite a newer list.
diff --git a/config.example.jsonc b/config.example.jsonc
index 1408eab7..22640179 100644
--- a/config.example.jsonc
+++ b/config.example.jsonc
@@ -6,6 +6,32 @@
  */
 {
 
+  // ==========================================
+  // Subtitle Selection
+  // Select primary and secondary mpv subtitle tracks from the overlay.
+  // Hot-reload: enabling or disabling updates the session shortcut immediately.
+  // ==========================================
+  "subtitleSelection": {
+    "enabled": false // Use the SubMiner modal to select primary and secondary subtitle tracks. When enabled, its shortcut overrides mpv subtitle selection. Values: true | false
+  }, // Select primary and secondary mpv subtitle tracks from the overlay.
+
+  // ==========================================
+  // Japanese Subtitle Generation
+  // Generate timed Japanese subtitles from local audio using whisper.cpp.
+  // Configure an existing GGML model path or explicitly download a SubMiner-managed model.
+  // Hot-reload: settings apply to the next generation or model download.
+  // ==========================================
+  "subtitleGeneration": {
+    "whisperPath": "", // Optional path override for whisper.cpp. Leave empty to find whisper-cli on PATH.
+    "modelPath": "", // Path to an existing multilingual whisper.cpp GGML model. Leave empty to use a SubMiner-managed model. A configured path always takes precedence.
+    "managedModel": "small", // Multilingual whisper.cpp model to use when modelPath is empty. Download it explicitly from the generation modal or launcher. Values: tiny | tiny-q5_1 | tiny-q8_0 | base | base-q5_1 | base-q8_0 | small | small-q5_1 | small-q8_0 | medium | medium-q5_0 | medium-q8_0 | large-v1 | large-v2 | large-v2-q5_0 | large-v2-q8_0 | large-v3 | large-v3-q5_0 | large-v3-turbo | large-v3-turbo-q5_0 | large-v3-turbo-q8_0
+    "threads": 4, // Positive integer CPU thread count for whisper.cpp Japanese transcription.
+    "ffmpegPath": "", // Optional FFmpeg path override for audio extraction. Leave empty to find ffmpeg on PATH.
+    "ffprobePath": "", // Optional FFprobe path override for audio tracks and timing. Leave empty to find ffprobe on PATH.
+    "vadModelPath": "", // Path to a whisper.cpp Silero VAD model. Enables dialogue-focused generation while retaining uncertain audible sections, which may include songs. Leave empty to transcribe the full audio.
+    "vadPath": "" // Optional speech detector executable override. With vadModelPath configured, leave empty to find whisper-vad-speech-segments or vad-speech-segments on PATH.
+  }, // Generate timed Japanese subtitles from local audio using whisper.cpp.
+
   // ==========================================
   // Visible Overlay Auto-Start
   // Show the visible subtitle overlay automatically after managed mpv playback starts SubMiner.
@@ -206,6 +232,8 @@
     "openRuntimeOptions": "CommandOrControl+Shift+O", // Accelerator that opens the runtime options modal.
     "openJimaku": "Ctrl+Shift+J", // Accelerator that opens the Jimaku subtitle search modal.
     "openTsukihime": "Ctrl+Shift+T", // Accelerator that opens the TsukiHime subtitle search modal (configured secondary/Japanese primary tabs).
+    "openSubtitleSelection": "g-s", // Open subtitle selection when enabled. Use g-s to press g then s. Set null to unbind.
+    "openSubtitleGeneration": "Ctrl+Shift+G", // Accelerator that opens the standalone Japanese subtitle generation modal.
     "openSessionHelp": "CommandOrControl+Slash", // Accelerator that opens the session help / keybinding cheatsheet.
     "openControllerSelect": "Alt+C", // Accelerator that opens the controller selection and learn-mode modal.
     "openControllerDebug": "Alt+Shift+C", // Accelerator that opens the controller debug modal with live axis/button readouts.
@@ -523,7 +551,7 @@
   // ==========================================
   // AnkiConnect Integration
   // Automatic Anki updates and media generation options.
-  // Hot-reload: ankiConnect.ai.enabled, media.normalizeAudio/mirrorMpvVolume, knownWords, nPlusOne, fields.word/audio/image/sentence/miscInfo, behavior.autoUpdateNewCards, isLapis.sentenceCardModel, isKiku.fieldGrouping, and lapisKiku.wordCardKind update live while SubMiner is running.
+  // Hot-reload: ankiConnect.ai.enabled, media.normalizeAudio/mirrorMpvVolume/reviewTiming, knownWords, nPlusOne, fields.word/audio/wordAudio/image/sentence/miscInfo, behavior.autoUpdateNewCards, isLapis.sentenceCardModel, isKiku.fieldGrouping, isSenren.fieldGrouping, and lapisKiku.wordCardKind update live while SubMiner is running.
   // Shared AI provider transport settings are read from top-level ai and typically require restart.
   // Most other AnkiConnect settings still require restart.
   // ==========================================
@@ -544,6 +572,7 @@
     "fields": {
       "word": "Expression", // Card field for the mined word or expression text.
       "audio": "ExpressionAudio", // Card field that receives generated sentence audio.
+      "wordAudio": "ExpressionAudio", // Existing word-audio field read to time the frozen first frame of animated images. This mapping is only used for synchronization.
       "image": "Picture", // Card field that receives the captured screenshot or animated image.
       "sentence": "Sentence", // Card field that receives the source sentence text.
       "miscInfo": "MiscInfo", // Card field that receives the miscellaneous info pattern (see ankiConnect.metadata.pattern).
@@ -569,9 +598,10 @@
       "syncAnimatedImageToWordAudio": true, // For animated AVIF images, prepend a frozen first frame matching the existing word-audio duration so motion starts with sentence audio. Values: true | false
       "normalizeAudio": true, // Normalize generated sentence audio loudness during media extraction. Changes apply live. Values: true | false
       "mirrorMpvVolume": true, // Apply mpv's current software volume curve to generated sentence audio. Changes apply live. Values: true | false
+      "reviewTiming": false, // Review and preview subtitle media timing before SubMiner creates or enriches a mined card. Values: true | false
       "audioPadding": 0, // Seconds of padding appended to both ends of generated sentence audio and animated AVIF clips.
       "fallbackDuration": 3, // Fallback clip duration in seconds when subtitle timing data is unavailable.
-      "maxMediaDuration": 30 // Maximum allowed media clip duration in seconds.
+      "maxMediaDuration": 30 // Maximum allowed media clip duration in seconds. 0 disables the cap.
     }, // Media setting.
     "knownWords": {
       "highlightEnabled": false, // Enable fast local highlighting for words already known in Anki. Values: true | false
@@ -606,6 +636,11 @@
       "fieldGrouping": "disabled", // Kiku duplicate-card field grouping mode. Values: auto | manual | disabled
       "deleteDuplicateInAuto": true // When Kiku field grouping is "auto", delete the duplicate source card after grouping completes. Values: true | false
     }, // Is kiku setting.
+    "isSenren": {
+      "enabled": false, // Enable Senren-specific duplicate handling (scene-switching field grouping, including miscInfo grouping). Mutually exclusive with isKiku.enabled. Values: true | false
+      "fieldGrouping": "auto", // Senren duplicate-card field grouping mode (scene switching). Values: auto | manual | disabled
+      "deleteDuplicateInAuto": true // When Senren field grouping is "auto", delete the duplicate source card after grouping completes. Values: true | false
+    }, // Is senren setting.
     "lapisKiku": {
       "wordCardKind": "word-and-sentence" // Card-type flag SubMiner marks on Kiku/Lapis word cards. Only one flag is set at a time; the others are cleared. Requires isKiku.enabled or isLapis.enabled. Values: word-and-sentence | click | sentence | audio | none
     } // Lapis kiku setting.
@@ -634,6 +669,16 @@
     "maxSearchResults": 10 // Maximum TsukiHime search results returned.
   }, // TsukiHime subtitle search configuration for Japanese primary and configured secondary subtitles. No API key required.
 
+  // ==========================================
+  // TMDB
+  // TMDB (The Movie Database) metadata for live-action dramas and movies in the stats Library: posters, synopses, and grouping by show.
+  // Hot-reload: TMDB changes apply to the next TMDB request.
+  // ==========================================
+  "tmdb": {
+    "apiKey": "", // Your own TMDB API key or read access token for live-action posters and synopses in the stats Library. Release builds bundle a project key, so set this only to use your own quota or when running from source (free under Settings > API on themoviedb.org).
+    "apiKeyCommand": "" // Shell command that prints the TMDB API key to stdout. Used instead of apiKey to avoid storing the key in plain text.
+  }, // TMDB (The Movie Database) metadata for live-action dramas and movies in the stats Library: posters, synopses, and grouping by show.
+
   // ==========================================
   // YouTube Playback Settings
   // Defaults for managed subtitle language preferences and YouTube subtitle loading.
diff --git a/docs-site/.vitepress/config.ts b/docs-site/.vitepress/config.ts
index 122da831..42795fd1 100644
--- a/docs-site/.vitepress/config.ts
+++ b/docs-site/.vitepress/config.ts
@@ -1,6 +1,6 @@
 import { spawnSync } from 'node:child_process';
-import { existsSync, readFileSync, statSync } from 'node:fs';
-import { extname, join, posix, resolve, sep } from 'node:path';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
 import type { DefaultTheme, HeadConfig, TransformContext, UserConfig } from 'vitepress';
 
 const DOCS_HOSTNAME = 'https://docs.subminer.moe';
@@ -14,12 +14,6 @@ const PLAUSIBLE_INIT_SCRIPT = [
 
 type DocsChannel = 'stable-root' | 'stable-archive' | 'main';
 
-type VersionManifest = {
-  latestStable: string;
-  channels: Array<{ label: string; path: string }>;
-  versions: Array<{ version: string; path: string }>;
-};
-
 function optionalEnv(value: string | undefined): string | undefined {
   return value && value !== 'undefined' ? value : undefined;
 }
@@ -32,17 +26,6 @@ const docsSourceDir = optionalEnv(process.env.SUBMINER_DOCS_SOURCE_DIR) ?? proce
 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';
-const versionManifest = parseVersionManifest(process.env.SUBMINER_DOCS_VERSION_MANIFEST);
-const versionLinkOrigin =
-  optionalEnv(process.env.SUBMINER_DOCS_VERSION_LINK_ORIGIN) ?? 'production';
-
-function getLocalArchiveDir(): string {
-  return resolve(
-    optionalEnv(process.env.SUBMINER_DOCS_LOCAL_ARCHIVE_DIR) ??
-      join(docsSourceDir, '..', '.tmp/docs-versioned-site'),
-  );
-}
 
 function normalizeBase(value: string): string {
   if (!value || value === '/') return '/';
@@ -54,21 +37,6 @@ function normalizeChannel(value: string | undefined): DocsChannel {
   return 'stable-root';
 }
 
-function parseVersionManifest(value: string | undefined): VersionManifest {
-  if (!value || value === 'undefined') {
-    return {
-      latestStable,
-      channels: [
-        { label: 'Latest stable', path: '/' },
-        { label: 'main', path: '/main/' },
-      ],
-      versions: [{ version: latestStable, path: `/v/${latestStable.replace(/^v/, '')}/` }],
-    };
-  }
-
-  return JSON.parse(value) as VersionManifest;
-}
-
 function withDocsBase(path: string): string {
   if (/^[a-z]+:\/\//i.test(path)) return path;
   const normalizedPath = path.startsWith('/') ? path : `/${path}`;
@@ -164,137 +132,16 @@ function filterSidebar(items: DefaultTheme.SidebarItem[]): DefaultTheme.SidebarI
     .filter((item): item is DefaultTheme.SidebarItem => Boolean(item));
 }
 
-function versionSwitchLink(path: string): string {
-  if (/^[a-z]+:\/\//i.test(path)) return path;
-  const normalizedPath = path.startsWith('/') ? path : `/${path}`;
-  if (versionLinkOrigin === 'local') return localVersionSwitchLink(normalizedPath);
-  return `${DOCS_HOSTNAME}${normalizedPath}`;
-}
-
-function localVersionSwitchLink(path: string): string {
-  if (base === '/') return path;
-
-  const basePath = base.replace(/\/$/, '');
-  const targetPath = path === '/' ? '/' : path.replace(/\/$/, '');
-  const relativePath = posix.relative(basePath, targetPath) || '.';
-
-  return path.endsWith('/') ? `${relativePath}/` : relativePath;
-}
-
-function shouldHandleLocalVersionRoute(pathname: string): boolean {
-  if (base !== '/' || channel !== 'stable-root') return false;
-  return /^\/main(?:\/|$)/.test(pathname) || /^\/v\/[^/]+(?:\/|$)/.test(pathname);
-}
-
-function contentTypeForPath(path: string): string {
-  switch (extname(path)) {
-    case '.css':
-      return 'text/css; charset=utf-8';
-    case '.gif':
-      return 'image/gif';
-    case '.ico':
-      return 'image/x-icon';
-    case '.jpg':
-    case '.jpeg':
-      return 'image/jpeg';
-    case '.js':
-    case '.mjs':
-      return 'text/javascript; charset=utf-8';
-    case '.json':
-    case '.jsonc':
-      return 'application/json; charset=utf-8';
-    case '.mp4':
-      return 'video/mp4';
-    case '.png':
-      return 'image/png';
-    case '.svg':
-      return 'image/svg+xml';
-    case '.ttf':
-      return 'font/ttf';
-    case '.webm':
-      return 'video/webm';
-    case '.woff':
-      return 'font/woff';
-    case '.woff2':
-      return 'font/woff2';
-    case '.xml':
-      return 'application/xml; charset=utf-8';
-    default:
-      return 'text/html; charset=utf-8';
-  }
-}
-
-function isFile(path: string): boolean {
-  try {
-    return statSync(path).isFile();
-  } catch {
-    return false;
-  }
-}
-
-function archiveFileForPathname(pathname: string): string | null {
-  if (!shouldHandleLocalVersionRoute(pathname)) return null;
-
-  const localArchiveDir = getLocalArchiveDir();
-  const routePath = decodeURIComponent(pathname).replace(/^\/+/, '');
-  const filePath = resolve(localArchiveDir, routePath);
-  if (filePath !== localArchiveDir && !filePath.startsWith(`${localArchiveDir}${sep}`)) {
-    return null;
-  }
-
-  const candidates = pathname.endsWith('/')
-    ? [join(filePath, 'index.html')]
-    : extname(filePath)
-      ? [filePath]
-      : [`${filePath}.html`, join(filePath, 'index.html')];
-
-  return candidates.find(isFile) ?? null;
-}
-
-function serveLocalArchiveRoute(pathname: string, response: DevServerResponse): boolean {
-  if (
-    (optionalEnv(process.env.SUBMINER_DOCS_VERSION_LINK_ORIGIN) ?? versionLinkOrigin) !== 'local'
-  ) {
-    return false;
-  }
-
-  const filePath = archiveFileForPathname(pathname);
-  if (!filePath) return false;
-
-  response.statusCode = 200;
-  response.setHeader('Content-Type', contentTypeForPath(filePath));
-  response.end(readFileSync(filePath));
-  return true;
-}
-
-type DevServerResponse = {
-  statusCode: number;
-  setHeader(name: string, value: string): void;
-  end(chunk?: string | Uint8Array): void;
-};
-
-const versionItems = [
-  {
-    text: `Latest stable (${versionManifest.latestStable})`,
-    link: versionSwitchLink('/'),
-    target: '_self',
-    noIcon: true,
-  },
-  ...versionManifest.channels
-    .filter((entry) => entry.label !== 'Latest stable')
-    .map((entry) => ({
-      text: entry.label,
-      link: versionSwitchLink(entry.path),
-      target: '_self',
-      noIcon: true,
-    })),
-  ...versionManifest.versions.map((entry) => ({
-    text: entry.version,
-    link: versionSwitchLink(entry.path),
-    target: '_self',
-    noIcon: true,
-  })),
-];
+// Version navigation targets other builds (root, `/main/`, `/versions`), so it links to
+// production by absolute URL: base-relative links would stay inside this build, and
+// `target: '_self'` makes the VitePress router do a full page load. The list is
+// deliberately static; the full release list lives on the root-only `/versions` page
+// so frozen `/v/<version>/` archives never need a rebuild when a new tag ships.
+const versionItems: DefaultTheme.NavItemWithLink[] = [
+  { text: 'Latest stable', link: `${DOCS_HOSTNAME}/` },
+  { text: 'main', link: `${DOCS_HOSTNAME}/main/` },
+  { text: 'All versions', link: `${DOCS_HOSTNAME}/versions` },
+].map((item) => ({ ...item, target: '_self', noIcon: true }));
 
 function sitemapUrlToPage(url: string): string {
   const route = url.replace(/\.html$/, '').replace(/^\/+|\/+$/g, '');
@@ -336,7 +183,7 @@ const nav: DefaultTheme.NavItem[] = [
   { text: 'Configuration', link: '/configuration' },
   { text: 'Changelog', link: '/changelog' },
   { text: 'Troubleshooting', link: '/troubleshooting' },
-  { text: docsVersion ?? (channel === 'main' ? 'main' : latestStable), items: versionItems },
+  { text: docsVersion ?? 'main', items: versionItems },
 ];
 
 const sidebar: DefaultTheme.SidebarItem[] = [
@@ -369,6 +216,7 @@ const sidebar: DefaultTheme.SidebarItem[] = [
       { text: 'Jellyfin', link: '/jellyfin-integration' },
       { text: 'YouTube', link: '/youtube-integration' },
       { text: 'Jimaku', link: '/jimaku-integration' },
+      { text: 'Subtitle Generation', link: '/subtitle-generation' },
       { text: 'TsukiHime', link: '/tsukihime-integration' },
       { text: 'AniList', link: '/anilist-integration' },
       { text: 'AniSkip', link: '/aniskip-integration' },
@@ -393,33 +241,6 @@ const config: UserConfig = {
     'SubMiner: an MPV immersion-mining overlay with Yomitan and AnkiConnect integration.',
   base,
   ...(outDir ? { outDir } : {}),
-  vite: {
-    plugins: [
-      {
-        name: 'subminer-docs-local-version-redirects',
-        configureServer(server) {
-          server.middlewares.use((request, response, next) => {
-            const requestUrl = new URL(request.url ?? '/', 'http://localhost');
-            if (serveLocalArchiveRoute(requestUrl.pathname, response)) {
-              return;
-            }
-
-            if (!shouldHandleLocalVersionRoute(requestUrl.pathname)) {
-              next();
-              return;
-            }
-
-            response.statusCode = 302;
-            response.setHeader(
-              'Location',
-              `${DOCS_HOSTNAME}${requestUrl.pathname}${requestUrl.search}`,
-            );
-            response.end();
-          });
-        },
-      },
-    ],
-  },
   head: [
     ['link', { rel: 'preconnect', href: PLAUSIBLE_PROXY_HOSTNAME }],
     [
diff --git a/docs-site/.vitepress/theme/components/StatusLine.vue b/docs-site/.vitepress/theme/components/StatusLine.vue
index 0d523cc6..56bc77bf 100644
--- a/docs-site/.vitepress/theme/components/StatusLine.vue
+++ b/docs-site/.vitepress/theme/components/StatusLine.vue
@@ -1,10 +1,10 @@
 <script setup>
 import { useRoute, useData } from 'vitepress';
-import { computed } from 'vue';
-import { formatStatusLineFilePath } from '../status-line';
+import { computed, onMounted, ref } from 'vue';
+import { formatStatusLineDate, formatStatusLineFilePath } from '../status-line';
 
 const route = useRoute();
-const { page, frontmatter } = useData();
+const { frontmatter } = useData();
 
 const mode = computed(() => {
   const layout = frontmatter.value.layout;
@@ -23,10 +23,10 @@ const section = computed(() => {
   return parts[0] || 'root';
 });
 
-const lastUpdated = computed(() => {
-  if (!page.value.lastUpdated) return '';
-  const date = new Date(page.value.lastUpdated);
-  return date.toISOString().slice(0, 10);
+// Set on the client only, so the prerendered HTML never bakes in the build date.
+const today = ref('');
+onMounted(() => {
+  today.value = formatStatusLineDate(new Date());
 });
 </script>
 
@@ -40,8 +40,8 @@ const lastUpdated = computed(() => {
     <div class="tui-statusline__right">
       <span class="tui-statusline__section">{{ section }}</span>
       <span class="tui-statusline__sep"></span>
-      <span v-if="lastUpdated" class="tui-statusline__date">{{ lastUpdated }}</span>
-      <span v-if="lastUpdated" class="tui-statusline__sep"></span>
+      <span v-if="today" class="tui-statusline__date">{{ today }}</span>
+      <span v-if="today" class="tui-statusline__sep"></span>
       <span class="tui-statusline__branch">GPL-3.0</span>
     </div>
   </footer>
diff --git a/docs-site/.vitepress/theme/status-line.test.ts b/docs-site/.vitepress/theme/status-line.test.ts
index 61317fd4..4d33e780 100644
--- a/docs-site/.vitepress/theme/status-line.test.ts
+++ b/docs-site/.vitepress/theme/status-line.test.ts
@@ -1,5 +1,5 @@
 import { expect, test } from 'bun:test';
-import { formatStatusLineFilePath } from './status-line';
+import { formatStatusLineDate, formatStatusLineFilePath } from './status-line';
 
 test('status line file path formats root home as index markdown', () => {
   expect(formatStatusLineFilePath('/')).toBe('index.md');
@@ -10,7 +10,9 @@ 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');
+});
+
+test('status line date uses the local calendar day, zero padded', () => {
+  expect(formatStatusLineDate(new Date(2026, 0, 5, 23, 59))).toBe('2026-01-05');
 });
diff --git a/docs-site/.vitepress/theme/status-line.ts b/docs-site/.vitepress/theme/status-line.ts
index e473e54c..e47bd82e 100644
--- a/docs-site/.vitepress/theme/status-line.ts
+++ b/docs-site/.vitepress/theme/status-line.ts
@@ -2,3 +2,10 @@ export function formatStatusLineFilePath(routePath: string): string {
   if (routePath === '/') return 'index.md';
   return `${routePath.replace(/^\/|\/$/g, '')}.md`;
 }
+
+// Local calendar date as YYYY-MM-DD (toISOString would give the UTC date).
+export function formatStatusLineDate(date: Date): string {
+  const month = String(date.getMonth() + 1).padStart(2, '0');
+  const day = String(date.getDate()).padStart(2, '0');
+  return `${date.getFullYear()}-${month}-${day}`;
+}
diff --git a/docs-site/README.md b/docs-site/README.md
index 16d10ef4..85d0061c 100644
--- a/docs-site/README.md
+++ b/docs-site/README.md
@@ -1,4 +1,4 @@
-# SubMiner Docs
+# SubMiner docs
 
 In-repo VitePress documentation source for SubMiner.
 
@@ -40,8 +40,23 @@ The public docs root is stable-only:
 - `/` serves the latest stable release docs.
 - `/main/` serves development docs from `main`.
 - `/v/<version>/` serves stable release archives.
+- `/versions` (root build only) lists every published version.
 - 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.
+Only `/` is indexable. `/main/` and every `/v/<version>/` page carries a self-referential canonical plus `noindex,follow`, repeated as an `X-Robots-Tag` header (by the generated `_headers` file for `/main/`, by the archive function for `/v/`). 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.
+
+### Stable archives in R2
+
+`/v/<version>/` archives are not part of the Pages deployment. Each one is built once, uploaded to an R2 bucket under `v/<version>/`, and served by the Pages Function in `functions/v/[[path]].ts`. Each deploy builds only archives the bucket is missing (an archive counts as present once its `_archive.json` marker exists), plus the root and `/main/` builds. Archive nav links to `/versions` instead of listing releases, so a new tag never invalidates old archives.
+
+To re-render archives on purpose (theme change, docs fix), run the `Docs Pages` workflow manually with `rebuild_archives` set to comma-separated tags or `all`.
+
+One-time setup:
+
+- R2 bucket for archives; its name goes in the `DOCS_ARCHIVE_R2_BUCKET` repository variable.
+- R2 API token with Object Read & Write on that bucket; its S3 credentials go in the `DOCS_ARCHIVE_R2_ACCESS_KEY_ID` and `DOCS_ARCHIVE_R2_SECRET_ACCESS_KEY` repository secrets.
+- Pages project: Settings > Bindings > R2 bucket, variable name `DOCS_ARCHIVES`, pointing at the same bucket.
+
+The first deploy after setup builds and uploads every stable archive; later deploys only add new tags.
diff --git a/docs-site/anilist-integration.md b/docs-site/anilist-integration.md
index 4852f46c..dab55b0c 100644
--- a/docs-site/anilist-integration.md
+++ b/docs-site/anilist-integration.md
@@ -1,133 +1,68 @@
-# AniList Integration
+# AniList integration
 
-SubMiner can sync your watch progress to [AniList](https://anilist.co) automatically. When you finish an episode, SubMiner detects the title and episode number from the filename, finds the matching AniList entry, and updates your progress via the GraphQL API. Failed updates are retried with exponential backoff in the background.
-
-AniList data also powers two additional features: [cover art](#cover-art) for the stats dashboard and the [Character Dictionary](/character-dictionary) for in-overlay name lookup.
-
-[AniList](https://anilist.co) is a free website for tracking which anime you have watched. An **access token** is a private key SubMiner stores so it can update your list on your behalf - you approve it once during setup, and you never paste a password into SubMiner.
+SubMiner updates your [AniList](https://anilist.co) watch progress when you finish an episode. The same connection supplies cover art for the stats dashboard and names for the [character dictionary](/character-dictionary).
 
 ## Setup
 
-AniList integration is opt-in. To enable it:
+1. Set `anilist.enabled` to `true`:
 
-1. Set `anilist.enabled` to `true` in your config.
-2. Leave `anilist.accessToken` empty and restart SubMiner (or run `--anilist-setup`).
-3. Approve access in the AniList authorization page.
-4. The callback returns to SubMiner via the `subminer://anilist-setup?...` protocol URL, and SubMiner stores the token automatically.
+   ```jsonc
+   {
+     "anilist": {
+       "enabled": true,
+     },
+   }
+   ```
 
-```jsonc
-{
-  "anilist": {
-    "enabled": true,
-    "accessToken": "",
-  },
-}
-```
+2. Restart SubMiner. With no token stored, it opens the AniList setup window. You can also open it from the tray (**Configure AniList**) or with `subminer app --anilist-setup`.
+3. Approve access on the AniList page. SubMiner receives the token through a `subminer://` link and stores it encrypted.
 
-The access token is encrypted at rest using Electron's `safeStorage` API. On Linux this defaults to `gnome-libsecret`; override the backend with `--password-store=<backend>` (for example `--password-store=basic_text`).
+If the setup window does not render, SubMiner opens the authorization page in your browser instead. To skip the flow entirely, paste a token into `anilist.accessToken`.
 
-If the embedded auth UI fails to render, SubMiner opens the authorize URL in your default browser and shows fallback instructions in-app.
+On Linux, the token is stored with `gnome-libsecret` by default. If your keyring is unavailable, start it (gnome-keyring or KWallet) or launch SubMiner with `--password-store=basic_text`.
 
-::: tip
-You can also set `anilist.accessToken` directly in config to skip the setup flow entirely. When blank, SubMiner uses the locally stored encrypted token.
-:::
+## How updates work
 
-## How Tracking Works
+An episode counts as watched after 85% of its length and at least 10 minutes of playback. SubMiner then:
 
-SubMiner monitors playback and triggers an AniList progress update when an episode is considered "watched" -- at least 85% of the episode duration viewed and a minimum of 10 minutes watched.
+1. Reads the title, season, and episode from the file name and folder. Install [guessit](https://github.com/guessit-io/guessit) for better parsing. A folder named `Season 2` is a strong season hint.
+2. Finds the matching AniList entry. For season 2 and later, it follows the show's sequels.
+3. Sets your progress to that episode and marks the entry Watching, or Completed on the final episode.
 
-The update flow:
+The show must already be on your Planning or Watching list. SubMiner does not add new entries, and it never lowers your progress.
 
-1. **Title detection** -- SubMiner extracts the anime title, season, and episode number from the media filename and path. Season folders such as `Season 2` are treated as a strong season signal. SubMiner tries [`guessit`](https://github.com/guessit-io/guessit) first for accurate parsing, then falls back to an internal filename parser if guessit is unavailable.
-2. **AniList search** -- The base title (with any `Season N` / `SN` marker stripped) is searched against the AniList GraphQL API, and SubMiner picks the best match by comparing titles (romaji, English, native, synonyms) and filtering by episode count. AniList has no notion of numbered seasons -- sequels are separate entries with their own titles (`Zoku`, `Kan`, `2nd Season`), so searching `<title> Season 3` finds nothing. For season 2 and later, SubMiner instead walks `SEQUEL` relations from the season 1 entry, preferring the TV line, and falls back to ordering the franchise's TV entries by air date when the relation chain is incomplete. If neither locates the season, SubMiner **skips the update** rather than writing progress to the season 1 entry, and tells you to pin the right entry with a [character dictionary override](/character-dictionary#correcting-anilist-matches).
-3. **Progress check** -- SubMiner fetches your current list entry for the matched media. The media must already be in Planning or Watching; otherwise SubMiner shows an MPV message explaining that the update is not possible. If your recorded progress already meets or exceeds the detected episode, the update is skipped.
-4. **Mutation** -- A `SaveMediaListEntry` mutation sets the new progress and marks the entry as `CURRENT`, or `COMPLETED` when the watched episode is the final episode of the season (the "already at this progress" skip is bypassed for the final episode so completion still lands).
+Failed updates are saved and retried in the background, up to 8 times with growing delays. The queue survives restarts.
 
-## Update Queue and Retry
+## Fixing a wrong match
 
-Failed AniList updates are persisted to a retry queue on disk and retried with exponential backoff.
+If a cover or title in the stats Library is wrong, open the title and use **Change AniList Entry**.
 
-| Parameter        | Value      |
-| ---------------- | ---------- |
-| Initial backoff  | 30 seconds |
-| Maximum backoff  | 6 hours    |
-| Maximum attempts | 8          |
-| Queue capacity   | 500 items  |
+If SubMiner cannot find a later season, it skips the update rather than writing progress to season 1. Pin the right entry with the character dictionary's AniList override. See [Character dictionary](/character-dictionary).
 
-After 8 failed attempts, the update is moved to a dead-letter queue and no longer retried automatically. The queue is persisted across restarts so no updates are lost if SubMiner exits before a retry succeeds.
+## Commands
 
-Use `--anilist-retry-queue` to manually process one ready item from the queue.
+| Command                              | What it does                            |
+| ------------------------------------ | --------------------------------------- |
+| `subminer app --anilist-setup`       | Open the AniList setup window           |
+| `subminer app --anilist-status`      | Show token state and retry queue counts |
+| `subminer app --anilist-logout`      | Remove the stored token                 |
+| `subminer app --anilist-retry-queue` | Retry one queued update now             |
 
-## Cover Art
+## Options
 
-SubMiner fetches cover art from AniList for display in the stats dashboard. When a new video starts playing, the cover art fetcher:
+| Key                   | What it does                                                  |
+| --------------------- | ------------------------------------------------------------- |
+| `anilist.enabled`     | Turns on progress updates.                                    |
+| `anilist.accessToken` | Token override. Leave empty to use the token stored by setup. |
 
-1. Checks the local database for cached art.
-2. If missing, parses the media title (guessit then fallback) and searches the AniList API.
-3. Downloads the cover image from the AniList CDN and caches it locally (both URL and blob).
-4. Stores AniList metadata (romaji/English titles, total episodes) alongside the cover for dashboard display.
-
-A no-match result is cached for 5 minutes before SubMiner retries, preventing repeated API calls for unrecognized media.
-
-If the automatic match is wrong, use **Change AniList Entry** on a title in the stats Library. Relinking rewrites the cached art for every episode of that title, and both the detail view and the Library grid pick up the new cover right away: the grid refetches after a relink, and cover responses carry an ETag and are revalidated on each request instead of being cached for a day.
-
-## Rate Limiting
-
-All AniList API calls go through a shared rate limiter that enforces a sliding window of 20 requests per minute. The limiter also reads AniList's `X-RateLimit-Remaining` and `Retry-After` response headers and pauses requests when the server signals throttling. This applies to both episode tracking and cover art fetching.
-
-## Configuration Reference
-
-```jsonc
-{
-  "anilist": {
-    "enabled": true,
-    "accessToken": "",
-    "characterDictionary": {
-      "maxLoaded": 3,
-      "profileScope": "all",
-      "collapsibleSections": {
-        "description": false,
-        "characterInformation": false,
-        "voicedBy": false,
-      },
-    },
-  },
-}
-```
-
-| Option                                      | Values                  | Description                                                                                                  |
-| ------------------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------ |
-| `enabled`                                   | `true`, `false`         | Enable AniList post-watch progress updates (default: `false`)                                                |
-| `accessToken`                               | string                  | Explicit AniList access token override; when blank, SubMiner uses the stored encrypted token (default: `""`) |
-| `characterDictionary.maxLoaded`             | number                  | Number of recent media snapshots kept in the merged dictionary (default: `3`)                                |
-| `characterDictionary.refreshTtlHours`       | number                  | Hours before a cached media snapshot is refreshed (default: `168`, clamped to 1–8760)                        |
-| `characterDictionary.evictionPolicy`        | `"delete"`, `"disable"` | What happens to snapshots evicted beyond `maxLoaded` (default: `"delete"`)                                   |
-| `characterDictionary.profileScope`          | `"all"`, `"active"`     | Apply dictionary to all Yomitan profiles or only the active one                                              |
-| `characterDictionary.collapsibleSections.*` | `true`, `false`         | Control which dictionary entry sections start expanded                                                       |
-
-There is no `characterDictionary.enabled` key: character dictionary sync is enabled by `subtitleStyle.nameMatchEnabled`. See the [Character Dictionary](/character-dictionary) page for full details on the character dictionary feature, including name generation, matching, auto-sync lifecycle, and dictionary entry format.
-
-## CLI Commands
-
-| Command                 | Description                                                   |
-| ----------------------- | ------------------------------------------------------------- |
-| `--anilist-setup`       | Open AniList setup/auth flow helper window                    |
-| `--anilist-status`      | Print current token resolution state and retry queue counters |
-| `--anilist-logout`      | Clear stored AniList token from local persisted state         |
-| `--anilist-retry-queue` | Process one ready retry queue item immediately                |
+Character dictionary settings live under `anilist.characterDictionary` and are covered on the [Character dictionary](/character-dictionary) page. See [Configuration](/configuration#anilist) for defaults.
 
 ## Troubleshooting
 
-- **Updates not triggering:** Confirm `anilist.enabled` is `true`. SubMiner requires at least 85% of the episode watched and a minimum of 10 minutes. Short episodes or partial watches will not trigger an update.
-- **Update not possible:** Add the season to your AniList Planning or Watching list first. SubMiner will not create new AniList list entries automatically.
-- **Wrong episode or title matched:** Detection quality is best when `guessit` is installed and on your `PATH`. Without it, SubMiner falls back to internal filename parsing which can be less accurate with unusual naming conventions.
-- **Token issues:** Run `--anilist-status` to check token state. If the token is invalid or expired, run `--anilist-setup` or `--anilist-logout` and re-authenticate.
-- **Updates failing repeatedly:** Run `--anilist-status` to see retry queue counters. Items that fail 8 times are moved to the dead-letter queue. Check network connectivity and AniList API status.
-- **Cover art missing:** Cover art is fetched on a best-effort basis using title matching. If the filename is hard to parse, the search may return no results. The fetcher retries after 5 minutes.
-- **Encryption unavailable on Linux:** If you see warnings about safeStorage, try `--password-store=basic_text` as a workaround, or ensure your desktop keyring (gnome-keyring, KWallet) is running.
+**No update after an episode.** Check that `anilist.enabled` is `true` and that you watched at least 85% of the episode.
 
-## Related
+**"AniList update not possible."** Add the show to your Planning or Watching list, then mark the episode watched again.
 
-- [Character Dictionary](/character-dictionary) -- AniList-powered character name dictionary for Yomitan
-- [Configuration Reference](/configuration) -- full config options
-- [Jellyfin Integration](/jellyfin-integration) -- media server integration
+**Wrong show or episode.** Install guessit and make sure it is on your `PATH`. Unusual file names parse poorly without it.
+
+**Token errors.** Run `subminer app --anilist-status`. If the token is invalid, run `--anilist-logout`, then `--anilist-setup`.
diff --git a/docs-site/aniskip-integration.md b/docs-site/aniskip-integration.md
index fc9bc230..e02071f4 100644
--- a/docs-site/aniskip-integration.md
+++ b/docs-site/aniskip-integration.md
@@ -1,53 +1,39 @@
-# AniSkip Integration
+# AniSkip integration
 
-SubMiner integrates with [AniSkip](https://aniskip.com) to automatically detect anime intro intervals and let you skip them with a single key press.
-
-Intro detection runs in the SubMiner app over the mpv IPC socket. It is available whenever the overlay is connected to mpv - not just at launch - and covers every local file loaded during an mpv session, including playlist advances.
+SubMiner looks up opening timestamps on [AniSkip](https://aniskip.com) so you can skip an anime's intro with one key.
 
 ## Setup
 
-AniSkip is enabled by default. Disable it or change the skip key in your config:
+AniSkip is on by default. To turn it off or change the key:
 
 ```jsonc
 {
   "mpv": {
-    "aniskipEnabled": true, // default: true
+    "aniskipEnabled": true,
     "aniskipButtonKey": "TAB",
   },
 }
 ```
 
-Both settings hot-reload: changing them in your config takes effect immediately without restarting playback or mpv.
-
-For best title and episode detection, install [`guessit`](https://github.com/guessit-io/guessit):
+Both settings apply immediately, without restarting mpv. For better title and episode detection, install [guessit](https://github.com/guessit-io/guessit):
 
 ```bash
 python3 -m pip install --user guessit
 ```
 
-Without `guessit`, SubMiner falls back to an internal filename parser which handles most common naming conventions but may miss unusual formats.
+## Usage
 
-## How It Works
+When a local file loads, SubMiner reads the title and episode from the file name, finds the show on MyAnimeList, and asks AniSkip for the intro's timestamps. Streams and URLs are skipped.
 
-On each local file load:
+If AniSkip has an intro, SubMiner adds `AniSkip Intro Start` and `AniSkip Intro End` chapters. When the intro starts, mpv shows "You can skip by pressing TAB" (with your key) for 3 seconds. Press the key any time during the intro to jump to its end.
 
-1. SubMiner infers the anime title, season, and episode number from the filename and path (using `guessit` if available, otherwise the built-in parser). Remote URLs are skipped entirely.
-2. The title is matched against MyAnimeList to resolve a MAL id.
-3. SubMiner queries the AniSkip API for an OP skip interval for that MAL id and episode.
-4. If an interval is found, SubMiner adds `AniSkip Intro Start` and `AniSkip Intro End` chapter markers to the current file and binds the skip key (`mpv.aniskipButtonKey`, default `TAB`).
-5. At the start of the intro, an OSD prompt appears for 3 seconds: `You can skip by pressing TAB` (reflects your configured key). Pressing the key at any point during the intro seeks to the intro end.
-
-When a custom key (other than `TAB` or `y-k`) is configured, the legacy `y-k` chord is also bound as a fallback skip trigger.
-
-Results are cached per file for the app session; only definitive "no intro found" results are cached, so transient lookup failures are retried on the next file load. Reload detection is also handled: if mpv reloads the same file, SubMiner re-applies the chapter markers without a new API lookup.
+With a custom key other than `TAB` or `y-k`, `y-k` also skips.
 
 ## Triggering from mpv
 
-You can trigger AniSkip actions from mpv script-messages:
+| Command                                   | What it does                                            |
+| ----------------------------------------- | ------------------------------------------------------- |
+| `script-message subminer-skip-intro`      | Skip to the end of the intro                            |
+| `script-message subminer-aniskip-refresh` | Look up the current file again, ignoring cached results |
 
-| 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.
+Use `subminer-aniskip-refresh` after a lookup failed or matched the wrong show.
diff --git a/docs-site/anki-integration.md b/docs-site/anki-integration.md
index d64c8c02..785e9aae 100644
--- a/docs-site/anki-integration.md
+++ b/docs-site/anki-integration.md
@@ -1,50 +1,34 @@
-# Anki Integration
+# Anki integration
 
-SubMiner uses the [AnkiConnect](https://ankiweb.net/shared/info/2055492159) add-on to create and update Anki cards with sentence context, audio, and screenshots.
-This project is built primarily for [Kiku](https://kiku.youyoumu.my.id/) and [Lapis](https://github.com/donkuri/lapis) note types, including sentence-card and field-grouping behavior.
+SubMiner talks to Anki through the [AnkiConnect](https://ankiweb.net/shared/info/2055492159) add-on. It fills new cards with the sentence, an audio clip, and a screenshot, and can create sentence cards and merge duplicate words. It is built for the [Lapis](https://github.com/donkuri/lapis), [Kiku](https://kiku.youyoumu.my.id/), and [Senren](https://github.com/BrenoAqua/Senren) note types, but works with any note type once you map its fields.
 
-::: tip New to these terms?
-
-- **Anki** is the flashcard app where your study cards live.
-- **AnkiConnect** is a free add-on that lets other programs (like SubMiner) talk to Anki over a local connection. SubMiner needs it installed to add or edit cards.
-- A **note type** (also called a "model") is the template that defines what a card looks like - for example the Kiku or Lapis templates many Japanese learners use.
-- A **field** is one labeled slot in that template, such as `Sentence`, `Expression`, or `Picture`. SubMiner fills these fields when it mines a card.
-  :::
+For the day-to-day flow, see [Mining workflow](/mining-workflow). Every key on this page, with its default, is listed in the [AnkiConnect config reference](/configuration#ankiconnect).
 
 ## Prerequisites
 
 1. Install [Anki](https://apps.ankiweb.net/).
-2. Install the [AnkiConnect](https://ankiweb.net/shared/info/2055492159) add-on (code: `2055492159`).
-3. Keep Anki running while using SubMiner.
+2. Install AnkiConnect (add-on code `2055492159`).
+3. Install FFmpeg and make sure it is on your `PATH`. SubMiner uses it for audio and images.
+4. Keep Anki running while you mine.
 
-AnkiConnect listens on `http://127.0.0.1:8765` by default. If you changed the port in AnkiConnect's settings, update `ankiConnect.url` in your SubMiner config.
+If you changed AnkiConnect's port, set `ankiConnect.url` to match.
 
-## Auto-Enrichment Transport
+## How cards get filled
 
-When you add a word via Yomitan, SubMiner detects the new card and fills in the sentence, audio, image, and translation fields automatically. Two detection methods are available:
+When Yomitan adds a note, SubMiner fills the sentence, audio, image, and MiscInfo fields. It finds new notes in one of two ways:
 
-**Proxy mode** (default) - SubMiner runs a local _proxy_: a small middleman server that sits between Yomitan and Anki. Yomitan sends new cards to SubMiner, SubMiner enriches them, then passes them along to Anki. This makes enrichment instant.
+- **Proxy (default).** SubMiner runs a local AnkiConnect-compatible server. Yomitan sends notes through it, and SubMiner fills each one right after Anki accepts it.
+- **Polling.** With `ankiConnect.proxy.enabled` set to `false`, SubMiner asks AnkiConnect for recently added notes every `ankiConnect.pollingRate` milliseconds.
 
-**Polling mode** (fallback, when the proxy is disabled) - SubMiner asks AnkiConnect every few seconds whether any new cards were added, then enriches them. Simpler setup, but with a short delay (~3 seconds).
+Set `ankiConnect.behavior.autoUpdateNewCards` to `false` to stop automatic filling and update cards by hand with `Ctrl/Cmd+V` instead.
 
-Use proxy mode if you want immediate enrichment. Use polling mode if your Yomitan instance is external (browser-based) or you prefer minimal configuration.
+`ankiConnect.deck` limits enrichment and duplicate checks to one deck. If it is empty, SubMiner uses Yomitan's mining deck when it can read it, and otherwise searches all decks.
 
-In both modes, the enrichment workflow is the same:
-
-1. Checks if a duplicate expression already exists (for field grouping).
-2. Updates the sentence field with the current subtitle.
-3. Generates and uploads audio and image media.
-4. Fills the translation field from the secondary subtitle or AI.
-5. Writes metadata to the miscInfo field.
-
-Polling mode uses the query `"deck:<ankiConnect.deck>" added:1` to find recently added cards. If no deck is configured, it searches all decks (`added:1`). In Settings, the AnkiConnect deck dropdown auto-fills and persists Yomitan's current mining deck when available, then falls back to the decks reported by AnkiConnect; stats-dashboard mining also falls back to Yomitan's mining deck when `ankiConnect.deck` is empty.
-Known-word sync scope is controlled by `ankiConnect.knownWords.decks`.
-
-### Proxy Mode Setup (Yomitan / Texthooker)
+### Proxy mode setup (Yomitan / texthooker) {#proxy-mode-setup-yomitan-texthooker}
 
 ```jsonc
 "ankiConnect": {
-  "url": "http://127.0.0.1:8765", // real AnkiConnect
+  "url": "http://127.0.0.1:8765",
   "proxy": {
     "enabled": true,
     "host": "127.0.0.1",
@@ -54,363 +38,183 @@ Known-word sync scope is controlled by `ankiConnect.knownWords.decks`.
 }
 ```
 
-Then point Yomitan/clients to `http://127.0.0.1:8766` instead of `8765`.
+Clients must send notes to the proxy (`http://127.0.0.1:8766` here), not to AnkiConnect directly.
 
-When SubMiner loads the bundled Yomitan extension, it also attempts to update the **currently active Yomitan profile**'s Anki server to the active SubMiner endpoint (falling back to `profiles[0]` if the active-profile index is invalid):
+- **Bundled Yomitan.** SubMiner sets the active Yomitan profile's Anki server for you. With the proxy on, it always points the profile at the proxy. With the proxy off, it sets `ankiConnect.url`, but only if the profile's server is blank or the stock `http://127.0.0.1:8765`.
+- **Browser Yomitan or other clients.** Set the Anki server to the proxy URL yourself. To leave your main profile alone, create a separate Yomitan profile for SubMiner, set its Anki server (Settings, Anki) to the proxy URL, and make it active while you mine.
 
-- proxy URL when `ankiConnect.proxy.enabled` is `true`
-- direct `ankiConnect.url` when proxy mode is disabled
+### Proxy troubleshooting
 
-To avoid clobbering custom setups, this auto-update only changes the profile when its current server is blank or the stock Yomitan default (`http://127.0.0.1:8765`).
+If cards are not getting filled:
 
-For browser-based Yomitan or other external clients (for example Texthooker in a normal browser profile), set their Anki server to the same proxy URL separately: `http://127.0.0.1:8766` (or your configured `proxy.host` + `proxy.port`).
+1. Check that the proxy is listening while SubMiner runs:
 
-### Browser/Yomitan external setup (separate profile)
+   ```bash
+   ss -ltnp | grep 8766
+   ```
 
-If you want SubMiner to use proxy mode without touching your main/default Yomitan profile, create or select a separate Yomitan profile just for SubMiner and set its Anki server to the proxy URL.
+2. Check that requests pass through to Anki:
 
-That profile isolation gives you both benefits:
+   ```bash
+   curl -sS http://127.0.0.1:8766 \
+     -H 'content-type: application/json' \
+     -d '{"action":"version","version":2}'
+   ```
 
-- SubMiner can auto-enrich immediately via proxy.
-- Your default Yomitan profile keeps its existing Anki server setting.
+3. Read the app log (`app-YYYY-MM-DD.log`) in the logs folder. See [Troubleshooting](/troubleshooting) for where logs live.
 
-In Yomitan, go to Settings → Profile and:
+## Field mapping
 
-1. Create a profile for SubMiner (or choose one dedicated profile).
-2. Open Anki settings for that profile.
-3. Set server to `http://127.0.0.1:8766` (or your configured proxy URL).
-4. Save and make that profile active when using SubMiner.
+`ankiConnect.fields` maps SubMiner's data to fields on your note type.
 
-This is only for non-bundled, external/browser Yomitan or other clients. The bundled profile auto-update logic only targets the active profile when its server is blank or still default.
-
-### Proxy Troubleshooting (quick checks)
-
-If auto-enrichment appears to do nothing:
-
-1. Confirm proxy listener is running while SubMiner is active:
-
-```bash
-ss -ltnp | rg 8766
-```
-
-2. Confirm requests can pass through the proxy:
-
-```bash
-curl -sS http://127.0.0.1:8766 \
-  -H 'content-type: application/json' \
-  -d '{"action":"version","version":2}'
-```
-
-3. Check the log sinks in `~/.config/SubMiner/logs/`:
-
-- App runtime log: `app-YYYY-MM-DD.log`
-- Launcher log: `launcher-YYYY-MM-DD.log`
-- mpv log: `mpv-YYYY-MM-DD.log`
-
-4. Ensure config JSONC is valid and logging shape is correct:
-
-```jsonc
-"logging": {
-  "level": "debug"
-}
-```
-
-`"logging": "debug"` is invalid for current schema and can break reload/start behavior.
-
-## Field Mapping
-
-SubMiner maps its data to your Anki note fields. Configure these under `ankiConnect.fields`:
+| Key                | Receives                                                                  |
+| ------------------ | ------------------------------------------------------------------------- |
+| `fields.word`      | The mined word                                                            |
+| `fields.audio`     | Sentence audio cut from the video                                         |
+| `fields.wordAudio` | Read only: Yomitan's word audio, used to time animated images (see below) |
+| `fields.image`     | Screenshot or animated clip                                               |
+| `fields.sentence`  | Subtitle text                                                             |
+| `fields.miscInfo`  | Text from `ankiConnect.metadata.pattern`                                  |
 
 ```jsonc
 "ankiConnect": {
   "fields": {
-    "word": "Expression",           // mined word / expression text
-    "audio": "ExpressionAudio",    // audio clip from the video
-    "image": "Picture",             // screenshot or animated clip
-    "sentence": "Sentence",         // subtitle text
-    "miscInfo": "MiscInfo",         // metadata (filename, timestamp)
-    "translation": "SelectionText"  // secondary sub or AI translation
+    "audio": "SentenceAudio",
+    "sentence": "Sentence"
   }
 }
 ```
 
-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.
+Field names are matched case-insensitively. A mapped field that is missing from the note type is skipped.
 
-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).
+`fields.audio` gets sentence audio, not word audio. Yomitan writes its own dictionary audio into your note, so point `fields.audio` at a separate field such as `SentenceAudio`. The default, `ExpressionAudio`, is the field many note types use for Yomitan's word audio, so leaving it would overwrite that audio.
 
-### Minimal Config
+`ankiConnect.tags` adds tags to every mined or updated card. Set it to `[]` to add none.
 
-If you only want sentence and audio on your cards:
+`ankiConnect.metadata.pattern` builds the MiscInfo text. Tokens: `%f` file name, `%F` file name with extension, `%t` timestamp, `%T` timestamp with milliseconds, `<br>` line break.
 
-```jsonc
-"ankiConnect": {
-  "enabled": true,
-  "fields": {
-    "sentence": "Sentence",
-    "audio": "ExpressionAudio"
-  }
-}
-```
+## Media
 
-## Media Generation
+| Key                                  | What it does                                                                                                              |
+| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- |
+| `media.generateAudio`                | Cut sentence audio (MP3) from the subtitle's start and end time                                                           |
+| `media.audioPadding`                 | Seconds added before and after the clip                                                                                   |
+| `media.fallbackDuration`             | Clip length when the subtitle has no timing                                                                               |
+| `media.maxMediaDuration`             | Longest allowed clip, in seconds (`0` removes the cap)                                                                    |
+| `media.normalizeAudio`               | Normalize clip loudness                                                                                                   |
+| `media.mirrorMpvVolume`              | Scale the clip by mpv's current volume, so quiet playback gives quiet clips                                               |
+| `media.generateImage`                | Capture an image                                                                                                          |
+| `media.imageType`                    | `static` for one frame, `avif` for an animated clip of the line                                                           |
+| `media.imageFormat`                  | Static format: `jpg`, `png`, or `webp`                                                                                    |
+| `media.imageQuality`                 | Static image quality                                                                                                      |
+| `media.imageMaxWidth` / `Height`     | Static size limit (`0` keeps source size)                                                                                 |
+| `media.animatedFps`                  | Animated clip frame rate                                                                                                  |
+| `media.animatedMaxWidth` / `Height`  | Animated size limit (`0` keeps aspect ratio)                                                                              |
+| `media.animatedCrf`                  | Animated quality, `0` to `63`, lower is better                                                                            |
+| `media.syncAnimatedImageToWordAudio` | Hold the first frame for the length of the word audio in `fields.wordAudio`, so the motion starts with the sentence audio |
+| `media.reviewTiming`                 | Pause and let you adjust the clip before media is made (see below)                                                        |
 
-SubMiner uses FFmpeg to generate audio and image media from the video. FFmpeg must be installed and on `PATH`.
+Animated AVIF needs an FFmpeg build with an AV1 encoder (`libaom-av1`, `libsvtav1`, or `librav1e`).
 
-### Audio
+Media settings apply to the next card without a restart.
 
-Audio is extracted from the video file using the subtitle's start and end timestamps. Padding is opt-in; keep it at `0` when you want sentence audio to start exactly at the mined sentence.
+### Review media timing
 
-```jsonc
-"ankiConnect": {
-  "media": {
-    "generateAudio": true,
-    "normalizeAudio": true,      // normalize generated clip loudness
-    "mirrorMpvVolume": true,     // apply the current mpv volume level
-    "audioPadding": 0,           // optional seconds before and after subtitle timing
-    "maxMediaDuration": 30       // cap total duration in seconds
-  }
-}
-```
+With `media.reviewTiming` on, SubMiner pauses before making media for word, sentence, and audio cards and opens a review dialog. You can also toggle it for the current session with **Review Media Timing** in the runtime options palette (`Ctrl/Cmd+Shift+O`). Clipboard updates and stats-dashboard mining skip the review.
 
-Output format: MP3 at 44100 Hz. If the video has multiple audio streams, SubMiner uses the active stream. Generated sentence audio is loudness-normalized to -23 LUFS by default during extraction; set `normalizeAudio` to `false` to keep raw source loudness. When subtitle timing is missing, clips fall back to `media.fallbackDuration` seconds (default `3`). Changing these settings applies to the next extraction without restarting SubMiner.
+The dialog shows the clip over a speech waveform. When the waveform loads, an untouched clip end moves back to just after the last speech in the line. The Line end rail still marks the subtitle's own end.
 
-`mirrorMpvVolume` is also enabled by default. Immediately before extracting each playback-overlay card's audio, SubMiner reads mpv's numeric `volume` and applies mpv's cubic software-volume curve after loudness normalization. For example, mpv volume `50` produces `0.5³ = 0.125` gain. Amplified output above mpv volume `100` is limited to a `-1 dBFS` ceiling before MP3 encoding to prevent clipping. It ignores mpv's separate `mute` state. If the volume property is missing, invalid, or unavailable, extraction continues with unity scaling; disabling this option skips the query and volume filter. Changing this setting applies to the next extraction without restarting SubMiner. YouTube cards queued for a background media-cache download retain the volume captured when the card was mined. Stats-dashboard mining does not currently have access to the active mpv property client, so it does not apply mpv volume scaling.
+| Action                   | How                                                                   |
+| ------------------------ | --------------------------------------------------------------------- |
+| Trim                     | Drag either edge, or click the waveform to move the nearer edge there |
+| Nudge an edge            | Arrow keys on a focused edge (100 ms, `Shift` for 500 ms)             |
+| Slide the clip           | Drag the middle                                                       |
+| Show more timeline       | Earlier / Later                                                       |
+| Pick the screenshot      | Screenshot slider or Frame buttons (static images only)               |
+| Add previous / next line | `P` / `N` (`Shift+P` / `Shift+N` removes)                             |
+| Preview                  | `Space`                                                               |
+| Confirm                  | `Enter`                                                               |
+| Cancel                   | `Escape`                                                              |
 
-The audio is uploaded to Anki's media folder and inserted as `[sound:audio_<timestamp>.mp3]`.
+The confirmed range is used as is, with no extra padding. Added lines go into the sentence field. Reset restores the original timing and removes added lines.
 
-### Screenshots (Static)
+When you cancel, you can go back to editing, keep the original timing, create the card without media, or discard it. Discard deletes the Yomitan note or audio card, and skips creation for a sentence card.
 
-A single frame is captured at the current playback position.
+### Update behavior
 
-```jsonc
-"ankiConnect": {
-  "media": {
-    "generateImage": true,
-    "imageType": "static",
-    "imageFormat": "jpg",        // "jpg", "png", or "webp"
-    "imageQuality": 92,          // 1–100
-    "imageMaxWidth": 0,          // 0 = preserve source resolution
-    "imageMaxHeight": 0
-  }
-}
-```
+| Key                           | What it does                                         |
+| ----------------------------- | ---------------------------------------------------- |
+| `behavior.overwriteAudio`     | Replace existing audio instead of adding to it       |
+| `behavior.overwriteImage`     | Replace the existing image instead of adding to it   |
+| `behavior.mediaInsertMode`    | `append` or `prepend` new media when not overwriting |
+| `behavior.autoUpdateNewCards` | Fill new Yomitan notes automatically                 |
+| `behavior.highlightWord`      | Bold the mined word in the sentence field            |
+| `behavior.notificationType`   | `overlay`, `system`, `both`, or `none`               |
 
-### Animated Clips (AVIF)
+Manual clipboard updates (`Ctrl/Cmd+V`) always replace the sentence audio, whatever `overwriteAudio` says.
 
-Instead of a static screenshot, SubMiner can generate an animated AVIF covering the subtitle duration.
+## Sentence cards (Lapis) {#sentence-cards-lapis}
 
-```jsonc
-"ankiConnect": {
-  "media": {
-    "generateImage": true,
-    "imageType": "avif",
-    "animatedFps": 10,
-    "animatedMaxWidth": 640,
-    "animatedMaxHeight": 0,      // 0 = preserve aspect ratio
-    "animatedCrf": 35            // 0–63, lower = better quality
-  }
-}
-```
-
-Animated AVIF requires an AV1 encoder (`libaom-av1`, `libsvtav1`, or `librav1e`) in your FFmpeg build. Generation timeout is 60 seconds. `media.syncAnimatedImageToWordAudio` (default `true`) prepends a frozen first frame matching the existing word-audio duration, so the motion starts together with the sentence audio.
-
-### Behavior Options
-
-```jsonc
-"ankiConnect": {
-  "behavior": {
-    "overwriteAudio": true,         // replace existing audio, or append
-    "overwriteImage": true,         // replace existing image, or append
-    "mediaInsertMode": "append",    // "append" or "prepend" to field content
-    "autoUpdateNewCards": true,     // auto-update when new card detected
-    "highlightWord": true,          // bold the mined word inside the sentence field
-    "notificationType": "overlay"   // "overlay", "system", "both", or "none"
-  }
-}
-```
-
-`both` now means overlay + system notification. `osd` and `osd-system` are legacy config-file-only values; set `notificationType` to `"osd-system"` in `config.jsonc` if you previously used `both` and want to keep mpv OSD + system notifications. The Settings window shows `osd` or `osd-system` when already configured, but only offers `overlay`, `system`, `both`, and `none` as normal choices.
-
-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.
-
-## AI Translation
-
-SubMiner can auto-translate the mined sentence and fill the translation field.
-Secondary subtitle text still wins when present. AI translation is only attempted when `ankiConnect.ai.enabled` is `true` and no secondary subtitle exists.
-
-```jsonc
-"ai": {
-  "enabled": true,
-  "apiKey": "sk-...",
-  "apiKeyCommand": "",
-  "baseUrl": "https://openrouter.ai/api",
-  "requestTimeoutMs": 15000
-},
-"ankiConnect": {
-  "ai": {
-    "enabled": true,
-    "model": "openai/gpt-4o-mini",
-    "systemPrompt": "Translate mined sentence text only."
-  }
-}
-```
-
-`ankiConnect.ai` controls feature-local enablement plus optional `model` / `systemPrompt` overrides.
-Provider credentials and request transport settings live in top-level `ai`.
-
-Translation priority:
-
-1. If a secondary subtitle is available, use it as the translation.
-2. If `ankiConnect.ai.enabled` is `true` and top-level `ai.enabled` is `true`, call the shared AI provider.
-3. If AI translation fails and no secondary subtitle exists, fall back to the original sentence text.
-
-The built-in translation request asks for English output by default. Customize that behavior through `ankiConnect.ai.systemPrompt`.
-
-## Sentence Cards (Lapis)
-
-SubMiner can create standalone sentence cards (without a word/expression) using a separate note type. This is designed for use with [Lapis](https://github.com/donkuri/Lapis) and similar sentence-focused note types.
-
-::: warning Required config
-Sentence card creation and audio card marking require a non-empty `ankiConnect.isLapis.sentenceCardModel` naming a note type that exists in Anki (default: `"Lapis"`). If the model is empty or missing, the `Ctrl/Cmd+S` and `Ctrl/Cmd+Shift+A` shortcuts will not create cards.
-:::
+`Ctrl/Cmd+S` creates a standalone sentence card from the current line, and `Ctrl/Cmd+Shift+S` then a digit combines several lines. The card uses the note type named in `ankiConnect.isLapis.sentenceCardModel`, which must exist in Anki. If it is empty, no card is created.
 
 ```jsonc
 "ankiConnect": {
   "isLapis": {
     "enabled": true,
-    "sentenceCardModel": "Lapis" // default; point at your Lapis/Kiku note type
+    "sentenceCardModel": "Lapis"
   }
 }
 ```
 
-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.
+Sentence cards and audio cards (`Ctrl/Cmd+Shift+A`) always write to the `Sentence` and `SentenceAudio` fields. Normal word cards keep using your `ankiConnect.fields` mapping.
 
-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)
 
-## Word Card Type (Kiku/Lapis)
+When `isKiku` or `isLapis` is enabled, SubMiner sets a card-type flag on word cards it fills. Choose the flag with `ankiConnect.lapisKiku.wordCardKind`:
 
-Word cards get a card-type flag when SubMiner fills their sentence, whether that comes from Yomitan auto-enrichment, a manual clipboard update, or stats-dashboard word mining. By default the flag is `IsWordAndSentenceCard`; pick a different one with `ankiConnect.lapisKiku.wordCardKind`.
+| Value               | Flag                    |
+| ------------------- | ----------------------- |
+| `word-and-sentence` | `IsWordAndSentenceCard` |
+| `click`             | `IsClickCard`           |
+| `sentence`          | `IsSentenceCard`        |
+| `audio`             | `IsAudioCard`           |
+| `none`              | Leaves flags alone      |
 
-```jsonc
-"ankiConnect": {
-  "isKiku": { "enabled": true },
-  "lapisKiku": {
-    "wordCardKind": "click" // word-and-sentence (default), click, sentence, audio, none
-  }
-}
-```
+The other card-type flags are cleared. Sentence cards and audio cards keep their own flag.
 
-`click` marks `IsClickCard`, `sentence` marks `IsSentenceCard`, `audio` marks `IsAudioCard`, and `none` leaves the flags untouched for templates that manage them elsewhere. Whichever flag is chosen, the other card-type flags are cleared so the note never claims two card types. The setting is only read when `isKiku` or `isLapis` is enabled, and cards mined with Mine Sentence or Mine Audio keep their own flag.
+## Field grouping (Kiku/Senren) {#field-grouping-kiku-senren}
 
-## Field Grouping (Kiku)
+When you mine a word that already has a card, SubMiner can merge the new card into the old one. The sentence, audio, image, and MiscInfo from both cards are kept as grouped entries, and the template lets you switch between them. This works with [Kiku](https://github.com/youyoumu/kiku) and [Senren](https://github.com/BrenoAqua/Senren) (which calls it [scene switching](https://github.com/BrenoAqua/Senren/blob/main/docs/scene_switching.md)).
 
-When you mine the same word multiple times, SubMiner can merge the cards instead of creating duplicates. This is designed for note types like [Kiku](https://github.com/youyoumu/kiku) that support grouped sentence/audio/image fields.
+Enable one of them. They write different markup to the same fields, so only one can be on. If both are enabled, Kiku is used and SubMiner logs a config warning.
 
 ```jsonc
 "ankiConnect": {
   "isKiku": {
     "enabled": true,
-    "fieldGrouping": "manual",         // "auto", "manual", or "disabled"
-    "deleteDuplicateInAuto": true      // delete new card after auto-merge
+    "fieldGrouping": "manual",
+    "deleteDuplicateInAuto": true
   }
 }
 ```
 
-### Modes
+For Senren, use the same keys under `isSenren`.
 
-**Disabled** (`"disabled"`): No duplicate detection. Each card is independent.
+| `fieldGrouping` | Behavior                                                                        |
+| --------------- | ------------------------------------------------------------------------------- |
+| `disabled`      | No duplicate check                                                              |
+| `auto`          | Merge into the existing card. With `deleteDuplicateInAuto`, delete the new card |
+| `manual`        | Show both cards, let you choose which to keep and preview the merge             |
 
-**Auto** (`"auto"`): When a duplicate expression is found, SubMiner merges the new card into the existing one automatically. Both cards' sentences, audio clips, and images are preserved as grouped entries. If `deleteDuplicateInAuto` is true, the new card is deleted after merging.
+The manual dialog cancels itself after 90 seconds. Identical entries are not deduplicated. Press `Ctrl/Cmd+G` to run the duplicate check on the last card yourself.
 
-**Manual** (`"manual"`): A modal appears in the overlay showing both cards. You choose which card to keep, preview the merge result, then confirm. The modal has a 90-second timeout, after which it cancels automatically.
+| Key         | Action                                |
+| ----------- | ------------------------------------- |
+| `1` / `2`   | Keep card 1 or card 2                 |
+| `Enter`     | Confirm                               |
+| `Backspace` | Back from the merge preview           |
+| `Esc`       | Cancel and leave both cards unchanged |
 
-### What Gets Merged
+## Config validation
 
-| Field    | Merge behavior                                |
-| -------- | --------------------------------------------- |
-| Sentence | Both cards' sentences kept as grouped entries |
-| Audio    | Both cards' `[sound:...]` entries kept        |
-| Image    | Both cards' images kept                       |
-
-Identical values from both cards are kept as separate grouped entries; the merge does not deduplicate.
-
-### Keyboard Shortcuts in the Modal
-
-| Key         | Action                             |
-| ----------- | ---------------------------------- |
-| `1` / `2`   | Select card 1 or card 2 to keep    |
-| `Enter`     | Confirm selection                  |
-| `Backspace` | Go back from the merge preview     |
-| `Esc`       | Cancel (keep both cards unchanged) |
-
-## Full Config Example
-
-```jsonc
-{
-  "ankiConnect": {
-    "enabled": true,
-    "url": "http://127.0.0.1:8765",
-    "pollingRate": 3000,
-    "deck": "",
-    "tags": ["SubMiner"],
-    "proxy": {
-      "enabled": true, // default
-      "host": "127.0.0.1",
-      "port": 8766,
-      "upstreamUrl": "http://127.0.0.1:8765",
-    },
-    "fields": {
-      "word": "Expression",
-      "audio": "ExpressionAudio",
-      "image": "Picture",
-      "sentence": "Sentence",
-      "miscInfo": "MiscInfo",
-      "translation": "SelectionText",
-    },
-    "media": {
-      "generateAudio": true,
-      "generateImage": true,
-      "imageType": "static",
-      "imageFormat": "jpg",
-      "imageQuality": 92,
-      "normalizeAudio": true,
-      "mirrorMpvVolume": true,
-      "audioPadding": 0,
-      "maxMediaDuration": 30,
-    },
-    "behavior": {
-      "overwriteAudio": true,
-      "overwriteImage": true,
-      "mediaInsertMode": "append",
-      "autoUpdateNewCards": true,
-      "notificationType": "overlay",
-    },
-    "metadata": {
-      "pattern": "[SubMiner] %f (%t)",
-    },
-    "ai": {
-      "enabled": false,
-      "model": "", // e.g. "openai/gpt-4o-mini"
-      "systemPrompt": "",
-    },
-    "isKiku": {
-      "enabled": false,
-      "fieldGrouping": "disabled",
-      "deleteDuplicateInAuto": true,
-    },
-    "isLapis": {
-      "enabled": false,
-      "sentenceCardModel": "Lapis",
-    },
-  },
-  "ai": {
-    "enabled": false,
-    "apiKey": "",
-    "apiKeyCommand": "",
-    "baseUrl": "https://openrouter.ai/api",
-    "requestTimeoutMs": 15000,
-  },
-}
-```
+Invalid `ankiConnect` values produce a warning and fall back to the default. Use JSON booleans (`true`, not `"true"`) and a positive number for `pollingRate`.
diff --git a/docs-site/architecture.md b/docs-site/architecture.md
index a88ad7bf..f4d9531b 100644
--- a/docs-site/architecture.md
+++ b/docs-site/architecture.md
@@ -1,149 +1,55 @@
 # Architecture
 
-This page is a contributor-facing architecture summary. Canonical internal architecture guidance lives in `docs/architecture/README.md` at the repo root.
+A contributor-facing map of how SubMiner is put together. The canonical internal guidance, including domain ownership and layering rules, is [`docs/architecture/README.md`](https://github.com/ksyasuda/SubMiner/blob/main/docs/architecture/README.md) in the repo.
 
-SubMiner is split into three cooperating runtimes:
+SubMiner runs as three cooperating runtimes:
 
-- Electron desktop app (`src/`) for overlay/UI/runtime orchestration.
-- Launcher CLI (`launcher/`) for mpv/app command workflows.
-- mpv Lua plugin (`plugin/subminer/main.lua` + module files) for player-side controls and IPC handoff.
+- the Electron desktop app (`src/`): overlay, UI, and runtime orchestration
+- the launcher CLI (`launcher/`): mpv and app command workflows
+- the mpv Lua plugin (`plugin/subminer/`): player-side controls and handoff to the app
 
-Within the desktop app, `src/main.ts` is a composition root that wires small runtime/domain modules plus core services.
+Inside the app, `src/main.ts` is a composition root. It owns wiring and state, and delegates behavior to small runtime and domain modules that can be tested without Electron or mpv.
 
-## Goals
-
-- Keep behavior stable while reducing coupling.
-- Prefer small, single-purpose units that can be tested in isolation.
-- Keep `main.ts` focused on wiring and state ownership, not implementation detail.
-- Follow Unix-style composability:
-  - each service does one job
-  - services compose through explicit inputs/outputs
-  - orchestration is separate from implementation
-
-## Project Structure
+## Project layout
 
 ```text
-launcher/                 # Standalone CLI launcher wrapper and mpv helpers
-  commands/               # Command modules (doctor/config/mpv/jellyfin/playback/app passthrough/
-                          #   dictionary/history/logs/stats/update)
-  config/                 # Launcher config parsers + CLI parser builder
-  main.ts                 # Launcher entrypoint and command dispatch
-plugin/
-  subminer/               # Modular mpv plugin (main · init · bootstrap · lifecycle · process
-                          #   state · messages · hover · ui · options · environment · log
-                          #   binary · session_bindings · version)
+launcher/
+  main.ts                 # entrypoint and command dispatch
+  commands/               # one module per subcommand (playback, jellyfin, stats, sync, ...)
+  config/                 # launcher config readers and CLI parser
+plugin/subminer/          # mpv plugin; main.lua loads init.lua, which boots the other modules
 src/
-  ai/                      # AI translation provider utilities (client, config)
-  main-entry.ts           # Background-mode bootstrap wrapper before loading main.js
-  main.ts                  # Entry point - delegates to runtime composers/domain modules
-  preload.ts               # Electron preload bridge
-  types.ts                 # Shared type definitions
-  main/                    # Main-process composition/runtime adapters
-    boot/                  # Pre-ready boot helpers
-    app-lifecycle.ts       # App lifecycle + app-ready runtime runner factories
-    character-dictionary-runtime.ts # Character-dictionary orchestration/public runtime API
-    cli-runtime.ts         # CLI command runtime service adapters
-    config-validation.ts   # Startup/hot-reload config error formatting and fail-fast helpers
-    dependencies.ts        # Shared dependency builders for IPC/runtime services
-    ipc-runtime.ts         # IPC runtime registration wrappers
-    overlay-runtime.ts     # Overlay modal routing + active-window selection
-    overlay-shortcuts-runtime.ts # Overlay keyboard shortcut handling
-    overlay-visibility-runtime.ts # Overlay visibility + tracker-driven bounds service
-    frequency-dictionary-runtime.ts # Frequency dictionary runtime adapter
-    jlpt-runtime.ts         # JLPT dictionary runtime adapter
-    media-runtime.ts        # Media path/title/subtitle-position runtime service
-    startup.ts              # Startup bootstrap dependency builder
-    startup-lifecycle.ts    # Lifecycle runtime runner adapter
-    state.ts                # Application runtime state container + reducer transitions
-    subsync-runtime.ts      # Subsync command runtime adapter
-    character-dictionary-runtime/ # Character-dictionary fetch/build/cache modules + focused tests
-    runtime/
-      composers/            # High-level composition clusters used by main.ts
-      domains/              # Domain barrel exports (startup/overlay/mpv/jellyfin/...)
-      registry.ts           # Domain registry consumed by main.ts
-  core/
-    services/              # Focused runtime services (Electron adapters + pure logic)
-      anilist/             # AniList token store/update queue/update helpers
-      immersion-tracker/   # Immersion persistence/session/metadata modules
-      tokenizer/           # Tokenizer stage modules (selection/enrichment/annotation)
-    utils/                 # Pure helpers and coercion/config utilities
-  cli/                     # CLI parsing and help output
-  config/                  # Config defaults/definitions, loading, parse, resolution pipeline
-    definitions/           # Domain-specific defaults + option registries
-    resolve/               # Domain-specific config resolution pipeline stages
-  shared/ipc/              # Cross-process IPC channel constants + payload validators
-  renderer/                # Overlay renderer (modularized UI/runtime)
-    handlers/              # Keyboard/mouse/gamepad interaction modules
-    modals/                # Modal flows (Jimaku, Kiku, subsync, runtime options, session help,
-                           #   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, ...)
-  window-trackers/         # Backend-specific tracker implementations (Hyprland, Sway, X11, macOS, Windows)
-  jimaku/                  # Jimaku API integration helpers
-  subsync/                 # Subtitle sync (alass/ffsubsync) helpers
-  anki-integration/        # AnkiConnect proxy server + note-update enrichment workflow
+  main-entry.ts           # bootstrap wrapper that runs before main.js
+  main.ts                 # composition root
+  preload*.ts             # preload bridges (overlay, settings, stats, sync, Jellyfin setup)
+  main/                   # main-process runtime modules and IPC/CLI wiring
+    boot/                 # pre-ready boot helpers
+    runtime/composers/    # larger runtime clusters assembled for main.ts
+    runtime/domains/      # domain barrels (startup, overlay, mpv, ipc, shortcuts, anilist, jellyfin, mining)
+  core/services/          # focused services: mpv client, overlay, tokenizer, mining, integrations, stats
+  core/utils/             # pure helpers
+  shared/ipc/             # IPC channel constants and payload validators
+  renderer/               # overlay renderer: subtitle rendering, input handlers, modals
+  config/                 # definitions/ (defaults + option registries) and resolve/ (resolution pipeline)
+  cli/                    # app CLI parsing and help output
+  settings/, syncui/      # settings and sync windows
+  window-trackers/        # Hyprland, Sway, X11, macOS, and Windows trackers
+  anki-integration/       # AnkiConnect proxy and note-update workflow
+  jimaku/, subsync/, tsukihime/  # integration helpers
+  types/                  # shared domain types
+stats/                    # stats dashboard UI (Vite)
+vendor/                   # Yomitan fork, texthooker-ui, JLPT vocab
 ```
 
-### Service Layer (`src/core/services/`)
+A few ownership notes that are hard to guess from file names:
 
-- **Overlay/window runtime:** `overlay-manager.ts`, `overlay-window.ts`, `overlay-visibility.ts`, `overlay-bridge.ts`, `overlay-runtime-init.ts`, `overlay-content-measurement.ts`
-- **Shortcuts/input:** `shortcut.ts`, `overlay-shortcut.ts`, `overlay-shortcut-handler.ts`, `shortcut-fallback.ts`, `numeric-shortcut.ts`
-- **MPV runtime:** `mpv.ts`, `mpv-transport.ts`, `mpv-protocol.ts`, `mpv-properties.ts`, `mpv-render-metrics.ts`
-- **Mining + Anki/Jimaku runtime:** `mining.ts`, `field-grouping.ts`, `field-grouping-overlay.ts`, `anki-jimaku.ts`, `anki-jimaku-ipc.ts`
-- **Subtitle/token pipeline:** `subtitle-processing-controller.ts`, `subtitle-position.ts`, `subtitle-ws.ts`, `tokenizer.ts` + `tokenizer/*` stage modules (including `parser-enrichment-worker-runtime.ts` for async MeCab enrichment and `yomitan-parser-runtime.ts`)
-- **Integrations:** `jimaku.ts`, `subsync.ts`, `subsync-runner.ts`, `texthooker.ts`, `jellyfin.ts`, `jellyfin-remote.ts`, `discord-presence.ts`, `yomitan-extension-loader.ts`, `yomitan-settings.ts`
-- **Anki integration (repo `src/` root, not under `core/services/`):** `src/anki-integration.ts`, `src/anki-integration/anki-connect-proxy.ts` (local proxy for push-based auto-enrichment), `src/anki-integration/note-update-workflow.ts`
-- **Config/runtime controls:** `config-hot-reload.ts`, `runtime-options-ipc.ts`, `cli-command.ts`, `startup.ts`
-- **Domain submodules:** `anilist/*` (token/update queue/updater), `immersion-tracker/*` (storage/session/metadata/query/reducer)
+- mpv access is split into transport (`mpv-transport.ts`), protocol (`mpv-protocol.ts`), and property modules under `src/core/services/`.
+- The renderer keeps `renderer.ts` to orchestration. Keyboard, mouse, and gamepad input live in `renderer/handlers/`, and each modal flow has its own file in `renderer/modals/`.
+- AniSkip intro detection runs in the app (`src/main/runtime/aniskip-runtime.ts`), which drives mpv chapters and the skip key over the mpv IPC socket. The plugin does not handle it.
 
-### Renderer Layer (`src/renderer/`)
+## Component diagram
 
-The renderer keeps `renderer.ts` focused on orchestration. UI behavior is delegated to per-concern modules.
-
-```text
-src/renderer/
-  renderer.ts              # Entrypoint/orchestration only
-  context.ts               # Shared runtime context contract
-  state.ts                 # Centralized renderer mutable state (visible overlay only)
-  error-recovery.ts        # Global renderer error boundary + recovery actions
-  overlay-content-measurement.ts # Reports rendered bounds to main process
-  subtitle-render.ts       # Primary/secondary subtitle rendering + style application
-  positioning.ts           # Facade export for positioning controller
-  yomitan-popup.ts         # Yomitan popup iframe detection utilities
-  positioning/
-    controller.ts          # Subtitle drag-position controller
-    position-state.ts      # Position state helpers (yPercent)
-  handlers/
-    keyboard.ts            # Keybindings, chord handling, modal key routing
-    mouse.ts               # Hover/drag behavior, selection + observer wiring
-    gamepad-controller.ts  # Gamepad/controller input handling
-    controller-binding-capture.ts # Controller binding capture flow
-  modals/
-    jimaku.ts              # Jimaku modal flow
-    kiku.ts                # Kiku field-grouping modal flow
-    runtime-options.ts     # Runtime options modal flow
-    session-help.ts        # Keyboard shortcuts/help modal flow
-    subsync.ts             # Manual subsync modal flow
-    character-dictionary.ts # Character dictionary modal flow
-    playlist-browser.ts    # Playlist browser modal flow
-    subtitle-sidebar.ts    # Subtitle sidebar modal flow
-    youtube-track-picker.ts # YouTube subtitle track picker
-    controller-*.ts        # Controller config/debug/select modals
-  utils/
-    dom.ts                 # Required DOM lookups + typed handles
-    platform.ts            # Layer/platform capability detection
-```
-
-### Launcher + Plugin Runtimes
-
-- `launcher/main.ts` dispatches commands through `launcher/commands/*` and shared config readers in `launcher/config/*`. It handles mpv startup, app passthrough, Jellyfin helper commands, and playback handoff.
-- `plugin/subminer/main.lua` is the mpv entrypoint: it sets up the module path and loads `init.lua`, a thin shim that boots the modular Lua files: `bootstrap.lua` (startup), `lifecycle.lua` (connect/disconnect), `process.lua` (process management), `state.lua` (shared state), `messages.lua` (IPC), `hover.lua` (hover-token highlight rendering), `ui.lua` (OSD rendering), `options.lua` (config), `environment.lua` (detection), `log.lua` (logging), `binary.lua` (path resolution), `session_bindings.lua` (configurable session keybindings), `version.lua` (version metadata). AniSkip intro detection lives in the SubMiner app (`src/main/runtime/aniskip-runtime.ts`), which drives mpv chapters and the skip key over the IPC socket.
-
-## Flow Diagram
-
-The main process orchestrates a single primary overlay window plus modal surfaces: `main.ts` delegates to composition modules that wire together domain services. Subtitle layers (primary + secondary bar) are rendered in the same overlay renderer process, connected through `preload.ts`. External runtimes (launcher CLI and mpv plugin) operate independently and communicate via IPC socket or CLI passthrough.
+The main process drives one primary overlay window plus modal surfaces. Primary and secondary subtitle layers render in the same overlay renderer, connected to the main process through `preload.ts`. The launcher and mpv plugin run as separate processes and talk to the app through sockets or CLI passthrough.
 
 ```mermaid
 flowchart TB
@@ -224,65 +130,41 @@ flowchart TB
   style ExtRt fill:#363a4f,stroke:#494d64,color:#cad3f5
 ```
 
-## Composition Pattern
+## Composition pattern
 
-Most runtime code follows a dependency-injection pattern:
+Runtime code uses dependency injection:
 
-1. Define a service interface in `src/core/services/*`.
-2. Keep core logic in pure or side-effect-bounded functions.
-3. Build runtime deps in `src/main/` composition modules; extract an adapter/helper only when it adds meaningful behavior or reuse.
-4. Call the service from lifecycle/command wiring points.
+1. Put the logic in a service under `src/core/services/`, as pure or side-effect-bounded functions.
+2. Build its runtime dependencies in a `src/main/` module. Pass simple dependencies inline; extract an adapter only when it adds behavior or gets reused.
+3. Call the service from lifecycle or command wiring.
 
-The composition root (`src/main.ts`) delegates to focused modules in `src/main/` and `src/main/runtime/composers/`:
+`main.ts` gets domain handlers through `createMainRuntimeRegistry()` (`src/main/runtime/registry.ts`), which exposes the barrels in `src/main/runtime/domains/`. Larger clusters, such as app-ready startup, mpv, Jellyfin, AniList tracking, shortcuts, and IPC, are assembled by composers in `src/main/runtime/composers/`. Many handlers take a `*MainDeps` object built by a `createBuild*MainDepsHandler` builder, which keeps side effects out of the unit under test.
 
-- `startup.ts` - argv/env processing and bootstrap flow
-- `app-lifecycle.ts` - Electron lifecycle event registration
-- `startup-lifecycle.ts` - app-ready initialization sequence
-- `state.ts` - centralized application runtime state container
-- `ipc-runtime.ts` - IPC channel registration and handler wiring
-- `cli-runtime.ts` - CLI command parsing and dispatch
-- `overlay-runtime.ts` - overlay window selection and modal state management
-- `subsync-runtime.ts` - subsync command orchestration
-- `runtime/composers/anilist-tracking-composer.ts` - AniList media tracking/probe/retry wiring
-- `runtime/composers/jellyfin-runtime-composer.ts` - Jellyfin config/client/playback/command/setup composition wiring
-- `runtime/composers/mpv-runtime-composer.ts` - MPV event/factory/tokenizer/warmup wiring
+Composers declare their inputs with `ComposerInputs<T>` and results with `ComposerOutputs<T>` from `src/main/runtime/composers/contracts.ts`. A missing dependency then fails at compile time.
 
-Composer modules share contract conventions via `src/main/runtime/composers/contracts.ts`:
+### IPC boundary
 
-- composer input surfaces are declared with `ComposerInputs<T>` so required dependencies cannot be omitted at compile time
-- composer outputs are declared with `ComposerOutputs<T>` to keep result contracts explicit and stable
-- builder return payload extraction should use shared type helpers instead of inline ad-hoc inference
+Channel names live in `src/shared/ipc/contracts.ts` and payload validators in `src/shared/ipc/validators.ts`. Renderer payloads are validated at the IPC entry points (`src/core/services/ipc.ts`, `src/core/services/anki-jimaku-ipc.ts`) before any domain handler runs. See [IPC + runtime contracts](/ipc-contracts) for the full rules.
 
-This keeps side effects explicit and makes behavior easy to unit-test with fakes.
+### Runtime state ownership
 
-Additional conventions in the current code:
+Some domains, such as AniList token, queue, and media-guess state, use reducer-style transitions:
 
-- `main.ts` uses `createMainRuntimeRegistry()` (`src/main/runtime/registry.ts`) to access domain handlers (`startup`, `overlay`, `mpv`, `ipc`, `shortcuts`, `anilist`, `jellyfin`, `mining`) without importing every runtime module directly.
-- Domain barrels in `src/main/runtime/domains/*` re-export runtime handlers + main-deps builders, while composers in `src/main/runtime/composers/*` assemble larger runtime clusters.
-- Many runtime handlers accept `*MainDeps` objects generated by `createBuild*MainDepsHandler` builders to isolate side effects and keep units testable.
+- Composition modules own the mutable state and expose narrow `get*`/`set*` accessors.
+- Handlers change another domain's state only through its transition helpers in `src/main/state.ts`, never by mutating the object directly.
+- A transition may update derived counters or snapshots, but must leave metadata it does not own untouched.
+- Tests for these domains check both the fields that should change and the ones that should not.
 
-### IPC Contract + Validation Boundary
+## Playback startup flow
 
-- Central channel constants live in `src/shared/ipc/contracts.ts` and are consumed by both main (`ipcMain`) and renderer preload (`ipcRenderer`) wiring.
-- Runtime payload parsers/type guards live in `src/shared/ipc/validators.ts`.
-- Rule: renderer-supplied payloads must be validated at IPC entry points (`src/core/services/ipc.ts`, `src/core/services/anki-jimaku-ipc.ts`) before calling domain handlers.
-- Malformed invoke payloads return explicit structured errors (for example `{ ok: false, error: ... }`) and malformed fire-and-forget payloads are ignored safely.
+A SubMiner-managed launch (the `subminer` launcher, the app's own playback, or the packaged Windows shortcut) starts mpv, injects the plugin, and brings up the overlay. The launcher reads `config.jsonc`, spawns mpv with the IPC socket and the bundled plugin, and passes runtime settings as `--script-opts`. The plugin never reads a config file: the shipped `subminer.conf` has no settings, so command-line options always win.
 
-### Runtime State Ownership (Migrated Domains)
+Once mpv is up, exactly one of two triggers starts the overlay:
 
-For domains migrated to reducer-style transitions (for example AniList token/queue/media-guess runtime state), follow these rules:
+- On a first launch, the launcher sets `auto_start=yes` and the plugin's `file-loaded` hook starts the app once the socket is ready.
+- When the app is already running, or for `--start-overlay` and YouTube flows, the launcher attaches over the app control socket and suppresses the plugin's auto-start.
 
-- Composition/runtime modules own mutable state cells and expose narrow `get*`/`set*` accessors.
-- Domain handlers do not mutate foreign state directly; they call explicit transition helpers that encode invariants.
-- Transition helpers may sync derived counters/snapshots, but must preserve non-owned metadata unless the transition explicitly owns that metadata.
-- Reducer boundary: when a domain has transition helpers in `src/main/state.ts`, new callsites should route updates through those helpers instead of ad-hoc object mutation in `main.ts` or composers.
-- Tests for migrated domains should assert both the intended field changes and non-targeted field invariants.
-
-## Playback Startup Flow
-
-Before the app boots, something has to launch mpv, inject the plugin, and bring the overlay up. SubMiner-managed launches own this step - the `subminer` launcher, the app's own playback, and the packaged Windows shortcut all follow the same path. The launcher reads `config.jsonc`, spawns mpv with the IPC socket and the bundled plugin, and passes runtime settings as `--script-opts`. The plugin never reads a config file: the shipped `subminer.conf` is intentionally empty so command-line opts always win.
-
-Once mpv is up, exactly one of two triggers brings up the overlay. On a first launch the plugin's `file-loaded` hook self-starts the app once the socket is ready (because the launcher injected `auto_start=yes`). When the app is already running - or for explicit `--start-overlay` and YouTube flows - the launcher instead attaches over the control socket and suppresses the plugin's auto-start, so the two never fire together. Both converge on the same app bring-up, which then runs the Program Lifecycle below.
+Both paths end in the same app bring-up, which then runs the program lifecycle below.
 
 ```mermaid
 flowchart TB
@@ -313,17 +195,17 @@ flowchart TB
   Conn --> Show["Transparent overlay over mpv<br/>Yomitan lookup · mine"]:::overlay
 ```
 
-The runtime sockets in this flow are detailed in [IPC + Runtime Contracts](./ipc-contracts#runtime-sockets).
+The sockets in this flow are described in [IPC + runtime contracts](./ipc-contracts#runtime-sockets).
 
-## Program Lifecycle
+## Program lifecycle
 
-- **Module-level init:** Before `app.ready`, the composition root registers protocols, sets platform flags, constructs all services, and wires dependency injection. `runAndApplyStartupState()` parses CLI args and detects the compositor backend.
-- **Startup:** If `--generate-config` is passed, it writes the template and exits. Otherwise `app-lifecycle.ts` acquires the single-instance lock and registers Electron lifecycle hooks.
-- **Critical-path init:** Once `app.whenReady()` fires, `composeAppReadyRuntime()` runs strict config reload, resolves keybindings, creates the `MpvIpcClient` (which immediately connects and subscribes to mpv subtitle/playback properties via `observe_property`), and initializes the `RuntimeOptionsManager`, `SubtitleTimingTracker`, and `ImmersionTrackerService`.
-- **Overlay runtime:** `initializeOverlayRuntime()` creates the primary overlay window (interactive Yomitan lookups and subtitle rendering), registers global shortcuts, and sets up bounds tracking via the active window tracker. mpv subtitle suppression is handled by a dedicated `overlay-mpv-sub-visibility` service.
-- **Background warmups:** Non-critical services are launched asynchronously: MeCab tokenizer check (with async worker thread), Yomitan extension load, JLPT + frequency dictionary prewarm, optional Jellyfin remote session, Discord presence service, AniList token refresh, and optional AnkiConnect proxy server. Warmup coverage is configurable through `startupWarmups` (including low-power mode that defers all but Yomitan).
-- **Runtime:** Event-driven. mpv property changes, IPC messages, CLI commands, overlay shortcuts, and hot-reload notifications route through runtime handlers/composers. Subtitle text flows through the `SubtitleProcessingController` (normalize → tokenize → merge), and results are sent to the main overlay renderer and modal surfaces.
-- **Shutdown:** `onWillQuitCleanup` destroys tray + config watcher, unregisters shortcuts, stops WebSocket + texthooker servers, closes the mpv socket + flushes OSD log, stops the window tracker, closes the Yomitan parser window, flushes the immersion tracker (SQLite), stops Jellyfin/Discord services, stops the AnkiConnect proxy server, and cleans Anki/AniList state.
+1. **Module init.** Before `app.ready`, the composition root registers protocols, sets platform flags, constructs services, and wires dependencies. `runAndApplyStartupState()` parses CLI args and detects the compositor backend.
+2. **Startup.** `--generate-config` writes the template and exits. Otherwise `app-lifecycle.ts` takes the single-instance lock and registers Electron lifecycle hooks.
+3. **App ready.** `composeAppReadyRuntime()` reloads config strictly, resolves keybindings, creates the `MpvIpcClient` (which connects and observes subtitle and playback properties), and starts the runtime options manager, subtitle timing tracker, and immersion tracker.
+4. **Overlay.** `initializeOverlayRuntime()` creates the overlay window, registers global shortcuts, and tracks mpv's window bounds through the active window tracker. `src/main/runtime/overlay-mpv-sub-visibility.ts` hides mpv's own subtitles while the overlay shows them.
+5. **Background warmups.** MeCab, Yomitan, JLPT and frequency dictionaries, the optional Jellyfin remote session, Discord presence, AniList token refresh, and the optional AnkiConnect proxy start asynchronously. `startupWarmups` controls which run; its low-power mode defers everything except Yomitan.
+6. **Runtime.** Event-driven. mpv property changes, IPC messages, CLI commands, shortcuts, and config hot-reloads route through handlers and composers. Subtitle text goes through `SubtitleProcessingController` (normalize, tokenize, merge) and out to the overlay renderer and modals.
+7. **Shutdown.** `onWillQuitCleanup` tears down the tray, config watcher, shortcuts, WebSocket and texthooker servers, mpv socket, window tracker, and Yomitan parser window. It flushes the immersion tracker to SQLite and stops Jellyfin, Discord, and the AnkiConnect proxy.
 
 ```mermaid
 flowchart TB
@@ -387,11 +269,11 @@ flowchart TB
   style Loop fill:#363a4f,stroke:#494d64,color:#cad3f5
 ```
 
-## Subtitle Prefetch Pipeline
+## Subtitle prefetch
 
-SubMiner can pre-tokenize upcoming subtitle lines before they appear on screen. When an external subtitle file (SRT, VTT, or ASS) is detected on the active track, the `SubtitlePrefetchService` parses all cues via the subtitle cue parser (`subtitle-cue-parser.ts`), identifies a priority window of upcoming lines based on the current playback position, and tokenizes them in the background through the same pipeline used for live subtitles. Results are stored directly into the `SubtitleProcessingController` cache, so when a subtitle actually appears during playback, it hits a warm cache and renders in ~30-50ms instead of ~200-320ms.
+SubMiner tokenizes upcoming subtitle lines before they appear, so they render from a warm cache. `SubtitlePrefetchService` (`src/core/services/subtitle-prefetch.ts`) gets the cue list from the active track: an external subtitle file, or for local media an embedded text track extracted with ffmpeg. It parses the cues with `subtitle-cue-parser.ts`, picks a window of upcoming lines from the playback position, and tokenizes them through the live pipeline, storing results in the `SubtitleProcessingController` cache.
 
-The prefetcher yields to live subtitle processing (which always takes priority over background work) and re-computes its priority window on seek. Cache invalidation events (e.g. marking a word as known) trigger re-prefetching of the current window to keep results fresh.
+Live subtitle processing always takes priority; the prefetcher pauses while the on-screen line is being processed. It recomputes its window on seek and re-prefetches when the cache is invalidated, for example after a word is marked known.
 
 ```mermaid
 flowchart TB
@@ -400,7 +282,7 @@ flowchart TB
   classDef runtime fill:#8bd5ca,stroke:#494d64,color:#24273a,stroke-width:1.5px
   classDef warmup fill:#eed49f,stroke:#494d64,color:#24273a,stroke-width:1.5px
 
-  SubFile["External Sub File"]:::init
+  SubFile["Subtitle Track"]:::init
   Parse["Cue Parser"]:::phase
   Window["Upcoming Lines"]:::phase
   Tokenize["Pre-tokenize"]:::warmup
@@ -417,22 +299,11 @@ flowchart TB
   style Render stroke-width:2px
 ```
 
-## Why This Design
+## Extension rules
 
-- **Smaller blast radius:** changing one feature usually touches one service.
-- **Better testability:** most behavior can be tested without Electron windows/mpv.
-- **Better reviewability:** PRs can be scoped to one subsystem.
-- **Backward compatibility:** CLI flags and IPC channels can remain stable while internals evolve.
-- **Runtime registry + domain barrels:** `src/main/runtime/registry.ts` and `src/main/runtime/domains/*` reduce direct fan-in inside `main.ts` while keeping domain ownership explicit.
-- **Extracted composition root:** `main.ts` delegates to focused modules under `src/main/` and `src/main/runtime/composers/` for lifecycle, IPC, overlay, mpv, shortcut, and integration wiring.
-- **Split MPV service layers:** MPV internals are separated into transport (`mpv-transport.ts`), protocol (`mpv-protocol.ts`), and properties/render metrics modules for maintainability.
-- **Config by domain:** defaults, option registries, and resolution are split by domain under `src/config/definitions/*` and `src/config/resolve/*`, keeping config evolution localized.
-
-## Extension Rules
-
-- Add behavior to an existing service in `src/core/services/*` or create a focused runtime module under `src/main/runtime/*`; avoid ad-hoc logic in `main.ts`.
-- Add new cross-process channels in `src/shared/ipc/contracts.ts` first, validate payloads in `src/shared/ipc/validators.ts`, then wire handlers in IPC runtime modules.
-- See also the contributor IPC onboarding page: [IPC + Runtime Contracts](/ipc-contracts).
-- If change spans startup/overlay/mpv/integration wiring, prefer composing through `src/main/runtime/domains/*` + `src/main/runtime/composers/*` rather than direct wiring in `main.ts`.
-- Keep service APIs explicit and narrowly scoped, and preserve existing CLI flag / IPC channel behavior unless the change is intentionally breaking.
-- Add or update focused tests (including malformed-payload IPC tests) when runtime boundaries or contracts change.
+- Add behavior to a service in `src/core/services/` or a focused module under `src/main/runtime/`. Keep new logic out of `main.ts`.
+- For changes that span startup, overlay, mpv, or integration wiring, compose through `src/main/runtime/domains/` and `src/main/runtime/composers/` instead of wiring directly in `main.ts`.
+- Add a cross-process channel in `src/shared/ipc/contracts.ts` first, validate it in `src/shared/ipc/validators.ts`, then wire the handler. See [IPC + runtime contracts](/ipc-contracts#add-a-new-ipc-action).
+- Config is split by domain under `src/config/definitions/` and `src/config/resolve/`. Keep config changes in the matching domain file.
+- Keep CLI flags and IPC channels stable unless a change is meant to break them.
+- Add or update focused tests when a runtime boundary or contract changes, including malformed-payload tests for IPC.
diff --git a/docs-site/archive-function.test.ts b/docs-site/archive-function.test.ts
new file mode 100644
index 00000000..ddbcaecc
--- /dev/null
+++ b/docs-site/archive-function.test.ts
@@ -0,0 +1,116 @@
+import { expect, test } from 'bun:test';
+import { onRequest, resolveArchiveRoute, type ArchiveBucket } from './functions/v/[[path]]';
+
+// In-memory stand-in for the R2 binding, including the range and precondition behavior
+// the function relies on.
+function fakeBucket(objects: Record<string, string>): ArchiveBucket {
+  return {
+    async get(key, options) {
+      const content = objects[key];
+      if (content === undefined) return null;
+      const bytes = new TextEncoder().encode(content);
+      const httpEtag = `"${key}"`;
+
+      if (options?.onlyIf?.get('if-none-match') === httpEtag) {
+        return { size: bytes.length, httpEtag };
+      }
+
+      const rangeHeader = options?.range?.get('range');
+      const match = rangeHeader ? /^bytes=(\d+)-(\d*)$/.exec(rangeHeader) : null;
+      if (match) {
+        const offset = Number(match[1]);
+        const end = match[2] ? Number(match[2]) : bytes.length - 1;
+        const slice = bytes.slice(offset, end + 1);
+        return {
+          size: bytes.length,
+          httpEtag,
+          range: { offset, length: slice.length },
+          body: new Blob([slice]).stream(),
+        };
+      }
+
+      return { size: bytes.length, httpEtag, body: new Blob([bytes]).stream() };
+    },
+  };
+}
+
+const bucket = fakeBucket({
+  'v/0.19.6/index.html': '<h1>home</h1>',
+  'v/0.19.6/usage.html': '<h1>usage</h1>',
+  'v/0.19.6/404.html': '<h1>missing</h1>',
+  'v/0.19.6/assets/app.abc123.js': 'console.log(1)',
+});
+
+function request(path: string, init?: RequestInit) {
+  return onRequest({
+    request: new Request(`https://docs.subminer.moe${path}`, init),
+    env: { DOCS_ARCHIVES: bucket },
+  });
+}
+
+test('archive routes follow the clean-URL layout of the built archives', () => {
+  expect(resolveArchiveRoute('/v/0.19.6/usage')).toEqual({
+    kind: 'lookup',
+    version: '0.19.6',
+    keys: ['v/0.19.6/usage.html', 'v/0.19.6/usage/index.html'],
+  });
+  expect(resolveArchiveRoute('/v/0.19.6/')).toEqual({
+    kind: 'lookup',
+    version: '0.19.6',
+    keys: ['v/0.19.6/index.html'],
+  });
+  expect(resolveArchiveRoute('/v/0.19.6', '?q=1')).toEqual({
+    kind: 'redirect',
+    location: '/v/0.19.6/?q=1',
+    status: 301,
+  });
+  expect(resolveArchiveRoute('/v/')).toEqual({
+    kind: 'redirect',
+    location: '/versions',
+    status: 302,
+  });
+  expect(resolveArchiveRoute('/v/0.19.6/%2e%2e/secret')).toEqual({ kind: 'not-found' });
+  expect(resolveArchiveRoute('/v/latest/')).toEqual({ kind: 'not-found' });
+});
+
+test('serves archive pages and hashed assets with their cache policy', async () => {
+  const page = await request('/v/0.19.6/usage');
+  expect(page.status).toBe(200);
+  expect(page.headers.get('content-type')).toBe('text/html; charset=utf-8');
+  expect(page.headers.get('cache-control')).toBe('public, max-age=3600');
+  expect(page.headers.get('x-robots-tag')).toBe('noindex, follow');
+  expect(await page.text()).toBe('<h1>usage</h1>');
+
+  const asset = await request('/v/0.19.6/assets/app.abc123.js');
+  expect(asset.headers.get('content-type')).toBe('text/javascript; charset=utf-8');
+  expect(asset.headers.get('cache-control')).toContain('immutable');
+});
+
+test('missing archive pages fall back to the archive 404 page', async () => {
+  const response = await request('/v/0.19.6/nope');
+  expect(response.status).toBe(404);
+  expect(await response.text()).toBe('<h1>missing</h1>');
+
+  const unknownVersion = await request('/v/0.1.0/usage');
+  expect(unknownVersion.status).toBe(404);
+});
+
+test('supports byte ranges, conditional requests, and HEAD', async () => {
+  const partial = await request('/v/0.19.6/usage', { headers: { Range: 'bytes=4-8' } });
+  expect(partial.status).toBe(206);
+  expect(partial.headers.get('content-range')).toBe('bytes 4-8/14');
+  expect(await partial.text()).toBe('usage');
+
+  const notModified = await request('/v/0.19.6/usage', {
+    headers: { 'If-None-Match': '"v/0.19.6/usage.html"' },
+  });
+  expect(notModified.status).toBe(304);
+
+  const head = await request('/v/0.19.6/usage', { method: 'HEAD' });
+  expect(head.status).toBe(200);
+  expect(head.headers.get('content-length')).toBe('14');
+  expect(await head.text()).toBe('');
+
+  const post = await request('/v/0.19.6/usage', { method: 'POST' });
+  expect(post.status).toBe(405);
+});
diff --git a/docs-site/changelog.md b/docs-site/changelog.md
index 335aa870..4717bb91 100644
--- a/docs-site/changelog.md
+++ b/docs-site/changelog.md
@@ -1,6 +1,219 @@
 # Changelog
 
-## v0.19.3 (2026-08-13)
+## v0.20.0 (2026-09-23)
+
+**Added**
+- **Japanese Subtitle Generation**:
+  - Generate Japanese SRT subtitles locally with whisper.cpp. Start it from a new modal (Ctrl+Shift+G), from the generate button in an empty subtitle sidebar, or with `subminer generate-subs`.
+  - Generation shows progress, can be cancelled, and loads the finished subtitles into mpv automatically.
+  - Pick an official multilingual Whisper model, including quantized variants, with size and accuracy guidance. You can download it in the app or point Settings at a model you already have.
+  - `large-v3-turbo` is recommended when CUDA support is detected, and `small` otherwise.
+  - whisper-cli, ffmpeg, and ffprobe are found on PATH unless you override them. SubMiner names any missing tools before a download starts.
+  - An optional "Focus on spoken dialogue" mode uses a separately downloaded Silero VAD model. It keeps audible sections it is unsure about, so dialogue under music is not dropped, but songs may also be transcribed.
+  - Long passages are split near speech starts or quiet pauses to reduce subtitles that appear too early. When an eligible embedded or external subtitle track is loaded in mpv, it guides the split points.
+  - Each passage runs in a fresh Whisper process, which prevents repeated-character output.
+- **Subtitle Selection Modal**:
+  - An optional modal for choosing primary and secondary mpv subtitle tracks.
+  - Turn it on in Settings under Behavior, then press g followed by s to open it. Turning it off restores mpv's own subtitle selection binding.
+  - Single-key actions take priority over configured key sequence prefixes.
+  - Conflicting sequences are disabled with a warning, and the existing y commands stay reserved.
+- **Subtitle Sidebar Copy**:
+  - Select dialogue across several sidebar rows and copy it without timestamps using Ctrl/Cmd+C or the Copy button.
+  - Selecting text does not seek playback and does not require mining a card.
+- **Media Timing Review Screenshot Picker**:
+  - Choose the still screenshot separately from the audio range, with a live preview and its own time slider.
+  - Step through decoded frames one at a time to get the exact frame you want.
+  - Works with local video and with seekable remote streams such as Jellyfin.
+- **mpv Keybindings in the Overlay**:
+  - The overlay now picks up keyboard bindings from mpv defaults, `input.conf`, and loaded scripts when they do not conflict with SubMiner.
+  - SubMiner controls and bindings you explicitly disabled take precedence.
+  - These bindings apply only to the current session and are not listed in the help menu.
+- **Jimaku Live Action Search**: The Jimaku modal has new Anime and Live action tabs, so you can search Jimaku's live action catalogue as well as anime. Use Arrow Left and Arrow Right to switch tabs.
+- **TMDB Live-Action Library**:
+  - Live-action dramas and movies in the stats Library now get posters, synopses, and titles from TMDB.
+  - Release builds include a project key. Setting `tmdb.apiKey` or `tmdb.apiKeyCommand` overrides it, and one of them is required when running from source.
+  - Titles that AniList cannot match are looked up on TMDB automatically when the parsed filename exactly matches a Japanese live-action title. For everything else, use the new **Link to TMDB** action.
+  - Entries linked to the same TMDB title merge into one card, and the Library kind selector has a new Live Action option.
+  - If a replacement download fails during provider reassignment, the previous link and artwork are kept. Merges and sync keep AniList and TMDB identities separate, and the merge dialog explains mixed selections instead of failing.
+- **YouTube Library Kind**:
+  - YouTube channels are now their own Library media kind. Existing channel entries migrate automatically, and viewing history and manual video assignments are unchanged.
+  - New All Titles, Anime, and YouTube Library filters.
+  - Channels are excluded from AniList matching, season repair, and duplicate recommendations.
+  - Merges and video moves can no longer combine an anime entry with a YouTube channel.
+
+**Changed**
+- **Launcher Uses Bundled Bun**:
+  - Every installed and downloadable launcher now runs on the Bun runtime that ships with SubMiner. A system Bun is no longer needed.
+  - Recognized legacy launchers migrate automatically.
+  - Windows gets a `subminer.cmd` launcher download.
+  - First-run setup is reduced to one optional launcher control. Runtime repair guidance appears only when it is needed.
+- **Faster Sync Transfers**:
+  - Sync between compatible macOS and Linux machines now uses compressed, incremental rsync transfers.
+  - The last snapshot received from each peer is cached, which reduces traffic on later syncs.
+  - Machines without a compatible rsync, including Windows, fall back to compressed scp.
+  - Older peers still work without the upload cache.
+  - Transfers abort after 30 minutes.
+- **Stats Server Request Safety**:
+  - The stats server now accepts loopback hosts only and rejects requests from browser origins other than its own.
+  - Requests that change data must send an `application/json` body. Scripts that POST to the server need to set a JSON content type.
+  - The in-app stats overlay now loads from the local server, so it gets the same protection.
+  - Dashboards served through a reverse proxy or Tailscale Serve are no longer supported.
+- **Smaller Downloads**:
+  - Installers and unpacked apps are smaller. Demo media, source maps, TypeScript sources, test fixtures, and unused Koffi binaries are no longer packaged.
+  - All windows now share one Japanese UI font.
+  - Release builds publish package size reports that compare against the previous release.
+- **Bundled Yomitan**: Updated with upstream Yomitan 26.9.8 changes, including historical Japanese kana transformations, Ukrainian language support, and improvements to Anki duplicate searches and audio retrieval.
+
+**Fixed**
+- **Jellyfin 12 Compatibility**:
+  - Playback, subtitle, artwork, and remote-control requests now authenticate with the `ApiKey` query parameter, so the integration works on Jellyfin 12, where legacy authorization is off by default.
+  - "Play on SubMiner" stays available. The cast connection now answers keep-alive requests and reconnects when the server stops responding, instead of silently dying after about a minute.
+  - The Jellyfin "now playing" bar clears when you close or finish a cast video instead of running on to the end of the episode.
+  - Cards mined during Jellyfin playback get the episode title in the misc info field again instead of "Unknown media".
+- **Jellyfin Privacy and Playback**:
+  - Jellyfin streams no longer leak titles taken from the stream URL, or stream URLs that contain credentials, into metadata lookups, Anki source fields, Discord presence, stats, or AniList retries.
+  - Previously cached metadata that contained credentials is cleaned up. Watch history and library assignments are not touched.
+  - Jellyfin playback and casting now use your configured mpv executable, so they work when mpv is installed outside PATH. Portable plugins next to that executable are detected.
+- **Anki Mining**:
+  - New `ankiConnect.fields.wordAudio` setting reads word audio separately from the sentence audio field. This fixes animated images that started moving immediately when `fields.audio` pointed to `SentenceAudio`. Existing animated images need to be regenerated to pick up the fix.
+  - Sentence furigana on word cards stays in sync with the full stats-search context and with expanded timing review selections. Stale readings are cleared if regeneration fails.
+  - Closing the overlay while media timing review is still loading now cancels the review, resumes playback if the review paused it, and cleans up the hidden preview player.
+  - `ankiConnect.media.maxMediaDuration: 0` now means unlimited when mining from the stats dashboard, matching overlay mining.
+  - Invalid AnkiConnect, Kiku, and Senren settings are now rejected with a warning and fall back to defaults.
+- **Stats Server Stability**:
+  - A port conflict is now reported in a status notification instead of crashing SubMiner.
+  - Simultaneous startup requests share one server start. Stopping the background server no longer disconnects dashboards open in the foreground.
+  - Shutdown waits only a limited time for active requests to finish.
+  - Malformed resource IDs, and ID lists with any invalid entries, are rejected before Library changes or cover backfills run.
+- **Subtitle Sidebar**:
+  - Clicking a cue no longer leaves the row focused, and Space no longer seeks back to a focused cue. Enter still seeks to the focused cue, and Space keeps its configured playback action.
+  - The sidebar stays near the current playback position during gaps when the subtitle file has a cue that starts at zero.
+- **Settings Save Feedback**:
+  - Settings marked LIVE no longer show false restart warnings, including for notifications and subtitle generation.
+  - When a save mixes live and restart-only changes, the live changes apply right away and only the changed sections that need a restart are listed.
+- **Overlay Windows**:
+  - On Hyprland, recovery dialogs stay above SubMiner windows so overlay placement updates no longer cover their Wait and Close buttons.
+  - On Linux, a delayed close callback during teardown can no longer reopen the overlay.
+- **First Launch on macOS**: SubMiner no longer exits on first launch when the config directory does not exist yet.
+
+**Docs**
+- **Launcher**: Documented the launcher install that uses the bundled runtime, migration from legacy launchers, package-managed updates, and the bundled Bun runtime's MIT and LGPL notices. The AUR package installs these notices under `/usr/share/licenses/subminer-bin`, and they are also included in `subminer-assets.tar.gz`.
+- **Subtitle Generation**: Documented model choice, VAD behavior, splitting guided by a reference track, fallback behavior, and known limits.
+- **Subtitle Selection**: Documented the subtitle selector setting, its shortcut override, and the primary and secondary track controls.
+- **Settings**: Clarified save feedback for live settings, warnings for saves that mix live and restart-only changes, and how subtitle generation settings reload.
+- **Jellyfin**:
+  - Clarified that Windows mpv playback and Jellyfin casting can use a configured executable path instead of PATH.
+  - Documented how Jellyfin media titles and stats identities keep stream credentials out of metadata.
+- **Stats Library**:
+  - Documented TMDB linking, provider reassignment, merge compatibility, and caching of the credential command's output.
+  - Documented YouTube channel filtering and video statistics in the Library.
+- **Mining**:
+  - Documented choosing the screenshot separately in media timing review.
+  - Documented the separate word audio field mapping, including that existing animated images need to be regenerated.
+- **Sync**: Documented compressed transfers, where the incremental sync cache is stored, and compatibility with older peers.
+
+<details>
+<summary>Internal changes</summary>
+
+**Internal**
+- Removed duplicate source and launcher smoke runs from the reusable CI quality gate. Every distinct test lane and failure artifact is kept.
+- Replaced mislabeled dist source reruns with a small Electron-runtime smoke check. It covers compiled stats startup, the HTTP service, native SQLite, port conflicts, and cleanup.
+
+</details>
+
+## Previous Versions
+
+<details>
+<summary>v0.19.x</summary>
+
+<h2>v0.19.6 (2026-09-04)</h2>
+
+**Added**
+
+- **Card Timing Review**:
+  - Optional pre-generation timing review for word, sentence, and audio cards, with a speech-weighted waveform that flattens background noise so dialogue edges stand out clearly.
+  - The clip end automatically snaps back to where the line's dialogue actually ends once the waveform loads, with drag and keyboard adjustments available.
+  - Audio preview includes a sweeping playhead that plays the clip to its true end, even on high-latency outputs like Bluetooth headphones.
+  - Previous and next subtitle lines can be pulled onto the card with `P`/`N` (or the Prev/Next steppers) and removed with Shift; the sentence preview and waveform markers update automatically.
+  - Cancelling lets you keep a card without media, and the review can be toggled on or off for the session.
+- **Senren Field Grouping**:
+  - Enable `ankiConnect.isSenren` to merge duplicate mined cards using Senren's scene-switching markup, grouping sentence, furigana, audio, picture, and misc-info fields.
+  - Supports the same auto/manual/disabled modes as Kiku, including the manual merge modal; only one of Senren or Kiku can be enabled at a time.
+
+**Changed**
+
+- **Remote Stream Mining Performance**: Mining a card from a remote stream (Jellyfin and other HTTP sources) now downloads the clip window once and reuses it for the timing review waveform, audio preview, audio extraction, and screenshot, instead of re-fetching the stream at each step; the temporary file is cleaned up after ten minutes of inactivity or on exit.
+- **TsukiHime Release Filtering**: The TsukiHime modal's Japanese and secondary-language tabs now filter the release list by the subtitle languages each release actually carries, and report when no release has subtitles for the active tab.
+
+**Fixed**
+
+- **Subtitle & Mining Accuracy**:
+  - Broadcast-style captions that split one sentence across two on-screen rows (e.g. Crunchyroll Japanese subs) now merge into a single line for the sidebar and mined cards, while separate speakers, sound effects, and labeled turns still stay on their own lines.
+  - Mining from the overlay no longer pulls in a lingering row from the previous caption; the mined sentence and clip timing now match what's actually on screen.
+  - Multi-line copy and mining now select lines backward in timeline order after seeking, instead of in playback encounter order.
+  - Copying a subtitle, mining a sentence, or recording immersion stats no longer includes the separate furigana line that broadcast ASS captions place above a word.
+- **Card Update Notifications**: Dismissed lingering overlay card-update progress when notification settings switch to OSD before an update finishes.
+- **Overlay Stability on Hyprland**: Opening a modal window (timing review, Jimaku, session help, and others) while mpv is fullscreen no longer causes the overlay to flicker while the modal loads; the overlay now stays on screen untouched until the modal is ready.
+- **Jellyfin Subtitle Sync**: Jellyfin subtitle files now load with zero mpv delay instead of inferring and saving an offset from Japanese and English cue timelines.
+- **Secondary Subtitle Visibility**: Native mpv secondary subtitles stay hidden when switching secondary subtitle tracks during playback.
+
+<h2>v0.19.5 (2026-08-30)</h2>
+
+**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.
+
+<h2>v0.19.4 (2026-08-25)</h2>
+
+**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>
+
+<h2>v0.19.3 (2026-08-13)</h2>
 
 **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`).
@@ -24,7 +237,7 @@
 
 </details>
 
-## v0.19.2 (2026-08-04)
+<h2>v0.19.2 (2026-08-04)</h2>
 
 **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.
@@ -42,7 +255,7 @@
 
 </details>
 
-## v0.19.1 (2026-08-01)
+<h2>v0.19.1 (2026-08-01)</h2>
 
 **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.
@@ -51,7 +264,7 @@
 - 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)
+<h2>v0.19.0 (2026-07-29)</h2>
 
 **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.
@@ -87,7 +300,7 @@
 
 </details>
 
-## Previous Versions
+</details>
 
 <details>
 <summary>v0.18.x</summary>
diff --git a/docs-site/character-dictionary.md b/docs-site/character-dictionary.md
index c6eca7ea..c356e81c 100644
--- a/docs-site/character-dictionary.md
+++ b/docs-site/character-dictionary.md
@@ -1,313 +1,104 @@
-# Character Dictionary
+# Character dictionary
 
-SubMiner can build a Yomitan-compatible character dictionary from [AniList](https://anilist.co) metadata so that character names in subtitles are recognized, highlighted, and enrichable with context - portraits, roles, voice actors, and biographical detail - without leaving the overlay. (AniList is an online anime/manga database; SubMiner pulls each show's character list from it.)
+SubMiner builds a Yomitan dictionary of the characters in the show you are watching, using data from [AniList](https://anilist.co). Character names in subtitles get their own color, and hovering one shows the character's portrait, role, voice actor, and description.
 
-This is helpful because proper names rarely appear in normal dictionaries, so character names would otherwise be flagged as "unknown" words and clutter your mining. Recognizing them keeps your N+1 highlighting focused on real vocabulary.
+Ordinary dictionaries rarely contain character names, so without this every name counts as an unknown word and throws off [N+1 highlighting](/subtitle-annotations#n-1-word-highlighting).
 
-The dictionary is generated per-media, merged across your recently-watched titles, and auto-imported into Yomitan. When a character name appears in a subtitle line, it gets highlighted and becomes available for hover-driven Yomitan profile lookup.
+## Turning it on
 
-## How It Works
-
-The feature has three stages: **snapshot**, **merge**, and **match**.
-
-1. **Snapshot** - When you start watching a new title, SubMiner queries the AniList GraphQL API for the media's character list. Each character's names, reading, role, description, birthday, voice actors, and portrait are fetched and saved as a local JSON snapshot in `character-dictionaries/snapshots/anilist-{mediaId}.json`. Images are downloaded and base64-encoded into the snapshot.
-
-2. **Merge** - SubMiner maintains a most-recently-used list of media IDs (default: 3). Snapshots from those titles are merged into a single Yomitan ZIP - `character-dictionaries/merged.zip` - which is always named "SubMiner Character Dictionary" so Yomitan treats it as a single stable dictionary across rebuilds.
-
-3. **Match** - During subtitle rendering, Yomitan scans subtitle text against all loaded dictionaries including the character dictionary. SubMiner only accepts character entries for the current AniList media when that media ID is known, then flags matching tokens with `isNameMatch` and highlights them in the overlay with a distinct color.
-
-## Enabling the Feature
-
-Character dictionary sync is disabled by default. To turn it on:
-
-1. Enable **Name Match** in Settings → Subtitle Style, or set `subtitleStyle.nameMatchEnabled: true` in your config.
-2. Start watching - SubMiner queries AniList's public GraphQL API (no authentication required) and imports the merged dictionary into Yomitan automatically.
-3. Optionally enable **Name Match Images** (Settings → Subtitle Style) to show inline circular character portraits next to matched names in subtitles.
+1. Set `subtitleStyle.nameMatchEnabled` to `true`, or turn it on in the Settings window under Annotation Display, Character Names.
+2. Optionally set `subtitleStyle.nameMatchImagesEnabled` to `true` to show a small portrait next to each name in the subtitle line.
+3. Play an episode.
 
 ```jsonc
 {
   "subtitleStyle": {
     "nameMatchEnabled": true,
-    "nameMatchImagesEnabled": true, // optional - inline portraits
+    "nameMatchImagesEnabled": true,
   },
 }
 ```
 
-::: tip
-The first sync for a media title takes a few seconds while character data and portraits are fetched from AniList. Subsequent launches reuse the cached media match and snapshot without a fresh AniList lookup.
-:::
+No AniList account is needed. Logging in to AniList is only for [watch progress sync](/anilist-integration).
 
-::: info
-AniList character data is fetched via public GraphQL queries - no account or access token is needed. AniList authentication is only required for the separate [watch-progress sync](/anilist-integration) feature.
-:::
+The character dictionary does not work when `yomitan.externalProfilePath` is set, because SubMiner then uses another app's Yomitan profile read-only.
 
-::: warning
-If `yomitan.externalProfilePath` is set, SubMiner switches to read-only external-profile mode. In that mode SubMiner can reuse another app's installed Yomitan dictionaries/settings, but SubMiner's own character-dictionary features are fully disabled.
-:::
+## What happens when you play something
 
-## Name Generation
+When a new show starts, SubMiner:
 
-A single character produces many searchable terms so that names are recognized regardless of how they appear in dialogue. SubMiner generates variants for:
+1. Guesses the title from the filename and finds it on AniList.
+2. Downloads the cast list and portraits.
+3. Builds the dictionary and imports it into SubMiner's Yomitan.
 
-**Spacing and combination:**
+A notification shows each step. Once it says the dictionary is ready, names match from the next subtitle line.
 
-- Full name with space: 須々木 心一
-- Combined form: 須々木心一
-- Family name alone: 須々木
-- Given name alone: 心一
+Each character gets entries for the full name, family name, given name, and common honorifics (`さん`, `君`, `ちゃん`, `先生`, and others), so `太郎さん` matches as well as `太郎`.
 
-Unspaced native names (AniList often stores 渡辺真奈美 without a separator) are split into family/given parts with MeCab when it is available: person-name POS tags (姓/名) decide the boundary, validated against AniList's romanized first/last name readings. Without MeCab, a length heuristic based on the romanized readings guesses the boundary — and because that guess can be ambiguous (東紫乃 could be 東+紫乃 or 東紫+乃), terms are generated for the top two candidate boundaries so the real surname still matches. Snapshots built without MeCab are regenerated automatically once MeCab becomes available, upgrading them to the exact splits.
+SubMiner keeps your most recent shows loaded in one merged dictionary. `anilist.characterDictionary.maxLoaded` sets how many. Starting another show drops the oldest one. Only the current show's characters are highlighted.
 
-**Middle-dot removal** (common in katakana foreign names):
+### How long it takes
 
-- ア・リ・ス → アリス (combined), plus individual segments
+The first time you watch a show, most of the time goes into downloading portraits, one at a time. A typical cast takes seconds to a minute. A very large cast takes much longer: One Piece has over a thousand characters and takes around 10 minutes. After that the show is cached, and later episodes load it from disk.
 
-**Honorific suffixes** - each base name is expanded with 15 common suffixes:
+## Correcting AniList matches
 
-| Honorific | Reading    |
-| --------- | ---------- |
-| さん      | さん       |
-| 様        | さま       |
-| 先生      | せんせい   |
-| 先輩      | せんぱい   |
-| 後輩      | こうはい   |
-| 氏        | し         |
-| 君        | くん       |
-| くん      | くん       |
-| ちゃん    | ちゃん     |
-| たん      | たん       |
-| 坊        | ぼう       |
-| 殿        | どの       |
-| 博士      | はかせ     |
-| 社長      | しゃちょう |
-| 部長      | ぶちょう   |
+SubMiner can match the wrong show when a filename is ambiguous, for example `Re - ZERO, Starting Life in Another World (2016)` matching a different `Re...` series. To fix it:
 
-**Romanized names** - names stored in romaji on AniList are converted to kana aliases so they can match against Japanese subtitle text.
+1. Press `Ctrl/Cmd+D` to open the character dictionary manager.
+2. Click **Override**, edit the title if needed, search, and pick the right result.
 
-This means a character like "太郎" generates entries for 太郎, 太郎さん, 太郎先生, 太郎君, 太郎ちゃん, and so on - all with correct readings.
-
-## Name Matching
-
-Name matching runs inside Yomitan's scanning pipeline during subtitle tokenization.
-
-1. Yomitan receives subtitle text and scans for dictionary matches.
-2. Entries from "SubMiner Character Dictionary" are checked with exact primary-source matching - the token must match the entry's `originalText` with `isPrimary: true` and `matchType: 'exact'`.
-3. When the current AniList media ID is known, entries whose embedded media ID belongs to a different title are ignored for name matching and inline portraits.
-4. Matched tokens are flagged `isNameMatch: true` and forwarded to the renderer.
-5. If `subtitleStyle.nameMatchEnabled` is enabled, the renderer applies the name-match highlight color (default: `#f5bde6`).
-6. If `subtitleStyle.nameMatchImagesEnabled` is enabled, the renderer also injects a small circular AniList portrait from the cached snapshot image data.
-
-Older snapshot schema versions are regenerated automatically. Current-version snapshots are normally reused, but when `subtitleStyle.nameMatchImagesEnabled` is enabled SubMiner also checks whether the cached snapshot contains usable character portrait data. If it does not, the snapshot is refreshed so the merged dictionary can include images.
-
-Name matches are visually distinct from [N+1 targeting, frequency highlighting, and JLPT tags](/subtitle-annotations) so you can tell at a glance whether a highlighted word is a character name or a vocabulary target.
-
-**Key settings:**
-
-| Option                                 | Default   | Description                               |
-| -------------------------------------- | --------- | ----------------------------------------- |
-| `subtitleStyle.nameMatchEnabled`       | `false`   | Enable dictionary sync and highlighting   |
-| `subtitleStyle.nameMatchImagesEnabled` | `false`   | Show small AniList portraits beside names |
-| `subtitleStyle.nameMatchColor`         | `#f5bde6` | Highlight color for matched names         |
-
-## Inline Character Portraits
-
-When `subtitleStyle.nameMatchImagesEnabled` is enabled, SubMiner injects a small circular portrait image directly into the subtitle line next to each matched character name.
-
-Portraits are sourced from the local snapshot - they are embedded at snapshot-generation time and served from the cached ZIP, so no network request happens during playback. Images are downloaded from AniList CDN once per character and stored in `character-dictionaries/img/`.
-
-If a snapshot was generated before portrait data was available (e.g. during an earlier version or offline sync), SubMiner detects the missing image data on the next media match and automatically refreshes the snapshot so portraits are included in the next merged dictionary build.
-
-**To enable:**
-
-- Settings → Subtitle Style → **Name Match Images**, or
-- `subtitleStyle.nameMatchImagesEnabled: true` in config.
-
-The portrait size is controlled by the surrounding subtitle font size and renders as a circle clipped from the character's AniList cover image.
-
-::: tip
-Inline portraits help you quickly associate names with faces while building vocabulary - especially useful for shows with large casts where you're still learning who's who.
-:::
-
-## Dictionary Entries
-
-Each character entry in the Yomitan dictionary includes structured content:
-
-- **Name** - the matched Japanese name form
-- **Known names** - generated non-honorific Japanese aliases for that character, excluding raw romanized/English aliases from lookup results
-- **Role badge** - color-coded by role: main / "Protagonist" (score 100), primary / "Main Character" (75), side / "Side Character" (50), appears / "Minor Role" (25). AniList's MAIN maps to main, SUPPORTING to primary, and BACKGROUND to side.
-- **Portrait** - character image from AniList, embedded in the ZIP
-- **Description** - biography text from AniList (collapsible)
-- **Character information** - age, birthday, gender, blood type (collapsible)
-- **Voiced by** - voice actor name and portrait (collapsible)
-
-The three collapsible sections can be configured to start open or closed:
-
-```jsonc
-{
-  "anilist": {
-    "characterDictionary": {
-      "collapsibleSections": {
-        "description": false,
-        "characterInformation": false,
-        "voicedBy": false,
-      },
-    },
-  },
-}
-```
-
-## Auto-Sync Lifecycle
-
-When `subtitleStyle.nameMatchEnabled` is `true`, SubMiner runs an auto-sync routine whenever the active media changes.
-
-These phases are emitted through the configured notification surface. Some phases are skipped when unnecessary: `generating` only appears on a cache miss, `building` only appears when the merged ZIP must be rebuilt, and `importing` only appears when Yomitan needs a new dictionary import.
-
-**Phases:**
-
-1. **checking** - Is there already a cached snapshot for this media ID?
-2. **generating** - No cache hit: fetch characters from AniList GraphQL, download portraits (250ms throttle between image requests), save snapshot JSON.
-3. MRU update (no notification) - add the media ID to the most-recently-used list and evict old entries beyond `maxLoaded`.
-4. **building** - Merge active snapshots into a single Yomitan ZIP. A SHA-1 revision hash is computed from the media set - if it matches the previously imported revision, the import is skipped.
-5. **importing** - Push the ZIP into Yomitan. Waits for Yomitan mutation readiness (7-second timeout per operation).
-6. **ready** - Dictionary is live. Character names will match on the next subtitle line.
-
-**State tracking** is persisted in `character-dictionaries/auto-sync-state.json`. AniList media matches are cached separately in `character-dictionaries/anilist-resolution-cache.json` so snapshot hits do not need another AniList search.
-
-```jsonc
-{
-  "activeMediaIds": ["170942 - Frieren", "163134 - ...", "154587 - ..."],
-  "mergedRevision": "a1b2c3d4e5f6",
-  "mergedDictionaryTitle": "SubMiner Character Dictionary",
-}
-```
-
-(Entries are `"<mediaId> - <title>"` label strings; bare numeric IDs from older versions are still read.)
-
-The `maxLoaded` setting (default: 3) controls how many media snapshots stay in the active set. When you start a 4th title, the oldest is evicted and the merged dictionary is rebuilt without it.
-
-## Manual Generation
-
-You can generate a character dictionary from the command line without auto-sync:
+From the command line:
 
 ```bash
-# Generate for a file or directory
-subminer dictionary /path/to/media
-
-# Generate for current anime (AppImage)
-SubMiner.AppImage --dictionary
-```
-
-This creates a standalone dictionary ZIP for the target media and saves it alongside the snapshots.
-
-## Correcting AniList Matches
-
-SubMiner uses `guessit` to infer the anime title from the active filename before searching AniList. Some filenames can still resolve to the wrong title. For example, `Re - ZERO, Starting Life in Another World (2016)` can be misread as a different `Re...` series.
-
-Use the in-app selector or CLI to pin the correct AniList media for the whole series:
-
-- In-app: open the manager with `Ctrl/Cmd+D`, use the **Override** tab/button, edit the prefilled title if needed, then search and choose the correct result.
-- CLI: `--dictionary-candidates` still lists matches for the current filename guess.
-
-```bash
-# List candidate AniList matches for a file
+# List AniList matches for a file
 subminer dictionary --candidates "/path/to/episode.mkv"
 
-# Save the correct AniList media ID for that series
+# Save the correct AniList ID for that series
 subminer dictionary --select 21355 "/path/to/episode.mkv"
-
-# Equivalent direct app flags
-SubMiner.AppImage --dictionary-candidates --dictionary-target "/path/to/episode.mkv"
-SubMiner.AppImage --dictionary-select --dictionary-anilist-id 21355 --dictionary-target "/path/to/episode.mkv"
-
-# Open the in-app selector from the running app
-subminer app --session-action '{"actionId":"openCharacterDictionaryManager"}'
 ```
 
-SubMiner stores manual selections in `character-dictionaries/anilist-overrides.json`. The episode's parent directory **and detected season** define the override scope, so later episodes in the same season keep the selected AniList ID even if their filename guesses differ, while a different season never inherits the override -- including when every season sits in one flat folder. When you replace a wrong match, SubMiner removes that stale media ID from the merged dictionary's active set and rebuilds/imports the merged character dictionary.
+The override applies to every episode of that season in the same folder. Other seasons are not affected, even when they share the folder. The override also sets which entry [AniList watch progress](/anilist-integration) updates, so one fix covers both.
 
-An override also pins the entry used for [AniList watch progress](/anilist-integration), so correcting a wrong match once fixes both the character dictionary and progress tracking.
+## Managing loaded shows
 
-## Managing Loaded Entries
+The manager (`Ctrl/Cmd+D`) lists the shows in the merged dictionary and marks the current one.
 
-Open the manager with `Ctrl/Cmd+D` (`shortcuts.openCharacterDictionaryManager`). The manager shows the merged dictionary's active MRU entries, marks the current anime, and lets you adjust eviction priority for the other loaded entries.
+- **Remove** drops a show from the dictionary. You cannot remove the show you are watching.
+- **Up/Down** changes which show gets dropped first when a new one is added.
+- **Override** replaces a show's AniList match.
 
-- **Remove** drops a non-current entry from the active merged dictionary and rebuilds/imports once.
-- **Up/Down** changes MRU order for future eviction; the merged dictionary is rebuilt and re-imported after a reorder.
-- **Override** opens the AniList selector for that entry's title so you can replace a saved loaded entry.
+## Generating from the command line
 
-The current anime cannot be removed while you are watching it; it stays loaded until playback changes.
-
-## File Structure
-
-All character dictionary data lives under `{userData}/character-dictionaries/`:
-
-```text
-character-dictionaries/
-  snapshots/
-    anilist-170942.json       # Per-media character snapshot
-    anilist-163134.json
-  merged.zip                  # Active merged dictionary (imported into Yomitan)
-  auto-sync-state.json        # Tracks active media IDs and revision
-  anilist-overrides.json      # Manual series-to-AniList overrides
-  img/
-    m170942-c12345.jpg        # Character portrait
-    m170942-va67890.jpg       # Voice actor portrait
+```bash
+subminer dictionary /path/to/media
 ```
 
-**Snapshot format** (v19, `CHARACTER_DICTIONARY_FORMAT_VERSION`): each snapshot contains the media ID, title, entry count, timestamp, an array of Yomitan term entries, and base64-encoded images. Snapshots with a different format version are regenerated.
+This builds a standalone dictionary file for that file or folder without playing it. With the AppImage directly, use `SubMiner.AppImage --dictionary`.
 
-**ZIP structure** follows the Yomitan dictionary format:
+## Configuration
 
-```text
-merged.zip
-  index.json                  # { title, revision, format: 3, author: "SubMiner", description }
-  tag_bank_1.json             # Tag definitions
-  term_bank_1.json            # Up to 10,000 terms per bank
-  term_bank_2.json
-  img/                        # Embedded character and VA portraits
-```
+Defaults are in the [configuration reference](/configuration).
 
-## Configuration Reference
-
-| Option                                                                 | Default   | Description                                                     |
-| ---------------------------------------------------------------------- | --------- | --------------------------------------------------------------- |
-| `anilist.characterDictionary.maxLoaded`                                | `3`       | Number of recent media snapshots kept in the merged dictionary  |
-| `anilist.characterDictionary.profileScope`                             | `"all"`   | Apply dictionary to `"all"` Yomitan profiles or `"active"` only |
-| `anilist.characterDictionary.collapsibleSections.description`          | `false`   | Start Description section expanded                              |
-| `anilist.characterDictionary.collapsibleSections.characterInformation` | `false`   | Start Character Information section expanded                    |
-| `anilist.characterDictionary.collapsibleSections.voicedBy`             | `false`   | Start Voiced By section expanded                                |
-| `subtitleStyle.nameMatchEnabled`                                       | `false`   | Enable character-dictionary sync and name highlighting          |
-| `subtitleStyle.nameMatchImagesEnabled`                                 | `false`   | Show small AniList portraits beside matched names               |
-| `subtitleStyle.nameMatchColor`                                         | `#f5bde6` | Highlight color for character-name matches                      |
-
-## Reference Implementation
-
-SubMiner's character dictionary builder is inspired by the [Japanese Character Name Dictionary](https://github.com/bee-san/Japanese_Character_Name_Dictionary) project - a standalone Rust web service that generates Yomitan character dictionaries from AniList and VNDB data.
-
-The reference implementation covers similar ground - name variant generation, honorific expansion, structured Yomitan content, portrait embedding - and additionally supports VNDB as a data source for visual novel characters. Key differences:
-
-|                        | SubMiner                                     | Reference Implementation              |
-| ---------------------- | -------------------------------------------- | ------------------------------------- |
-| **Runtime**            | TypeScript, runs inside Electron             | Rust, standalone web service          |
-| **Data sources**       | AniList only                                 | AniList + VNDB                        |
-| **Delivery**           | Auto-synced into bundled Yomitan             | ZIP download via web UI               |
-| **Honorific strategy** | Eager generation at build time               | Lazy generation during ZIP export     |
-| **Caching**            | File-based snapshots                         | Multi-tier (memory + disk + SQLite)   |
-| **Updates**            | Revision-hashed; skips reimport if unchanged | URL-encoded settings for auto-refresh |
-
-If you work with visual novels or want a standalone dictionary generator independent of SubMiner, the reference implementation is worth checking out.
+| Key                                                                    | What it does                                     |
+| ---------------------------------------------------------------------- | ------------------------------------------------ |
+| `subtitleStyle.nameMatchEnabled`                                       | Build the dictionary and color character names   |
+| `subtitleStyle.nameMatchImagesEnabled`                                 | Show a portrait next to matched names            |
+| `subtitleStyle.nameMatchColor`                                         | Color for character names                        |
+| `anilist.characterDictionary.maxLoaded`                                | Number of recent shows kept in the dictionary    |
+| `anilist.characterDictionary.collapsibleSections.description`          | Show the description expanded in the popup       |
+| `anilist.characterDictionary.collapsibleSections.characterInformation` | Show age, birthday, and similar details expanded |
+| `anilist.characterDictionary.collapsibleSections.voicedBy`             | Show the voice actor section expanded            |
+| `shortcuts.openCharacterDictionaryManager`                             | Shortcut for the manager                         |
 
 ## Troubleshooting
 
-- **Names not highlighting:** Confirm `subtitleStyle.nameMatchEnabled` is `true`. Check that the current media has an AniList entry - SubMiner needs a media ID to fetch characters.
-- **Inline portraits missing:** Confirm `subtitleStyle.nameMatchImagesEnabled` is `true`. On the next character dictionary sync, SubMiner refreshes current-version snapshots that do not contain usable cached character portrait data. Portraits still require AniList to return an image and the image download to succeed.
-- **Sync seems stuck:** The auto-sync debounces for 800ms after media changes and throttles image downloads at 250ms per image. Large casts (50+ characters) take longer. Check the status bar for the current sync phase.
-- **Wrong characters showing:** Open the in-app character dictionary manager (`Ctrl/Cmd+D`) to remove/reorder loaded titles, then use **Override** to correct the active AniList match. You can also run `--dictionary-candidates`, then save the correct media with `--dictionary-select --dictionary-anilist-id <id>`. SubMiner ignores character entries from other loaded titles for subtitle name matching and inline portraits once the current media ID is known.
-- **Yomitan import fails:** SubMiner waits up to 7 seconds for Yomitan to be ready for mutations. If Yomitan is still loading dictionaries or performing another import, the operation may time out. Restarting the overlay typically resolves this.
-- **Portraits missing:** Images are downloaded from AniList CDN during snapshot generation. If the network was unavailable during the initial sync, delete the snapshot file from `character-dictionaries/snapshots/` and let it regenerate.
+**It seems stuck.** Check the notification. While generating it shows counts (`image 120/400`), an estimate of time left, and an elapsed clock. If the clock moves, it is still working, and large casts are slow (see [how long it takes](#how-long-it-takes)). If you missed the notification, open the notification history with `Ctrl/Cmd+N`. For errors, check the app log ([log locations](/troubleshooting)).
 
-## Related
+**Import failed or timed out.** Yomitan may have been busy importing another dictionary. Play the next episode or restart SubMiner. The import may have finished anyway, so check for the character popup before retrying.
 
-- [Subtitle Annotations](/subtitle-annotations) - how name matches interact with N+1, frequency, and JLPT layers
-- [AniList Integration](/anilist-integration) - watch-progress sync and AniList authentication (separate from character dictionary)
-- [Configuration Reference](/configuration) - full config options
+**Names are not highlighted.** Check that `subtitleStyle.nameMatchEnabled` is `true`, that `yomitan.externalProfilePath` is empty, and that the show was found on AniList. The wrong show's cast means a wrong match. See [correcting AniList matches](#correcting-anilist-matches).
+
+**Portraits are missing.** Portraits need AniList to have an image and the download to succeed. If you were offline during the first sync, delete that show's file from `character-dictionaries/snapshots/` in the SubMiner config directory and replay it.
+
+SubMiner's generator is based on the [Japanese Character Name Dictionary](https://github.com/bee-san/Japanese_Character_Name_Dictionary) project, which also supports VNDB and works without SubMiner.
diff --git a/docs-site/configuration.md b/docs-site/configuration.md
index 6726c5b3..b3de3142 100644
--- a/docs-site/configuration.md
+++ b/docs-site/configuration.md
@@ -8,74 +8,24 @@ outline: [2, 3]
 import { withBase } from 'vitepress';
 </script>
 
-SubMiner is configured through a single file (`config.jsonc`). Most settings are also editable from the in-app **Settings** window - you rarely need to edit the file by hand. This page is the full reference: it explains the Settings window, where the config file lives, and documents every option grouped by topic. New to SubMiner? The Quick Start below plus the [Settings window](#settings) cover everything most users need.
+All SubMiner settings live in one file, `config.jsonc`. Most of them are also editable in the Settings window, so you rarely need to edit the file by hand. This page lists every config block with its keys and defaults.
 
-## Quick Start
+## Config file {#configuration-file}
 
-For most users, start with this minimal configuration:
+| Platform     | Path                                                                                  |
+| ------------ | ------------------------------------------------------------------------------------- |
+| Linux, macOS | `$XDG_CONFIG_HOME/SubMiner/config.jsonc` (`~/.config/SubMiner/config.jsonc` if unset) |
+| Windows      | `%APPDATA%\SubMiner\config.jsonc`                                                     |
 
-```json
-{
-  "ankiConnect": {
-    "enabled": true,
-    "deck": "YourDeckName",
-    "knownWords": {
-      "decks": {
-        "YourDeckName": ["Word"]
-      }
-    },
-    "fields": {
-      "sentence": "Sentence",
-      "audio": "Audio",
-      "image": "Image"
-    }
-  }
-}
-```
+The file is JSONC, so comments and trailing commas are allowed. If both `config.jsonc` and `config.json` exist, SubMiner uses `config.jsonc`. Only add the keys you want to change. Everything else uses the built-in default.
 
-Use the known-word deck map to choose which Anki decks and note fields feed the known-word cache.
+The [generated example config](/config.example.jsonc) lists every option with its default and a comment. Defaults in the tables below come from that file.
 
-Then customize as needed using the sections below.
-
-## Settings
-
-SubMiner includes a dedicated **Settings** window accessible from the tray menu, the app `--settings` flag, or launcher commands such as `subminer --settings` and `subminer settings`. It is the primary way to configure SubMiner - all changes are written directly to `config.jsonc`, so manual file editing is not required for most users.
-
-The Settings window groups options by workflow instead of mirroring the raw config-file shape:
-
-- Appearance
-- Behavior
-- Mining & Anki
-- Input
-- Integrations
-- Tracking & App
-- Advanced
-
-Playback-related fields live as sections inside these groups (for example "Playback Behavior" under **Behavior** and "mpv Playback" / "YouTube Playback Settings" under **Integrations**).
-
-Each field still writes to its current `config.jsonc` path. For example, subtitle hover pause appears under **Behavior** / playback behavior, but saves to `subtitleStyle.autoPauseVideoOnHover`. Anki-aware fields can query AnkiConnect for deck names, note types, and field names. The AnkiConnect deck field also reads Yomitan's current mining deck and persists it into an empty setting when one is found. Stats mining also uses Yomitan's current mining deck when `ankiConnect.deck` is empty. Keybinding fields use click-to-learn controls instead of raw text boxes.
-
-The Settings window preserves existing JSONC comments, trailing commas, and unrelated keys. Resetting a field removes the explicit config path so the built-in default applies.
-
-Secret fields do not display stored values. They show whether a value is configured; entering a new value writes it, and reset clears the explicit path. Prefer command-based secret options such as `ai.apiKeyCommand` when available.
-
-Saving validates the candidate config before writing. Live-reloadable changes are applied immediately; other changes return a restart-required banner in the window.
-
-## Configuration File
-
-The Settings window writes to `config.jsonc` directly, so most users do not need to edit the file by hand. The config file and the option reference below are provided for advanced use, scripting, or cases where you prefer editing config directly.
-
-Settings are stored in `$XDG_CONFIG_HOME/SubMiner/config.jsonc` (or `~/.config/SubMiner/config.jsonc` when `XDG_CONFIG_HOME` is unset).
-On Windows, the default path is `%APPDATA%\SubMiner\config.jsonc`.
-When both files exist, SubMiner prefers `config.jsonc` over `config.json`.
-
-See [config.example.jsonc](/config.example.jsonc) for a comprehensive example with all available options, default values, and detailed comments. Only include the options you want to customize in your config file.
-
-::: warning One value in that file is platform-specific
-The example is generated with a fixed Linux/macOS socket path so it stays reproducible, so it shows `"socketPath": "/tmp/subminer-socket"`. On Windows the real default is `\\\\.\\pipe\\subminer-socket`. Leave `mpv.socketPath` out of your config entirely unless you need a custom path, and SubMiner picks the right one for your platform.
+::: warning mpv.socketPath differs on Windows
+The example shows `"socketPath": "/tmp/subminer-socket"`. On Windows the default is `\\.\pipe\subminer-socket`. Leave `mpv.socketPath` out of your config unless you need a custom path, and SubMiner picks the right one.
 :::
 
-Generate a fresh default config from the centralized config registry:
+To write a fresh default config:
 
 ```bash
 SubMiner.AppImage --generate-config
@@ -83,1066 +33,391 @@ SubMiner.AppImage --generate-config --config-path /tmp/subminer.jsonc
 SubMiner.AppImage --generate-config --backup-overwrite
 ```
 
-- `--generate-config` writes a default JSONC config template.
-- JSONC config supports comments and trailing commas.
-- If the target file exists, SubMiner prompts to create a timestamped backup and overwrite.
-- In non-interactive shells, use `--backup-overwrite` to explicitly back up and overwrite.
-- On Windows, generated configs default to `%APPDATA%\SubMiner\config.jsonc`.
+If the target file exists, SubMiner asks before backing it up and overwriting it. In non-interactive shells, pass `--backup-overwrite`.
 
-Malformed config syntax (invalid JSON/JSONC) is startup-blocking: SubMiner shows a clear parse error with the config path and asks you to fix the file and restart.
+A syntax error in the file stops startup with a message that names the file. A valid file with a bad value logs a warning and uses the default for that key. On macOS, these warnings also open a dialog.
 
-For valid JSON/JSONC with invalid option values, SubMiner uses warn-and-fallback behavior: it logs the bad key/value and continues with the default for that option.
+## Settings window {#settings}
 
-On macOS, these validation warnings also open a native dialog with full details (desktop notification banners can truncate long messages).
+Open it from the tray menu, with `subminer settings`, or with the app's `--settings` flag. Options are grouped by task (Appearance, Behavior, Mining & Anki, Input, Integrations, Tracking & App, Advanced) rather than by config block, but each field saves to its normal `config.jsonc` path.
 
-### Hot-Reload Behavior
+- Saving keeps your comments, trailing commas, and unrelated keys. Resetting a field removes its key so the default applies.
+- Each field is tagged **Live** or **Restart**. After saving, a banner lists any sections that need a restart.
+- Anki fields can fetch deck, note type, and field names from AnkiConnect.
+- Secret fields never show the stored value, only whether one is set. Prefer the `*Command` variants (such as `jimaku.apiKeyCommand`) to keep keys out of the file.
 
-SubMiner watches the active config file (`config.jsonc` or `config.json`) while running and applies supported updates automatically.
+## Hot-reload {#hot-reload-behavior}
 
-Hot-reloadable settings include subtitle appearance, sidebar controls, keybindings,
-shortcuts, notifications, logging level, selected source-language preferences,
-Jimaku/Subsync settings, AniSkip settings (`mpv.aniskipEnabled`, `mpv.aniskipButtonKey`),
-stats keys (`stats.toggleKey`, `stats.markWatchedKey`), the secondary-subtitle default
-mode, and the Anki deck, known-word, N+1, field, sentence-card, AI, and Kiku options
-listed in the reference tables below.
+SubMiner watches the config file while running. When it changes, live settings apply immediately and SubMiner shows a notification listing any changed sections that need a restart. If the new file is invalid, the previous config stays active.
 
-When these values change, SubMiner applies them live. Invalid config edits are rejected and the previous valid runtime config remains active.
+These apply live:
 
-Restart-required changes:
+- `subtitleStyle`, `subtitleSidebar`, `subtitleSelection`, `keybindings`, `shortcuts`
+- `logging.level`, `logging.rotation`, `logging.files`
+- `secondarySub.defaultMode`, `youtube.primarySubLanguages`
+- `mpv.aniskipEnabled`, `mpv.aniskipButtonKey`, `stats.toggleKey`, `stats.markWatchedKey`
+- `ankiConnect.deck`, `ankiConnect.fields.*`, `ankiConnect.behavior.autoUpdateNewCards`
+- `ankiConnect.media.normalizeAudio`, `media.mirrorMpvVolume`, `media.reviewTiming`
+- `ankiConnect.knownWords` (`highlightEnabled`, `refreshMinutes`, `addMinedWordsImmediately`, `matchMode`, `decks`) and `ankiConnect.nPlusOne.*`
+- `ankiConnect.isLapis.sentenceCardModel`, `isKiku.fieldGrouping`, `isSenren.fieldGrouping`, `lapisKiku.wordCardKind`
 
-- Any other config sections still require restart.
-- Shared top-level `ai` provider settings still require restart.
-- AnkiConnect transport/proxy/media/tag fields still require restart unless listed above.
-- SubMiner shows an on-screen/system notification listing restart-required sections when they change.
+These are read at the start of the next operation, so changes take effect on the next request or run: `jimaku`, `tmdb`, `subsync`, `subtitleGeneration`, `notifications`.
 
-### Configuration Options Overview
+Everything else needs a restart.
 
-The configuration file includes several main sections:
-
-**Core Settings**
-
-- [**Logging**](#logging) - Runtime log level
-- [**Auto-Start Overlay**](#auto-start-overlay) - Automatically show overlay on MPV connection
-- [**Startup Warmups**](#startup-warmups) - Control what preloads on startup vs first-use defer
-- [**WebSocket Server**](#websocket-server) - Built-in subtitle broadcasting server
-- [**Annotation WebSocket**](#annotation-websocket) - Dedicated annotated subtitle payload stream
-- [**Texthooker**](#texthooker) - Control browser opening behavior
-
-**Subtitle Display**
-
-- [**Subtitle Style**](#subtitle-style) - Appearance customization
-- [**Subtitle Sidebar**](#subtitle-sidebar) - Parsed cue list sidebar modal
-- [**Subtitle Position**](#subtitle-position) - Overlay vertical positioning
-- [**Secondary Subtitles**](#secondary-subtitles) - Dual subtitle track support
-
-**Keyboard & Controls**
-
-- [**Keybindings**](#keybindings) - MPV command shortcuts
-- [**Shortcuts Configuration**](#shortcuts-configuration) - Overlay keyboard shortcuts
-- [**Controller Support**](#controller-support) - Gamepad support for keyboard-only mode
-- [**Manual Card Update Shortcuts**](#manual-card-update-shortcuts) - Shortcuts for manual Anki card workflows
-- [**Session Help Modal**](#session-help-modal) - In-overlay shortcut reference
-- [**Runtime Option Palette**](#runtime-option-palette) - Live, session-only option toggles
-
-**Anki Integration**
-
-- [**Shared AI Provider**](#shared-ai-provider) - Canonical OpenAI-compatible provider config shared by Anki and YouTube subtitle fixing
-- [**AnkiConnect**](#ankiconnect) - Automatic Anki card creation with media
-- [**Kiku/Lapis Integration**](#kiku-lapis-integration) - Sentence cards and duplicate handling for Kiku/Lapis note types
-- [**N+1 Word Highlighting**](#n-1-word-highlighting) - Known-word cache and single-target highlighting
-- [**Field Grouping Modes**](#field-grouping-modes) - Kiku/Lapis duplicate card merging
-
-**External Integrations**
-
-- [**Jimaku**](#jimaku) - Jimaku API configuration and defaults
-- [**TsukiHime**](#tsukihime) - Multi-language subtitle search and download
-- [**Subtitle Sync**](#subtitle-sync) - Sync current subtitle with `alass`/`ffsubsync`
-- [**AniList**](#anilist) - Optional post-watch progress updates
-- [**Yomitan**](#yomitan) - Reuse an external read-only Yomitan profile
-- [**Jellyfin**](#jellyfin) - Optional Jellyfin auth, library listing, and playback launch
-- [**Discord Rich Presence**](#discord-rich-presence) - Optional Discord activity card updates
-- [**Immersion Tracking**](#immersion-tracking) - Track subtitle sessions and mining activity in SQLite
-- [**Stats Dashboard**](#stats-dashboard) - Local dashboard and overlay for immersion progress
-- [**MPV Launcher**](#mpv-launcher) - mpv executable path, profile, and window launch mode
-- [**YouTube Playback Settings**](#youtube-playback-settings) - Defaults for YouTube subtitle loading
-- [**Updates**](#updates) - Automatic update checks, notifications, and prerelease testing
-- [**Notifications**](#notifications) - Overlay notification placement
-
-## Core Settings
+## Core settings
 
 ### Logging
 
-Control the minimum log level for runtime output:
+Log files are named by date (`app-YYYY-MM-DD.log`, `launcher-...`, `mpv-...`). Log export writes a sanitized copy and leaves the originals alone.
 
-```json
-{
-  "logging": {
-    "level": "warn",
-    "rotation": 7,
-    "files": {
-      "app": true,
-      "launcher": true,
-      "mpv": false
-    }
-  }
-}
-```
-
-| Option           | Values                                   | Description                                                          |
-| ---------------- | ---------------------------------------- | -------------------------------------------------------------------- |
-| `level`          | `"debug"`, `"info"`, `"warn"`, `"error"` | Minimum log level for runtime logging (default: `"warn"`)            |
-| `rotation`       | positive integer                         | Number of days of app, launcher, and mpv logs to retain (default: 7) |
-| `files.app`      | boolean                                  | Write SubMiner app runtime logs (default: `true`)                    |
-| `files.launcher` | boolean                                  | Write launcher command logs (default: `true`)                        |
-| `files.mpv`      | boolean                                  | Write mpv player logs. Enable temporarily for mpv/plugin debugging.  |
-
-Log filenames use the local calendar date, for example `app-YYYY-MM-DD.log`, `launcher-YYYY-MM-DD.log`, and `mpv-YYYY-MM-DD.log`.
-Log export creates a sanitized copy of those files; it does not rewrite the original log files on disk.
+| Key                      | Default  | What it does                                            |
+| ------------------------ | -------- | ------------------------------------------------------- |
+| `logging.level`          | `"warn"` | Minimum level: `debug`, `info`, `warn`, `error`         |
+| `logging.rotation`       | `7`      | Days of logs to keep                                    |
+| `logging.files.app`      | `true`   | Write app logs                                          |
+| `logging.files.launcher` | `true`   | Write launcher logs                                     |
+| `logging.files.mpv`      | `false`  | Write mpv logs. Turn on temporarily to debug mpv/plugin |
 
 ### Updates
 
-Configure automatic update checks and update notifications:
+Manual checks from the tray or `subminer -u` always work, even with automatic checks off. Overlay update notifications include an **Update** button.
 
-```json
-{
-  "updates": {
-    "enabled": true,
-    "checkIntervalHours": 24,
-    "notificationType": "overlay",
-    "channel": "stable"
-  }
-}
-```
-
-| Option               | Values                                            | Description                                                                                         |
-| -------------------- | ------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
-| `updates.enabled`    | `true`, `false`                                   | Enable automatic background update checks. Manual tray and `subminer -u` checks are always allowed. |
-| `checkIntervalHours` | number                                            | Minimum hours between automatic update checks. Default `24`.                                        |
-| `notificationType`   | `"overlay"` \| `"system"` \| `"both"` \| `"none"` | How SubMiner announces available updates. Default `"overlay"`. `"both"` means overlay + system.     |
-| `channel`            | `"stable"` \| `"prerelease"`                      | Release channel used for update checks. Use `"prerelease"` to test beta/RC releases.                |
-
-When `notificationType` is `"overlay"` or `"both"`, update-available overlay notifications include an **Update** button that starts the app update flow.
-
-`osd` and `osd-system` are legacy config-file-only notification values. The Settings window offers `overlay`, `system`, `both`, and `none`; if your config already contains `osd` or `osd-system`, it is shown as the selected value but not offered as a normal choice. If you previously used `both` for mpv OSD + system notifications, set `notificationType` to `"osd-system"` in `config.jsonc` to keep that behavior.
+| Key                          | Default     | What it does                                              |
+| ---------------------------- | ----------- | --------------------------------------------------------- |
+| `updates.enabled`            | `true`      | Check for updates in the background                       |
+| `updates.checkIntervalHours` | `24`        | Minimum hours between automatic checks                    |
+| `updates.notificationType`   | `"overlay"` | `overlay`, `system`, `both` (overlay + system), or `none` |
+| `updates.channel`            | `"stable"`  | `stable` or `prerelease` (betas and release candidates)   |
 
 ### Notifications
 
-Configure where overlay notification cards appear:
+Overlay notifications are also kept in a session-only history panel. Toggle it with `shortcuts.toggleNotificationHistory`. The panel opens from the same side as the notification cards.
 
-```json
-{
-  "notifications": {
-    "overlayPosition": "top-right"
-  }
-}
-```
+| Key                             | Default       | What it does                                               |
+| ------------------------------- | ------------- | ---------------------------------------------------------- |
+| `notifications.overlayPosition` | `"top-right"` | Where overlay cards appear: `top-left`, `top`, `top-right` |
 
-| Option            | Values                                   | Description                                                        |
-| ----------------- | ---------------------------------------- | ------------------------------------------------------------------ |
-| `overlayPosition` | `"top-left"` \| `"top"` \| `"top-right"` | Position for in-overlay notification cards. Default `"top-right"`. |
+Mining and startup status notifications use `ankiConnect.behavior.notificationType` (see [AnkiConnect](#ankiconnect)).
 
-#### Notification history panel
+### Auto-start overlay
 
-Every overlay notification shown during a session is also recorded in a notification history panel. Press `Ctrl/Cmd+N` (configurable via [`shortcuts.toggleNotificationHistory`](#shortcuts-configuration)) to toggle the panel; the binding works whether the overlay or mpv has focus. The panel slides in from the same edge the notifications use — left when `overlayPosition` is `"top-left"`, and right for `"top-right"` or `"top"` (centered). Character dictionary sync uses one live card but records each distinct phase in history. Each entry can be removed individually, or use **Clear** to empty the history. History is session-only and is not persisted across restarts.
+When mpv is started by SubMiner or the `subminer` launcher, the launcher passes these settings to the bundled mpv plugin. There is no separate plugin config file. `mpv.autoStartSubMiner` and `mpv.pauseUntilOverlayReady` (see [MPV launcher](#mpv-launcher)) control the background start and the initial pause.
 
-Startup tokenization, subtitle annotation, and character dictionary status follow the configured notification surface. When the surface is `"overlay"` or `"both"`, SubMiner queues those startup notifications until the overlay renderer is ready instead of falling back to mpv OSD. If loading and ready states both finish before the overlay can paint, the loading card is delivered first and then updates to ready shortly after. With `"both"`, character dictionary checking/building/importing/ready status also goes to system notifications; building and importing are only emitted when that work is actually needed. The bundled mpv plugin only shows its startup OSD messages when `ankiConnect.behavior.notificationType` is set to `"osd"` or `"osd-system"` in `config.jsonc`; AniSkip prompts and skip result messages are playback feedback and still route to overlay notifications when configured.
+| Key                  | Default | What it does                                                 |
+| -------------------- | ------- | ------------------------------------------------------------ |
+| `auto_start_overlay` | `true`  | Show the visible overlay when the mpv plugin starts SubMiner |
 
-The equivalent direct CLI command is `--playback-feedback <text>` (`playbackFeedback` internally). It sends that one non-empty feedback string through the same route controlled by `ankiConnect.behavior.notificationType`; it does not change the saved config.
+### Startup warmups
 
-### Auto-Start Overlay
+Warmups load components in the background at startup. Turn one off to load it on first use instead.
 
-Control whether the overlay automatically becomes visible when it connects to mpv:
+| Key                                    | Default | What it does                                                                  |
+| -------------------------------------- | ------- | ----------------------------------------------------------------------------- |
+| `startupWarmups.lowPowerMode`          | `false` | Defer every warmup except the Yomitan extension                               |
+| `startupWarmups.mecab`                 | `true`  | Load the MeCab tokenizer                                                      |
+| `startupWarmups.yomitanExtension`      | `true`  | Load the Yomitan extension                                                    |
+| `startupWarmups.subtitleDictionaries`  | `true`  | Load the JLPT and frequency dictionaries                                      |
+| `startupWarmups.jellyfinRemoteSession` | `false` | Connect the Jellyfin remote session (also needs Jellyfin remote auto-connect) |
 
-```json
-{
-  "auto_start_overlay": true
-}
-```
+### WebSocket server
 
-| Option               | Values          | Description                                           |
-| -------------------- | --------------- | ----------------------------------------------------- |
-| `auto_start_overlay` | `true`, `false` | Auto-show overlay on mpv connection (default: `true`) |
+Broadcasts plain subtitle text to external clients. See [WebSocket / Texthooker API](/websocket-texthooker-api) for payloads and client examples.
 
-When you launch through the SubMiner app or the `subminer` wrapper, the launcher reads these settings from this config and injects them into the mpv plugin at runtime - there is no separate plugin config file to edit. `auto_start_overlay` controls whether the visible overlay shows on auto-start. Two related keys in the `mpv` block tune startup behavior: `mpv.autoStartSubMiner` starts the overlay automatically when a file loads, and `mpv.pauseUntilOverlayReady` pauses mpv on visible auto-start until SubMiner signals overlay/tokenization readiness. On visible-overlay startup, SubMiner brings up the tray and visible overlay shell before tokenization and annotation warmups finish, then releases playback only after autoplay readiness.
-
-On Windows, packaged plugin installs also rewrite the plugin socket path to `\\.\pipe\subminer-socket`.
-
-### Startup Warmups
-
-Control which startup warmups run in the background versus deferring to first real usage:
-
-```json
-{
-  "startupWarmups": {
-    "lowPowerMode": false,
-    "mecab": true,
-    "yomitanExtension": true,
-    "subtitleDictionaries": true,
-    "jellyfinRemoteSession": false
-  }
-}
-```
-
-| Option                  | Values          | Description                                                                                       |
-| ----------------------- | --------------- | ------------------------------------------------------------------------------------------------- |
-| `lowPowerMode`          | `true`, `false` | Defer all warmups except Yomitan extension                                                        |
-| `mecab`                 | `true`, `false` | Warm up MeCab tokenizer at startup                                                                |
-| `yomitanExtension`      | `true`, `false` | Warm up Yomitan extension at startup                                                              |
-| `subtitleDictionaries`  | `true`, `false` | Warm up JLPT + frequency dictionaries at startup                                                  |
-| `jellyfinRemoteSession` | `true`, `false` | Warm up Jellyfin remote session at startup (still requires Jellyfin remote auto-connect settings) |
-
-Defaults warm local tokenizer/dictionary work (`true` for `mecab`, `yomitanExtension`, and `subtitleDictionaries`) with `lowPowerMode: false`; Jellyfin remote session warmup is opt-in (`false` by default). Setting a warmup toggle to `false` defers that work until first usage.
-
-### WebSocket Server
-
-The overlay includes a built-in WebSocket server that broadcasts plain subtitle text to connected clients for external processing.
-
-For endpoint details, payload examples, and client patterns, see [WebSocket / Texthooker API & Integration](/websocket-texthooker-api).
-
-By default, the server is disabled. Set `enabled` to `true` to force it on, or `"auto"` to start it unless [mpv_websocket](https://github.com/kuroahna/mpv_websocket) is detected at `~/.config/mpv/mpv_websocket`.
-
-See `config.example.jsonc` for detailed configuration options.
-
-```json
-{
-  "websocket": {
-    "enabled": false,
-    "port": 6677
-  }
-}
-```
-
-| Option              | Values                    | Description                                         |
-| ------------------- | ------------------------- | --------------------------------------------------- |
-| `websocket.enabled` | `true`, `false`, `"auto"` | Built-in subtitle websocket mode (default: `false`) |
-| `websocket.port`    | number                    | WebSocket server port (default: 6677)               |
+| Key                 | Default | What it does                                                                                                                   |
+| ------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `websocket.enabled` | `false` | `true`, `false`, or `"auto"` (start unless the [mpv_websocket](https://github.com/kuroahna/mpv_websocket) plugin is installed) |
+| `websocket.port`    | `6677`  | Server port                                                                                                                    |
 
 ### Annotation WebSocket
 
-SubMiner also exposes a dedicated annotated websocket stream for the bundled texthooker UI and token-aware clients.
+A separate stream that adds token data (known word, N+1, frequency, JLPT, character names) to each subtitle. The bundled texthooker uses it.
 
-This stream includes subtitle text plus token metadata (N+1, known-word, frequency, JLPT, and character-name annotation context).
-
-```json
-{
-  "annotationWebsocket": {
-    "enabled": false,
-    "port": 6678
-  }
-}
-```
-
-| Option                        | Values          | Description                                                    |
-| ----------------------------- | --------------- | -------------------------------------------------------------- |
-| `annotationWebsocket.enabled` | `true`, `false` | Toggle annotated websocket stream (independent of `websocket`) |
-| `annotationWebsocket.port`    | number          | Annotation websocket port (default: 6678)                      |
+| Key                           | Default | What it does                                            |
+| ----------------------------- | ------- | ------------------------------------------------------- |
+| `annotationWebsocket.enabled` | `false` | Start the annotated stream (independent of `websocket`) |
+| `annotationWebsocket.port`    | `6678`  | Server port                                             |
 
 ### Texthooker
 
-Control whether texthooker starts automatically and whether it opens a browser:
+| Key                          | Default | What it does                                            |
+| ---------------------------- | ------- | ------------------------------------------------------- |
+| `texthooker.launchAtStartup` | `false` | Start the texthooker server when SubMiner starts        |
+| `texthooker.openBrowser`     | `false` | Open the texthooker page in your browser when it starts |
 
-See `config.example.jsonc` for detailed configuration options.
+## Subtitle display
 
-```json
-{
-  "texthooker": {
-    "launchAtStartup": false,
-    "openBrowser": false
-  }
-}
-```
+### Subtitle style
 
-| Option            | Values          | Description                                                             |
-| ----------------- | --------------- | ----------------------------------------------------------------------- |
-| `launchAtStartup` | `true`, `false` | Start texthooker automatically with SubMiner startup (default: `false`) |
-| `openBrowser`     | `true`, `false` | Open browser tab when texthooker starts (default: `false`)              |
+Controls how primary and secondary subtitles look and which annotations they show. `css` and `secondary.css` take CSS declarations with normal property names. See [Subtitle annotations](/subtitle-annotations) for how known-word, N+1, frequency, JLPT, and character-name highlighting work.
 
-## Subtitle Display
-
-### Subtitle Style
-
-Customize the appearance of primary and secondary subtitles:
-
-See `config.example.jsonc` for detailed configuration options.
-
-```json
+```jsonc
 {
   "subtitleStyle": {
-    "css": {
-      "font-family": "Hiragino Sans, M PLUS 1, Source Han Sans JP, Noto Sans CJK JP",
-      "color": "#cad3f5",
-      "background-color": "transparent",
-      "font-size": "35px",
-      "font-weight": "600",
-      "line-height": "1.35",
-      "letter-spacing": "-0.01em",
-      "word-spacing": "0",
-      "font-kerning": "normal",
-      "text-rendering": "geometricPrecision",
-      "text-shadow": "-1px -1px 2px rgba(0,0,0,0.95), 1px -1px 2px rgba(0,0,0,0.95), -1px 1px 2px rgba(0,0,0,0.95), 1px 1px 2px rgba(0,0,0,0.95), 0 0 8px rgba(0,0,0,0.5)",
-      "font-style": "normal",
-      "backdrop-filter": "blur(6px)",
-      "--subtitle-hover-token-color": "#f4dbd6",
-      "--subtitle-hover-token-background-color": "transparent"
-    },
-    "secondary": {
-      "css": {
-        "font-family": "Hiragino Sans, M PLUS 1, Source Han Sans JP, Noto Sans CJK JP",
-        "color": "#cad3f5",
-        "background-color": "transparent",
-        "font-size": "24px",
-        "text-shadow": "-1px -1px 2px rgba(0,0,0,0.95), 1px -1px 2px rgba(0,0,0,0.95), -1px 1px 2px rgba(0,0,0,0.95), 1px 1px 2px rgba(0,0,0,0.95), 0 0 8px rgba(0,0,0,0.5)"
-      }
-    }
-  }
+    "css": { "font-size": "40px", "color": "#ffffff" },
+    "secondary": { "css": { "font-size": "24px" } },
+  },
 }
 ```
 
-| Option                             | Values   | Description                                                                                                                                                               |
-| ---------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `primaryDefaultMode`               | string   | Default primary subtitle bar visibility mode: `"hidden"`, `"visible"`, or `"hover"` (default: `"visible"`)                                                                |
-| `subtitleStyle.css`                | object   | CSS declaration object applied to primary subtitles after normal style defaults. Use CSS property names such as `font-size`.                                              |
-| `secondary.css`                    | object   | CSS declaration object applied to secondary subtitles after normal secondary style defaults.                                                                              |
-| `enableJlpt`                       | boolean  | Enable JLPT level underline styling (`false` by default)                                                                                                                  |
-| `preserveLineBreaks`               | boolean  | Preserve line breaks in visible overlay subtitle rendering (`false` by default). Enable to mirror mpv line layout.                                                        |
-| `autoPauseVideoOnHover`            | boolean  | Pause playback while mouse hovers subtitle text, then resume on leave (`true` by default).                                                                                |
-| `autoPauseVideoOnYomitanPopup`     | boolean  | Pause playback while the Yomitan popup is open, then resume when the popup closes (`true` by default).                                                                    |
-| `primaryVisibleOnYomitanPopup`     | boolean  | Keep hover-mode primary subtitles visible while the Yomitan popup is open (`true` by default).                                                                            |
-| `nameMatchEnabled`                 | boolean  | Enable character dictionary sync and subtitle token coloring for character-name matches (`false` by default)                                                              |
-| `nameMatchImagesEnabled`           | boolean  | Show small cached AniList character portraits beside matched character-name tokens (`false` by default)                                                                   |
-| `nameMatchColor`                   | string   | Hex color used for subtitle tokens matched from the SubMiner character dictionary (default: `#f5bde6`)                                                                    |
-| `knownWordColor`                   | string   | Hex color used for known-word subtitle highlights (default: `#a6da95`)                                                                                                    |
-| `knownWordMaturityColors`          | object   | Per-tier known-word colors used when `ankiConnect.knownWords.maturityEnabled` is on: `new` (`#ee99a0`), `learning` (`#b7bdf8`), `young` (`#91d7e3`), `mature` (`#a6da95`) |
-| `nPlusOneColor`                    | string   | Hex color used for the single N+1 target subtitle highlight (default: `#c6a0f6`)                                                                                          |
-| `frequencyDictionary.enabled`      | boolean  | Enable frequency highlighting from dictionary lookups (`false` by default)                                                                                                |
-| `frequencyDictionary.sourcePath`   | string   | Path to a local frequency dictionary root. Leave empty or omit to use installed/default frequency-dictionary search paths.                                                |
-| `frequencyDictionary.topX`         | number   | Only color tokens whose frequency rank is `<= topX` (`10000` by default)                                                                                                  |
-| `frequencyDictionary.mode`         | string   | `"single"` or `"banded"` (`"single"` by default)                                                                                                                          |
-| `frequencyDictionary.matchMode`    | string   | `"headword"` or `"surface"` (`"headword"` by default)                                                                                                                     |
-| `frequencyDictionary.singleColor`  | string   | Color used for all highlighted tokens in single mode                                                                                                                      |
-| `frequencyDictionary.bandedColors` | string[] | Array of five hex colors used for ranked bands in banded mode                                                                                                             |
-| `jlptColors`                       | object   | JLPT level underline colors object (`N1`..`N5`)                                                                                                                           |
+| Key                                              | Default      | What it does                                                                                          |
+| ------------------------------------------------ | ------------ | ----------------------------------------------------------------------------------------------------- |
+| `subtitleStyle.primaryDefaultMode`               | `"visible"`  | Primary bar at startup: `hidden`, `visible`, or `hover`                                               |
+| `subtitleStyle.css`                              | see example  | CSS for primary subtitles (font, size `35px`, color, shadow, and so on)                               |
+| `subtitleStyle.secondary.css`                    | see example  | CSS for secondary subtitles (size `24px`)                                                             |
+| `subtitleStyle.preserveLineBreaks`               | `false`      | Keep line breaks as mpv shows them instead of one line                                                |
+| `subtitleStyle.autoPauseVideoOnHover`            | `true`       | Pause while the mouse is over subtitle text                                                           |
+| `subtitleStyle.autoPauseVideoOnYomitanPopup`     | `true`       | Pause while a Yomitan popup is open                                                                   |
+| `subtitleStyle.primaryVisibleOnYomitanPopup`     | `true`       | In hover mode, keep the primary bar visible while a popup is open                                     |
+| `subtitleStyle.knownWordColor`                   | `#a6da95`    | Known-word highlight color                                                                            |
+| `subtitleStyle.knownWordMaturityColors`          | see example  | `new`, `learning`, `young`, `mature` colors, used when `ankiConnect.knownWords.maturityEnabled` is on |
+| `subtitleStyle.nPlusOneColor`                    | `#c6a0f6`    | N+1 target word color                                                                                 |
+| `subtitleStyle.enableJlpt`                       | `false`      | Underline words by JLPT level                                                                         |
+| `subtitleStyle.jlptColors`                       | see example  | Underline colors for `N1` to `N5`                                                                     |
+| `subtitleStyle.nameMatchEnabled`                 | `false`      | Sync the character dictionary and color character names                                               |
+| `subtitleStyle.nameMatchImagesEnabled`           | `false`      | Show small character portraits next to matched names                                                  |
+| `subtitleStyle.nameMatchColor`                   | `#f5bde6`    | Character-name color                                                                                  |
+| `subtitleStyle.frequencyDictionary.enabled`      | `false`      | Color words by frequency rank                                                                         |
+| `subtitleStyle.frequencyDictionary.sourcePath`   | `""`         | Folder with `term_meta_bank_*.json` files. Empty searches the default locations                       |
+| `subtitleStyle.frequencyDictionary.topX`         | `10000`      | Only color words ranked at or below this                                                              |
+| `subtitleStyle.frequencyDictionary.mode`         | `"single"`   | `single` (one color) or `banded` (five colors, common to rare)                                        |
+| `subtitleStyle.frequencyDictionary.matchMode`    | `"headword"` | Look up by `headword` (dictionary form) or `surface` (text as shown)                                  |
+| `subtitleStyle.frequencyDictionary.singleColor`  | `#f5a97f`    | Color for `single` mode                                                                               |
+| `subtitleStyle.frequencyDictionary.bandedColors` | see example  | Five colors for `banded` mode                                                                         |
 
-Subtitle CSS custom properties:
+Two CSS custom properties style the hovered word: `--subtitle-hover-token-color` (`#f4dbd6`) and `--subtitle-hover-token-background-color` (`transparent`). Set them inside `subtitleStyle.css`.
 
-| CSS Property                              | Default       | Description                             |
-| ----------------------------------------- | ------------- | --------------------------------------- |
-| `--subtitle-hover-token-color`            | `#f4dbd6`     | Hovered subtitle token text color       |
-| `--subtitle-hover-token-background-color` | `transparent` | Hovered subtitle token background color |
+### Subtitle sidebar
 
-The Settings window keeps subtitle color controls separate, then saves CSS textboxes to
-the primary subtitle, secondary subtitle, and sidebar CSS objects. The generated example
-uses that same CSS declaration shape.
+A scrollable cue list for the current subtitle file. It only works when SubMiner could parse the active subtitle into cues. See [Subtitle sidebar](/subtitle-sidebar).
 
-Frequency dictionary highlighting uses the same dictionary file format as JLPT bundle lookups (`term_meta_bank_*.json` under discovered dictionary directories). A token is highlighted when it has a positive integer `frequencyRank` (lower is more common) and the rank is within `topX`.
+| Key                                 | Default       | What it does                                                                   |
+| ----------------------------------- | ------------- | ------------------------------------------------------------------------------ |
+| `subtitleSidebar.enabled`           | `true`        | Enable the sidebar                                                             |
+| `subtitleSidebar.autoOpen`          | `false`       | Open it once when the overlay starts                                           |
+| `subtitleSidebar.layout`            | `"overlay"`   | `overlay` floats over mpv. `embedded` reserves space on the right of the video |
+| `subtitleSidebar.toggleKey`         | `"Backslash"` | `KeyboardEvent.code` that opens and closes it                                  |
+| `subtitleSidebar.pauseVideoOnHover` | `true`        | Pause while hovering the cue list                                              |
+| `subtitleSidebar.autoScroll`        | `true`        | Keep the active cue in view                                                    |
+| `subtitleSidebar.css`               | see example   | CSS for the sidebar, plus the custom properties below                          |
 
-Lookup behavior:
+Sidebar custom properties: `--subtitle-sidebar-max-width` (`420px`), `--subtitle-sidebar-timestamp-color`, `--subtitle-sidebar-active-line-color`, `--subtitle-sidebar-active-background-color`, `--subtitle-sidebar-hover-background-color`. Their defaults are in the example config.
 
-- Point the source path at a directory containing `term_meta_bank_*.json` for a fully custom source.
-- If `sourcePath` is missing or empty, SubMiner searches default install/runtime locations for `frequency-dictionary` directories (for example app resources, user data paths, and current working directory).
-- In both cases, only terms with a valid `frequencyRank` are used; everything else falls back to no highlighting.
-- Match mode controls which token text is used for frequency lookups: `headword` (dictionary form) or `surface` (visible subtitle text).
-- Frequency highlighting skips tokens that look like non-lexical SFX/interjection noise (for example kana reduplication or short kana endings like `っ`), even when dictionary ranks exist.
+If `embedded` layout places the video oddly on your system, switch back to `overlay`.
 
-In `single` mode all highlights use `singleColor`; in `banded` mode tokens map to five ascending color bands from most common to least common inside the topX window.
+### Subtitle position
 
-Character-name highlighting is separate from N+1 and frequency highlighting:
+You can also drag subtitles with `Right-click + drag` while watching.
 
-- `nameMatchEnabled` controls whether SubMiner syncs the character dictionary and includes character-dictionary name matches in subtitle token metadata and renderer styling.
-- `nameMatchImagesEnabled` adds small circular portraits beside matched names using the AniList images already cached with character dictionary snapshots.
-- `nameMatchColor` sets the highlight color for those matched character names.
-- Matches come from the bundled SubMiner character dictionary, including AniList-synced merged dictionaries when name matching is enabled.
+| Key                         | Default | What it does                                                     |
+| --------------------------- | ------- | ---------------------------------------------------------------- |
+| `subtitlePosition.yPercent` | `10`    | Starting distance from the bottom, as a percent of screen height |
 
-Secondary subtitle styling lives in the secondary subtitle CSS object. Any CSS property not set there falls back to the secondary subtitle defaults, then the normal renderer defaults.
+### Secondary subtitles
 
-**See `config.example.jsonc`** for the complete list of subtitle style configuration options.
+Shows a second track, such as English, above the Japanese line.
 
-### Subtitle Sidebar
-
-Configure the parsed-subtitle sidebar modal.
-
-```json
-{
-  "subtitleSidebar": {
-    "enabled": true,
-    "autoOpen": false,
-    "layout": "overlay",
-    "toggleKey": "Backslash",
-    "pauseVideoOnHover": true,
-    "autoScroll": true,
-    "css": {
-      "font-family": "Hiragino Sans, M PLUS 1, Source Han Sans JP, Noto Sans CJK JP",
-      "font-size": "16px",
-      "color": "#cad3f5",
-      "background-color": "rgba(73, 77, 100, 0.9)",
-      "--subtitle-sidebar-max-width": "420px"
-    }
-  }
-}
-```
-
-| Option                      | Values  | Description                                                                                             |
-| --------------------------- | ------- | ------------------------------------------------------------------------------------------------------- |
-| `subtitleSidebar.enabled`   | boolean | Enable subtitle sidebar support (`true` by default)                                                     |
-| `autoOpen`                  | boolean | Open sidebar automatically on overlay startup (`false` by default)                                      |
-| `layout`                    | string  | `"overlay"` floats over mpv; `"embedded"` reserves right-side player space to mimic browser-like layout |
-| `subtitleSidebar.toggleKey` | string  | `KeyboardEvent.code` used to open/close the sidebar (default: `"Backslash"`)                            |
-| `pauseVideoOnHover`         | boolean | Pause playback while hovering the sidebar cue list (`true` by default)                                  |
-| `autoScroll`                | boolean | Keep the active cue in view while playback advances                                                     |
-| `subtitleSidebar.css`       | object  | CSS declaration object applied to the sidebar. Use CSS properties plus sidebar custom properties below. |
-
-Direct style keys are also available under `subtitleSidebar` and map to the same visuals as the CSS custom properties: `maxWidth` (default `420`), `opacity` (`0.95`), `backgroundColor`, `textColor`, `fontFamily`, `fontSize` (`16`), `timestampColor`, `activeLineColor`, `activeLineBackgroundColor`, and `hoverLineBackgroundColor`.
-
-Sidebar CSS custom properties:
-
-| CSS Property                                 | Default                     | Description                  |
-| -------------------------------------------- | --------------------------- | ---------------------------- |
-| `--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 |
-
-The sidebar is only available when the active subtitle source has been parsed into a cue list. Default colors use Catppuccin Macchiato with a semi-transparent shell so the panel stays readable without feeling like an opaque settings dialog.
-
-`embedded` layout is intended to act like a split-pane view: it reserves player space with a right-side video margin and keeps interaction in both the player area and sidebar. If you see unexpected offset behavior in your environment, switch back to `overlay` to isolate sidebar placement.
-
-For full details on layout modes, behavior, and the keyboard shortcut, see the [Subtitle Sidebar](/subtitle-sidebar) page.
-
-`subtitleStyle.jlptColors` keys are:
-
-| Key  | Default   | Description             |
-| ---- | --------- | ----------------------- |
-| `N1` | `#ed8796` | JLPT N1 underline color |
-| `N2` | `#f5a97f` | JLPT N2 underline color |
-| `N3` | `#f9e2af` | JLPT N3 underline color |
-| `N4` | `#8bd5ca` | JLPT N4 underline color |
-| `N5` | `#8aadf4` | JLPT N5 underline color |
-
-### Subtitle Position
-
-Set the initial vertical subtitle position (measured from the bottom of the screen):
-
-```json
-{
-  "subtitlePosition": {
-    "yPercent": 10
-  }
-}
-```
-
-| Option     | Values           | Description                                                            |
-| ---------- | ---------------- | ---------------------------------------------------------------------- |
-| `yPercent` | number (0 - 100) | Distance from the bottom as a percent of screen height (default: `10`) |
-
-In the overlay, you can fine-tune subtitle position at runtime with `Right-click + drag` on subtitle text.
-
-### Secondary Subtitles
-
-Display a second subtitle track (e.g., English alongside Japanese) in the overlay:
-
-See `config.example.jsonc` for detailed configuration options.
-
-Secondary subtitles do **not** auto-load by default. To turn them on for local and Jellyfin playback, set `autoLoadSecondarySub` to `true` and list the language codes you want:
+Secondary subtitles do **not** auto-load by default (`autoLoadSecondarySub`, default: `false`). To load them for local and Jellyfin playback, turn it on and list the languages you want:
 
 ```json
 {
   "secondarySub": {
     "secondarySubLanguages": ["eng", "en"],
-    "autoLoadSecondarySub": true,
-    "defaultMode": "hover"
+    "autoLoadSecondarySub": true
   }
 }
 ```
 
-| Option                  | Values                             | Description                                                                                                                                   |
-| ----------------------- | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
-| `secondarySubLanguages` | string[]                           | Language codes to auto-load (e.g., `["eng", "en"]`); non-Signs/Songs tracks are preferred when several tracks match. Default is empty (`[]`). |
-| `autoLoadSecondarySub`  | `true`, `false`                    | Auto-detect and load a matching secondary subtitle track for local/Jellyfin sidecar files (default: `false`)                                  |
-| `defaultMode`           | `"hidden"`, `"visible"`, `"hover"` | Initial display mode (default: `"hover"`)                                                                                                     |
+| Key                                  | Default   | What it does                                                                            |
+| ------------------------------------ | --------- | --------------------------------------------------------------------------------------- |
+| `secondarySub.secondarySubLanguages` | `[]`      | Language codes in priority order. Regular tracks win over Signs/Songs tracks            |
+| `secondarySub.autoLoadSecondarySub`  | `false`   | Load a matching secondary track when the primary loads                                  |
+| `secondarySub.defaultMode`           | `"hover"` | `hidden`, `visible` (always shown), or `hover` (shown when you hover the subtitle area) |
 
-These two settings apply to local and Jellyfin playback only. YouTube secondary selection is fixed to English and ignores them; see [YouTube Integration](/youtube-integration#secondary-subtitle-languages). `defaultMode` still controls how the loaded secondary bar is displayed in every case.
+YouTube ignores the first two keys and always picks English. See [YouTube integration](/youtube-integration). `defaultMode` applies everywhere.
 
-Because the mined-card translation field is filled from the secondary subtitle when one is present, leaving `autoLoadSecondarySub` off means local-file cards fall back to AI translation (when configured) or the original sentence text.
+### Subtitle selection {#subtitle-selection}
 
-The secondary-subtitle language list also acts as the fallback secondary-language priority for managed startup subtitle selection on local playback and YouTube playback.
+Adds a modal for choosing mpv's primary and secondary subtitle tracks. Open it with `g` then `s` (`shortcuts.openSubtitleSelection`). While enabled, that shortcut replaces mpv's own binding for the same key. See [Keyboard shortcuts](/shortcuts) for sequence conflicts.
 
-**Display modes:**
+| Key                         | Default | What it does                        |
+| --------------------------- | ------- | ----------------------------------- |
+| `subtitleSelection.enabled` | `false` | Enable the subtitle selection modal |
 
-- **hidden** - Secondary subtitles not shown
-- **visible** - Always visible at top of overlay
-- **hover** - Only visible when hovering over the subtitle area (default)
-
-**See `config.example.jsonc`** for additional secondary subtitle configuration options.
-
-## Keyboard & Controls
+## Keyboard and controls
 
 ### Keybindings
 
-Add a `keybindings` array to configure keyboard shortcuts that send mpv commands or SubMiner session actions:
-
-See `config.example.jsonc` for detailed configuration options and more examples.
-
-**Default keybindings:**
-
-| Key                     | Command                       | Description                             |
-| ----------------------- | ----------------------------- | --------------------------------------- |
-| `Space`                 | `["cycle", "pause"]`          | Toggle pause                            |
-| `KeyF`                  | `["cycle", "fullscreen"]`     | Toggle fullscreen                       |
-| `KeyJ`                  | `["cycle", "sid"]`            | Cycle primary subtitle track            |
-| `Shift+KeyJ`            | `["cycle", "secondary-sid"]`  | Cycle secondary subtitle track          |
-| `Ctrl+Alt+KeyP`         | `["__playlist-browser-open"]` | Open playlist browser                   |
-| `Ctrl+Alt+KeyC`         | `["__youtube-picker-open"]`   | Open the manual YouTube subtitle picker |
-| `ArrowRight`            | `["seek", 5]`                 | Seek forward 5 seconds                  |
-| `ArrowLeft`             | `["seek", -5]`                | Seek backward 5 seconds                 |
-| `ArrowUp`               | `["seek", 60]`                | Seek forward 60 seconds                 |
-| `ArrowDown`             | `["seek", -60]`               | Seek backward 60 seconds                |
-| `Shift+KeyH`            | `["sub-seek", -1]`            | Jump to previous subtitle               |
-| `Shift+KeyL`            | `["sub-seek", 1]`             | Jump to next subtitle                   |
-| `Ctrl+Shift+ArrowLeft`  | `["sub-step", -1]`            | Shift subtitle delay to previous cue    |
-| `Ctrl+Shift+ArrowRight` | `["sub-step", 1]`             | Shift subtitle delay to next cue        |
-| `KeyZ`                  | `["add", "sub-delay", -0.1]`  | Shift subtitles 100 ms earlier          |
-| `Shift+KeyZ`            | `["add", "sub-delay", 0.1]`   | Delay subtitles by 100 ms               |
-| `KeyX`                  | `["add", "sub-delay", 0.1]`   | Delay subtitles by 100 ms               |
-| `Ctrl+Shift+KeyH`       | `["__replay-subtitle"]`       | Replay current subtitle, pause at end   |
-| `Ctrl+Shift+KeyL`       | `["__play-next-subtitle"]`    | Play next subtitle, pause at end        |
-| `KeyQ`                  | `["quit"]`                    | Quit mpv                                |
-| `Ctrl+KeyW`             | `["quit"]`                    | Quit mpv                                |
-
-**Custom keybindings example:**
+`keybindings` maps keys to mpv commands or SubMiner actions. Your entries merge with the defaults. The full default list is on [Keyboard shortcuts](/shortcuts).
 
 ```json
 {
   "keybindings": [
-    { "key": "ArrowRight", "command": ["seek", 5] },
-    { "key": "ArrowLeft", "command": ["seek", -5] },
     { "key": "Shift+ArrowRight", "command": ["seek", 30] },
     { "key": "MBTN_BACK", "command": ["sub-seek", -1] },
-    { "key": "MBTN_FORWARD", "command": ["sub-seek", 1] },
-    { "key": "KeyR", "command": ["script-binding", "immersive/auto-replay"] },
-    { "key": "KeyA", "command": ["script-message", "ankiconnect-add-note"] }
+    { "key": "Space", "command": null }
   ]
 }
 ```
 
-**Key format:** Use `KeyboardEvent.code` values (`Space`, `ArrowRight`, `KeyR`, etc.) with optional modifiers (`Ctrl+`, `Alt+`, `Shift+`, `Meta+`). Mouse buttons use mpv button names: `MBTN_LEFT`, `MBTN_MID`, `MBTN_RIGHT`, `MBTN_BACK`, and `MBTN_FORWARD`.
+- `key` uses `KeyboardEvent.code` names (`Space`, `KeyR`, `ArrowRight`) with optional `Ctrl+`, `Alt+`, `Shift+`, `Meta+`. Mouse buttons are `MBTN_LEFT`, `MBTN_MID`, `MBTN_RIGHT`, `MBTN_BACK`, `MBTN_FORWARD`.
+- `command` is any mpv JSON IPC command array. Set it to `null` to disable a default.
+- Commands starting with `__` run inside SubMiner: `__playlist-browser-open`, `__youtube-picker-open`, `__replay-subtitle`, `__play-next-subtitle`, `__runtime-options-open`, and `__runtime-option-cycle:<id>[:next|prev]`.
+- Unused single-key bindings from your mpv config also work in the overlay. Your SubMiner bindings win on conflicts.
 
-**Disable a default binding:** Set command to `null`:
+### Shortcuts configuration
 
-```json
-{ "key": "Space", "command": null }
-```
+`shortcuts` holds SubMiner's own actions (mining, copying, opening modals). Values are [Electron accelerator strings](https://www.electronjs.org/docs/latest/tutorial/keyboard-shortcuts) such as `"CommandOrControl+S"`. Set one to `null` to disable it. [Keyboard shortcuts](/shortcuts) lists every key, its default, and what it does. Anki shortcuts only run when `ankiConnect.enabled` is on.
 
-**Special commands:** Commands prefixed with `__` are handled internally by the overlay rather than sent to mpv. `__playlist-browser-open` opens the split-pane playlist browser for the current file's parent directory and the live mpv queue. `__replay-subtitle` replays the current subtitle and pauses at its end. `__play-next-subtitle` seeks to the next subtitle, plays it, and pauses at its end. `__runtime-options-open` opens the runtime options palette. `__runtime-option-cycle:<id>[:next|prev]` cycles a runtime option value.
+| Key                            | Default | What it does                                             |
+| ------------------------------ | ------- | -------------------------------------------------------- |
+| `shortcuts.multiCopyTimeoutMs` | `3000`  | How long multi-copy and multi-mine wait for a digit (ms) |
 
-**Supported commands:** Any valid mpv JSON IPC command array (`["cycle", "pause"]`, `["seek", 5]`, `["script-binding", "..."]`, etc.)
+### Controller support
 
-Subtitle delay commands (`sub-delay`, `sub-step`) show a native mpv OSD notification after the command runs. Subtitle-position and subtitle-track proxy commands (`sub-pos`, `sid`, `secondary-sid`) show playback feedback through the configured notification surface.
+Gamepad input for the overlay, through the browser Gamepad API. It only works while keyboard-only mode is on. Use the `Alt+C` modal to pick a controller and learn bindings, and `Alt+Shift+C` to see raw button and axis values. Default button actions are on [Keyboard shortcuts](/shortcuts).
 
-**See `config.example.jsonc`** for more keybinding examples and configuration options.
+| Key                                | Default  | What it does                                                                          |
+| ---------------------------------- | -------- | ------------------------------------------------------------------------------------- |
+| `controller.enabled`               | `false`  | Enable controller support. The `Alt+C` and `Alt+Shift+C` modals stay closed while off |
+| `controller.smoothScroll`          | `true`   | Smooth popup scrolling                                                                |
+| `controller.scrollPixelsPerSecond` | `900`    | Popup scroll speed                                                                    |
+| `controller.horizontalJumpPixels`  | `160`    | Popup page-jump distance                                                              |
+| `controller.stickDeadzone`         | `0.2`    | Stick deadzone                                                                        |
+| `controller.triggerInputMode`      | `"auto"` | `auto`, `digital`, or `analog`. Use `analog` if your L2/R2 report analog values       |
+| `controller.triggerDeadzone`       | `0.5`    | Trigger threshold for `auto` and `analog`                                             |
+| `controller.repeatDelayMs`         | `320`    | Delay before a held button repeats                                                    |
+| `controller.repeatIntervalMs`      | `120`    | Repeat interval for held buttons                                                      |
 
-### Shortcuts Configuration
+Bindings are set with `Alt+C` learn mode, which saves them per controller.
 
-Customize or disable the overlay keyboard shortcuts:
-
-See `config.example.jsonc` for detailed configuration options.
-
-```json
-{
-  "shortcuts": {
-    "toggleVisibleOverlayGlobal": "Alt+Shift+O",
-    "copySubtitle": "CommandOrControl+C",
-    "copySubtitleMultiple": "CommandOrControl+Shift+C",
-    "updateLastCardFromClipboard": "CommandOrControl+V",
-    "triggerFieldGrouping": "CommandOrControl+G",
-    "triggerSubsync": "Ctrl+Alt+S",
-    "mineSentence": "CommandOrControl+S",
-    "mineSentenceMultiple": "CommandOrControl+Shift+S",
-    "markAudioCard": "CommandOrControl+Shift+A",
-    "openCharacterDictionaryManager": "CommandOrControl+D",
-    "openRuntimeOptions": "CommandOrControl+Shift+O",
-    "openSessionHelp": "CommandOrControl+Slash",
-    "openControllerSelect": "Alt+C",
-    "openControllerDebug": "Alt+Shift+C",
-    "openJimaku": "Ctrl+Shift+J",
-    "toggleSubtitleSidebar": "Backslash",
-    "toggleNotificationHistory": "CommandOrControl+N",
-    "appendClipboardVideoToQueue": "CommandOrControl+A",
-    "multiCopyTimeoutMs": 3000
-  }
-}
-```
-
-| Option                           | Values           | Description                                                                                                                                                                        |
-| -------------------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `toggleVisibleOverlayGlobal`     | string \| `null` | Global accelerator for toggling visible subtitle overlay (default: `"Alt+Shift+O"`)                                                                                                |
-| `copySubtitle`                   | string \| `null` | Accelerator for copying current subtitle (default: `"CommandOrControl+C"`)                                                                                                         |
-| `copySubtitleMultiple`           | string \| `null` | Accelerator for multi-copy mode (default: `"CommandOrControl+Shift+C"`)                                                                                                            |
-| `updateLastCardFromClipboard`    | string \| `null` | Accelerator for updating card from clipboard (default: `"CommandOrControl+V"`)                                                                                                     |
-| `triggerFieldGrouping`           | string \| `null` | Accelerator for Kiku field grouping on last card (default: `"CommandOrControl+G"`; only active when automatic card updates are disabled)                                           |
-| `triggerSubsync`                 | string \| `null` | Accelerator for running Subsync (default: `"Ctrl+Alt+S"`)                                                                                                                          |
-| `mineSentence`                   | string \| `null` | Accelerator for creating sentence card from current subtitle (default: `"CommandOrControl+S"`)                                                                                     |
-| `mineSentenceMultiple`           | string \| `null` | Accelerator for multi-mine sentence card mode (default: `"CommandOrControl+Shift+S"`)                                                                                              |
-| `multiCopyTimeoutMs`             | number           | Timeout in ms for multi-copy/mine digit input (default: `3000`)                                                                                                                    |
-| `toggleSecondarySub`             | string \| `null` | Accelerator for cycling secondary subtitle mode (default: `"CommandOrControl+Shift+V"`)                                                                                            |
-| `markAudioCard`                  | string \| `null` | Accelerator for marking last card as audio card (default: `"CommandOrControl+Shift+A"`)                                                                                            |
-| `openCharacterDictionaryManager` | string \| `null` | Opens the loaded character dictionary manager (default: `"CommandOrControl+D"`)                                                                                                    |
-| `openRuntimeOptions`             | string \| `null` | Opens runtime options palette for live session-only toggles (default: `"CommandOrControl+Shift+O"`)                                                                                |
-| `openSessionHelp`                | string \| `null` | Opens the in-overlay session help modal (default: `"CommandOrControl+Slash"`)                                                                                                      |
-| `openControllerSelect`           | string \| `null` | Opens the controller config/remap modal (default: `"Alt+C"`)                                                                                                                       |
-| `openControllerDebug`            | string \| `null` | Opens the controller debug modal (default: `"Alt+Shift+C"`)                                                                                                                        |
-| `openJimaku`                     | string \| `null` | Opens the Jimaku search modal (default: `"Ctrl+Shift+J"`)                                                                                                                          |
-| `toggleSubtitleSidebar`          | string \| `null` | Dispatches the subtitle sidebar toggle action (default: `"Backslash"`). `subtitleSidebar.toggleKey` remains the primary bare-key setting.                                          |
-| `toggleNotificationHistory`      | string \| `null` | Toggles the overlay notification history panel (default: `"CommandOrControl+N"`). The panel slides in from the same edge as notifications (right when notifications are centered). |
-| `appendClipboardVideoToQueue`    | string \| `null` | Appends a video file path from the clipboard to the mpv playlist (default: `"CommandOrControl+A"`). Works whether the overlay or mpv has focus.                                    |
-
-**See `config.example.jsonc`** for the complete list of shortcut configuration options.
-
-Set any shortcut to `null` to disable it.
-
-Feature-dependent shortcuts/keybindings only run when their related integration is enabled. For example, Anki/Kiku shortcuts require `ankiConnect.enabled` (and Kiku-specific behavior where applicable), and Jellyfin remote startup behavior requires Jellyfin to be enabled.
-
-### Controller Support
-
-SubMiner can read controllers through the Chrome Gamepad API and map them onto the existing keyboard-only overlay workflow.
-
-Important behavior:
-
-- Controller input is only active while keyboard-only mode is enabled.
-- Keyboard-only mode continues to work normally without a controller.
-- By default SubMiner uses the first connected controller.
-- Fresh installs keep controller support disabled until you set `controller.enabled` to `true`.
-- `Alt+C` opens the controller config modal by default, and you can remap that shortcut through `shortcuts.openControllerSelect`.
-- The `Alt+C` config modal and `Alt+Shift+C` debug modal stay closed while controller support is disabled.
-- Click the binding badge, edit pencil, or `Learn`, then press the next fresh button, trigger, or stick direction you want to bind for that overlay action.
-- Click the reset button beside the edit pencil to restore one binding to the built-in default.
-- Learned bindings are saved under `controller.profiles` for the selected controller id. Global `controller.bindings` remains the fallback for controllers without a profile.
-- `Alt+Shift+C` opens the debug modal by default, and you can remap that shortcut through `shortcuts.openControllerDebug`.
-- The debug modal shows raw axes/button values plus a ready-to-copy `buttonIndices` config block.
-- The button-index map is a semantic reference mapping. Changing it does not rewrite the raw numeric descriptor values already stored under controller bindings.
-- Turning keyboard-only mode off clears the keyboard-only token highlight state.
-- Closing the Yomitan popup clears the temporary native text-selection fill, but keeps controller token selection active.
-
-```jsonc
-{
-  "controller": {
-    "enabled": true,
-    "preferredGamepadId": "",
-    "preferredGamepadLabel": "",
-    "smoothScroll": true,
-    "scrollPixelsPerSecond": 900,
-    "horizontalJumpPixels": 160,
-    "stickDeadzone": 0.2,
-    "triggerInputMode": "auto",
-    "triggerDeadzone": 0.5,
-    "repeatDelayMs": 320,
-    "repeatIntervalMs": 120,
-    "buttonIndices": {
-      "select": 6,
-      "buttonSouth": 0,
-      "buttonEast": 1,
-      "buttonWest": 2,
-      "buttonNorth": 3,
-      "leftShoulder": 4,
-      "rightShoulder": 5,
-      "leftStickPress": 9,
-      "rightStickPress": 10,
-      "leftTrigger": 6,
-      "rightTrigger": 7,
-    },
-    "bindings": {
-      "toggleLookup": { "kind": "button", "buttonIndex": 0 },
-      "closeLookup": { "kind": "button", "buttonIndex": 1 },
-      "toggleKeyboardOnlyMode": { "kind": "button", "buttonIndex": 3 },
-      "mineCard": { "kind": "button", "buttonIndex": 2 },
-      "quitMpv": { "kind": "button", "buttonIndex": 6 },
-      "previousAudio": { "kind": "none" },
-      "nextAudio": { "kind": "button", "buttonIndex": 5 },
-      "playCurrentAudio": { "kind": "button", "buttonIndex": 4 },
-      "toggleMpvPause": { "kind": "button", "buttonIndex": 9 },
-      "leftStickHorizontal": { "kind": "axis", "axisIndex": 0, "dpadFallback": "horizontal" },
-      "leftStickVertical": { "kind": "axis", "axisIndex": 1, "dpadFallback": "vertical" },
-      "rightStickHorizontal": { "kind": "axis", "axisIndex": 3, "dpadFallback": "none" },
-      "rightStickVertical": { "kind": "axis", "axisIndex": 4, "dpadFallback": "none" },
-    },
-    "profiles": {
-      "Xbox Wireless Controller": {
-        "label": "Xbox Wireless Controller",
-        "bindings": {
-          "toggleLookup": { "kind": "button", "buttonIndex": 0 },
-          "mineCard": { "kind": "button", "buttonIndex": 2 },
-        },
-      },
-    },
-  },
-}
-```
-
-Default logical mapping:
-
-- Left stick up/down: scroll Yomitan popup
-- Left stick left/right: move subtitle token selection
-- Right stick up/down: page-jump through Yomitan popup
-- Right stick left/right: unused by default
-- `A`: toggle lookup
-- `B`: close lookup
-- `Y`: toggle keyboard-only mode
-- `X`: mine card
-- `Minus` / `Select`: quit mpv
-- `L1`: play current Yomitan audio (falls back to the first available track)
-- `R1`: move to the next available Yomitan audio track
-- `L3`: toggle mpv pause
-- `L2` / `R2`: unbound by default
-
-Discrete bindings may use raw button indices or raw axis directions, and analog bindings use raw axis indices with optional D-pad fallback. The `Alt+C` learn flow writes those descriptors under `controller.profiles["<controller id>"]` for the selected controller. Manual edits are only needed when you want to script or copy exact mappings.
-
-If you bind a discrete action to an axis manually, include `direction`:
-
-```jsonc
-{
-  "controller": {
-    "bindings": {
-      "toggleLookup": { "kind": "axis", "axisIndex": 5, "direction": "positive" },
-    },
-  },
-}
-```
-
-Treat the button-index map as reference-only unless you are copying values from the debug modal. Updating it alone does not rewrite the hardcoded raw numeric values already present in controller bindings or controller profiles. If you need a real remap, prefer the `Alt+C` learn flow so both the source and the descriptor shape stay correct.
-
-If you choose to bind `L2` or `R2` manually, set `triggerInputMode` to `analog` and tune `triggerDeadzone` when your controller reports triggers as analog values instead of digital pressed/not-pressed buttons. `digital` forces pressed/not-pressed handling; `auto` accepts either style and remains the default.
-
-If one controller reports non-standard raw button numbers, override that controller profile's button-index map using values from the `Alt+Shift+C` debug modal. Use the global button-index map only when the mapping should apply to every controller without a profile.
-
-If you update this controller documentation or the generated controller examples, run `bun run docs:test` and `bun run docs:build` before merging.
-
-Tune `scrollPixelsPerSecond`, `horizontalJumpPixels`, deadzones, repeat timing, and profile `buttonIndices` to match your controller. See [config.example.jsonc](/config.example.jsonc) for the full generated comments for every controller field.
-
-### Manual Card Update Shortcuts
-
-When automatic card updates are disabled, new cards are detected but not automatically updated. Use these keyboard shortcuts for manual control:
-
-| Shortcut       | Action                                                                                                        |
-| -------------- | ------------------------------------------------------------------------------------------------------------- |
-| `Ctrl+C`       | Copy the current subtitle line to clipboard (preserves line breaks)                                           |
-| `Ctrl+Shift+C` | Enter multi-copy mode. Press `1-9` to copy that many recent lines, or `Esc` to cancel. Timeout: 3 seconds     |
-| `Ctrl+V`       | Update the last added Anki card using subtitles from clipboard                                                |
-| `Ctrl+G`       | Trigger Kiku duplicate field grouping for the last added card (only when automatic card updates are disabled) |
-| `Ctrl+S`       | Create a sentence card from the current subtitle line                                                         |
-| `Ctrl+Shift+S` | Enter multi-mine mode. Press `1-9` to create a sentence card from that many recent lines, or `Esc` to cancel  |
-| `Ctrl+Shift+V` | Cycle secondary subtitle display mode (hidden → visible → hover)                                              |
-| `Ctrl+Shift+A` | Mark the last added Anki card as an audio card (sets IsAudioCard, SentenceAudio, Sentence, Picture)           |
-| `Ctrl+D`       | Open loaded character dictionary manager                                                                      |
-| `Ctrl+Shift+O` | Open runtime options palette (session-only live toggles)                                                      |
-| `Ctrl/Cmd+A`   | Append clipboard video path to MPV playlist (configurable via `shortcuts.appendClipboardVideoToQueue`)        |
-
-**Multi-line copy workflow:**
-
-1. Press `Ctrl+Shift+C`
-2. Press a number key (`1-9`) within 3 seconds
-3. The specified number of most recent subtitle lines are copied
-4. Press `Ctrl+V` to update the last added card with the copied lines
-
-These shortcuts are only active when the overlay window is visible and automatically disabled when hidden.
-
-### Session Help Modal
-
-The session help modal opens from the overlay with `Ctrl/Cmd+/` by default. The mpv plugin also exposes it through the `y-h` chord. It shows the current session keybindings and color legend.
-
-You can filter the modal quickly with `/`:
-
-- Type any part of the action name or shortcut in the search bar.
-- Search is case-insensitive and ignores spaces/punctuation (`+`, `-`, `_`, `/`) so `ctrl w`, `ctrl+w`, and `ctrl+s` all match.
-- Results are filtered across active MPV shortcuts, configured overlay shortcuts, and color legend items.
-
-While the modal is open:
-
-- `Esc`: close the modal (or clear the filter when text is entered)
-- `↑/↓`, `j/k`: move selection
-- Mouse/trackpad: click to select and activate rows
-
-The list is generated at runtime from:
-
-- Your active mpv keybindings (`keybindings`).
-- Your configured overlay shortcuts (`shortcuts`, including runtime-loaded config values).
-- Current subtitle color settings from `subtitleStyle`.
-
-When config hot-reload updates shortcut/keybinding/style values, close and reopen the help modal to refresh the displayed entries.
-
-### Runtime Option Palette
-
-Use the runtime options palette to toggle settings live while SubMiner is running. These changes are session-only and reset on restart.
-
-Current runtime options cover automatic card updates, known-word highlighting,
-known-word maturity coloring, N+1 annotation, JLPT underlines, frequency
-highlighting, known-word match mode, and Kiku field grouping mode.
-
-Annotation toggles only apply to new subtitle lines after the toggle. The currently displayed line is not re-tokenized in place.
-
-Default shortcut: `Ctrl+Shift+O`
-
-Palette controls:
-
-- `Arrow Up/Down`: select option
-- `Arrow Left/Right`: change selected value
-- `Enter`: apply selected value
-- `Esc`: close
-
-## Anki Integration
-
-### Shared AI Provider
-
-This is the single, shared connection to an OpenAI-compatible LLM endpoint. Configure it **once** here at the top level, and SubMiner reuses it wherever AI is needed (Anki translation/enrichment and YouTube subtitle fixing). Per-feature toggles and prompt/model tweaks live in their own sections (for example `ankiConnect.ai` and `youtubeSubgen.ai`) and inherit this transport.
-
-```json
-{
-  "ai": {
-    "enabled": false,
-    "apiKey": "",
-    "apiKeyCommand": "",
-    "model": "openai/gpt-4o-mini",
-    "baseUrl": "https://openrouter.ai/api",
-    "requestTimeoutMs": 15000
-  }
-}
-```
-
-| Option             | Values               | Description                                                                          |
-| ------------------ | -------------------- | ------------------------------------------------------------------------------------ |
-| `ai.enabled`       | `true`, `false`      | Enable shared AI provider features (default: `false`)                                |
-| `apiKey`           | string               | Static API key for the shared provider                                               |
-| `apiKeyCommand`    | string               | Shell command used to resolve the API key (preferred over a plaintext `apiKey`)      |
-| `model`            | string               | Default model identifier requested from the provider (default: `openai/gpt-4o-mini`) |
-| `baseUrl`          | string (URL)         | OpenAI-compatible base URL (default: `https://openrouter.ai/api`)                    |
-| `systemPrompt`     | string               | Default system prompt sent with requests (default: a translation-engine prompt)      |
-| `requestTimeoutMs` | integer milliseconds | Shared request timeout (default: `15000`)                                            |
-
-SubMiner uses the shared provider for:
-
-- Anki translation/enrichment when Anki AI is enabled
-- YouTube generated-subtitle fixing when `youtubeSubgen.fixWithAi` is enabled (with optional `youtubeSubgen.ai.model` / `systemPrompt` overrides)
+## Anki integration
 
 ### AnkiConnect
 
-Enable automatic Anki card creation and updates with media generation:
+Creates and updates Anki cards with sentence, audio, and screenshot. Needs the [AnkiConnect](https://github.com/FooSoft/anki-connect) add-on and ffmpeg. See [Anki integration](/anki-integration) for setup, the proxy, and media options in detail.
 
 ```json
 {
   "ankiConnect": {
-    "enabled": true,
-    "url": "http://127.0.0.1:8765",
-    "pollingRate": 3000,
-    "proxy": {
-      "enabled": true,
-      "host": "127.0.0.1",
-      "port": 8766,
-      "upstreamUrl": "http://127.0.0.1:8765"
-    },
-    "tags": ["SubMiner"],
-    "deck": "Learning::Japanese",
-    "fields": {
-      "word": "Expression",
-      "audio": "ExpressionAudio",
-      "image": "Picture",
-      "sentence": "Sentence",
-      "miscInfo": "MiscInfo",
-      "translation": "SelectionText"
-    },
-    "ai": {
-      "enabled": false,
-      "model": "",
-      "systemPrompt": ""
-    },
-    "media": {
-      "generateAudio": true,
-      "generateImage": true,
-      "imageType": "static",
-      "imageFormat": "jpg",
-      "imageQuality": 92,
-      "imageMaxWidth": 0,
-      "imageMaxHeight": 0,
-      "animatedFps": 10,
-      "animatedMaxWidth": 640,
-      "animatedMaxHeight": 0,
-      "animatedCrf": 35,
-      "normalizeAudio": true,
-      "mirrorMpvVolume": true,
-      "audioPadding": 0,
-      "fallbackDuration": 3,
-      "maxMediaDuration": 30
-    },
-    "behavior": {
-      "autoUpdateNewCards": true,
-      "overwriteAudio": true,
-      "overwriteImage": true
-    },
-    "metadata": {
-      "pattern": "[SubMiner] %f (%t)"
-    },
-    "isLapis": {
-      "enabled": false,
-      "sentenceCardModel": "Lapis"
-    },
-    "isKiku": {
-      "enabled": false,
-      "fieldGrouping": "disabled",
-      "deleteDuplicateInAuto": true
-    }
+    "deck": "Mining",
+    "fields": { "audio": "SentenceAudio", "image": "Picture" },
+    "knownWords": { "highlightEnabled": true, "decks": { "Mining": ["Expression"] } }
   }
 }
 ```
 
-This example is intentionally compact. The option table below documents available `ankiConnect` settings and behavior.
+**Connection**
 
-**Requirements:** [AnkiConnect](https://github.com/FooSoft/anki-connect) plugin must be installed and running in Anki. ffmpeg must be installed for media generation.
+| Key                             | Default                   | What it does                                                                   |
+| ------------------------------- | ------------------------- | ------------------------------------------------------------------------------ |
+| `ankiConnect.enabled`           | `true`                    | Enable Anki integration                                                        |
+| `ankiConnect.url`               | `"http://127.0.0.1:8765"` | AnkiConnect URL                                                                |
+| `ankiConnect.pollingRate`       | `3000`                    | Milliseconds between checks for new cards (polling mode)                       |
+| `ankiConnect.proxy.enabled`     | `true`                    | Run a local AnkiConnect proxy so cards added through it are updated right away |
+| `ankiConnect.proxy.host`        | `"127.0.0.1"`             | Proxy bind host                                                                |
+| `ankiConnect.proxy.port`        | `8766`                    | Proxy bind port                                                                |
+| `ankiConnect.proxy.upstreamUrl` | `"http://127.0.0.1:8765"` | Where the proxy forwards requests                                              |
+| `ankiConnect.tags`              | `["SubMiner"]`            | Tags added to mined and updated cards. `[]` disables                           |
+| `ankiConnect.deck`              | `""`                      | Deck for duplicate checks and enrichment. Empty uses Yomitan's mining deck     |
 
-| Option                                            | Values                                      | Description                                                                                                                                                                                                                     |
-| ------------------------------------------------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `ankiConnect.enabled`                             | `true`, `false`                             | Enable AnkiConnect integration (default: `true`)                                                                                                                                                                                |
-| `url`                                             | string (URL)                                | AnkiConnect API URL (default: `http://127.0.0.1:8765`)                                                                                                                                                                          |
-| `pollingRate`                                     | number (ms)                                 | How often to check for new cards in polling mode (default: `3000`; ignored for direct proxy `addNote`/`addNotes` updates)                                                                                                       |
-| `proxy.enabled`                                   | `true`, `false`                             | Enable local AnkiConnect-compatible proxy for push-based auto-enrichment (default: `true`)                                                                                                                                      |
-| `proxy.host`                                      | string                                      | Bind host for local AnkiConnect proxy (default: `127.0.0.1`)                                                                                                                                                                    |
-| `proxy.port`                                      | number                                      | Bind port for local AnkiConnect proxy (default: `8766`)                                                                                                                                                                         |
-| `proxy.upstreamUrl`                               | string (URL)                                | Upstream AnkiConnect URL that proxy forwards to (default: `http://127.0.0.1:8765`)                                                                                                                                              |
-| `tags`                                            | array of strings                            | Tags automatically added to cards mined/updated by SubMiner (default: `['SubMiner']`; set `[]` to disable automatic tagging).                                                                                                   |
-| `ankiConnect.deck`                                | string                                      | Restrict duplicate detection and card enrichment to this Anki deck. Leave empty to use the Yomitan mining deck when available. In Settings, this dropdown auto-fills and persists Yomitan's current mining deck when available. |
-| `fields.word`                                     | string                                      | Card field for mined word / expression text (default: `Expression`)                                                                                                                                                             |
-| `fields.audio`                                    | string                                      | Card field for audio files (default: `ExpressionAudio`)                                                                                                                                                                         |
-| `fields.image`                                    | string                                      | Card field for images (default: `Picture`)                                                                                                                                                                                      |
-| `fields.sentence`                                 | string                                      | Card field for sentences (default: `Sentence`)                                                                                                                                                                                  |
-| `fields.miscInfo`                                 | string                                      | Card field for metadata (default: `"MiscInfo"`, set to `null` to disable)                                                                                                                                                       |
-| `fields.translation`                              | string                                      | Card field for sentence-card translation/back text (default: `SelectionText`)                                                                                                                                                   |
-| `ankiConnect.ai.enabled`                          | `true`, `false`                             | Use AI translation for sentence cards. Also auto-attempted when secondary subtitle is missing.                                                                                                                                  |
-| `ankiConnect.ai.model`                            | string                                      | Optional model override for Anki AI translation/enrichment flows.                                                                                                                                                               |
-| `ankiConnect.ai.systemPrompt`                     | string                                      | Optional system prompt override for Anki AI translation/enrichment flows.                                                                                                                                                       |
-| `media.generateAudio`                             | `true`, `false`                             | Generate audio clips from video (default: `true`)                                                                                                                                                                               |
-| `media.normalizeAudio`                            | `true`, `false`                             | Normalize generated sentence-audio loudness during media extraction (default: `true`). Set to `false` to keep raw source loudness. Changes apply live.                                                                          |
-| `media.mirrorMpvVolume`                           | `true`, `false`                             | Apply mpv's cubic software-volume curve to each generated sentence-audio clip (default: `true`). This ignores mpv's separate mute state, falls back to unity scaling if volume cannot be read, and applies changes live.        |
-| `media.generateImage`                             | `true`, `false`                             | Generate image/animation screenshots (default: `true`)                                                                                                                                                                          |
-| `media.imageType`                                 | `"static"`, `"avif"`                        | Image type: static screenshot or animated AVIF (default: `"static"`)                                                                                                                                                            |
-| `media.imageFormat`                               | `"jpg"`, `"png"`, `"webp"`                  | Image format (default: `"jpg"`)                                                                                                                                                                                                 |
-| `media.imageQuality`                              | number (1-100)                              | Image quality for JPG/WebP; PNG ignores this (default: `92`). JPG values are mapped onto FFmpeg's 2-31 quality scale; WebP uses the value directly.                                                                             |
-| `media.imageMaxWidth`                             | number (px)                                 | Optional max width for static screenshots. Unset keeps source width.                                                                                                                                                            |
-| `media.imageMaxHeight`                            | number (px)                                 | Optional max height for static screenshots. Unset keeps source height.                                                                                                                                                          |
-| `media.animatedFps`                               | number (1-60)                               | FPS for animated AVIF (default: `10`)                                                                                                                                                                                           |
-| `media.animatedMaxWidth`                          | number (px)                                 | Max width for animated AVIF (default: `640`)                                                                                                                                                                                    |
-| `media.animatedMaxHeight`                         | number (px)                                 | Optional max height for animated AVIF. Unset keeps source aspect-constrained height.                                                                                                                                            |
-| `media.animatedCrf`                               | number (0-63)                               | CRF quality for AVIF; lower = higher quality (default: `35`)                                                                                                                                                                    |
-| `media.syncAnimatedImageToWordAudio`              | `true`, `false`                             | Whether animated AVIF includes an opening frame synced to sentence word-audio timing (default: `true`).                                                                                                                         |
-| `media.audioPadding`                              | number (seconds)                            | Optional padding around generated sentence media timing (default: `0`). Animated AVIF clips include the same padded source range as sentence audio.                                                                             |
-| `media.fallbackDuration`                          | number (seconds)                            | Default duration if timing unavailable (default: `3.0`)                                                                                                                                                                         |
-| `media.maxMediaDuration`                          | number (seconds)                            | Max duration for generated media from multi-line copy (default: `30`, `0` to disable)                                                                                                                                           |
-| `behavior.overwriteAudio`                         | `true`, `false`                             | Replace existing audio on updates; when `false`, new audio is appended/prepended using the configured media insert mode; manual clipboard updates always replace generated sentence audio (default: `true`)                     |
-| `behavior.overwriteImage`                         | `true`, `false`                             | Replace existing images on updates; when `false`, new images are appended/prepended using the configured media insert mode (default: `true`)                                                                                    |
-| `behavior.mediaInsertMode`                        | `"append"`, `"prepend"`                     | Where to insert new media when overwrite is off (default: `"append"`)                                                                                                                                                           |
-| `behavior.highlightWord`                          | `true`, `false`                             | Highlight the word in sentence context (default: `true`)                                                                                                                                                                        |
-| `ankiConnect.knownWords.highlightEnabled`         | `true`, `false`                             | Enable fast local highlighting for words already known in Anki (default: `false`)                                                                                                                                               |
-| `ankiConnect.knownWords.addMinedWordsImmediately` | `true`, `false`                             | Add words from successful mines into the local known-word cache immediately (default: `true`)                                                                                                                                   |
-| `ankiConnect.knownWords.matchMode`                | `"headword"`, `"surface"`                   | Matching strategy for known-word highlighting (default: `"headword"`). `headword` uses token headwords; `surface` uses visible subtitle text.                                                                                   |
-| `ankiConnect.knownWords.refreshMinutes`           | number                                      | Minutes between known-word cache refreshes (default: `1440`)                                                                                                                                                                    |
-| `ankiConnect.knownWords.decks`                    | object                                      | Deck→fields mapping used for known-word cache query scope (e.g. `{ "Kaishi 1.5k": ["Word"] }`).                                                                                                                                 |
-| `ankiConnect.knownWords.maturityEnabled`          | `true`, `false`                             | Color known words by Anki card maturity (new/learning/young/mature) instead of one color. Requires `knownWords.highlightEnabled` (default: `false`). Tier colors come from `subtitleStyle.knownWordMaturityColors`.             |
-| `ankiConnect.knownWords.matureThresholdDays`      | number                                      | Card interval in days at which a known word counts as mature (default: `21`, matching Anki's own convention)                                                                                                                    |
-| `ankiConnect.nPlusOne.enabled`                    | `true`, `false`                             | Enable N+1 subtitle highlighting (highlights the one unknown word in a sentence). Independent from `knownWords.highlightEnabled`. Requires known-word cache data (default: `false`).                                            |
-| `ankiConnect.nPlusOne.minSentenceWords`           | number                                      | Minimum number of words required in a sentence before single unknown-word N+1 highlighting can trigger (default: `3`).                                                                                                          |
-| `behavior.notificationType`                       | `"overlay"`, `"system"`, `"both"`, `"none"` | Notification type on card update (default: `"overlay"`). `"both"` means overlay + system. `osd` and `osd-system` are legacy config-file-only values; use `"osd-system"` to keep the old OSD + system behavior.                  |
-| `behavior.autoUpdateNewCards`                     | `true`, `false`                             | Automatically update cards on creation (default: `true`)                                                                                                                                                                        |
-| `metadata.pattern`                                | string                                      | Format pattern for metadata: `%f`=filename, `%F`=filename+ext, `%t`=time, `%T`=time with milliseconds, `<br>`=newline                                                                                                           |
-| `isLapis`                                         | object                                      | Lapis/shared sentence-card config: `{ enabled, sentenceCardModel }`. Sentence/audio field names are fixed to `Sentence` and `SentenceAudio`.                                                                                    |
-| `isKiku`                                          | object                                      | Kiku-only config: `{ enabled, fieldGrouping, deleteDuplicateInAuto }` (shared sentence/audio/model settings are inherited from `isLapis`)                                                                                       |
+**Fields**
 
-`ankiConnect.ai` only controls feature-local enablement plus optional `model` / `systemPrompt` overrides.
-API key resolution, base URL, and timeout live under the shared top-level [`ai`](#shared-ai-provider) config.
+| Key                            | Default                | What it does                                                                                                                   |
+| ------------------------------ | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `ankiConnect.fields.word`      | `"Expression"`         | Word field                                                                                                                     |
+| `ankiConnect.fields.audio`     | `"ExpressionAudio"`    | Field that receives sentence audio. Set a separate field such as `SentenceAudio` so it does not overwrite Yomitan's word audio |
+| `ankiConnect.fields.wordAudio` | `"ExpressionAudio"`    | Existing word-audio field, read only to time animated images                                                                   |
+| `ankiConnect.fields.image`     | `"Picture"`            | Screenshot field                                                                                                               |
+| `ankiConnect.fields.sentence`  | `"Sentence"`           | Sentence field                                                                                                                 |
+| `ankiConnect.fields.miscInfo`  | `"MiscInfo"`           | Metadata field. `null` disables                                                                                                |
+| `ankiConnect.metadata.pattern` | `"[SubMiner] %f (%t)"` | MiscInfo template: `%f` filename, `%F` filename with extension, `%t` time, `%T` time with ms, `<br>` newline                   |
 
-### Kiku/Lapis Integration
+**Media**
 
-SubMiner is intentionally built for [Kiku](https://kiku.youyoumu.my.id/) and [Lapis](https://github.com/donkuri/lapis) workflows, with note-type-specific behavior built into Anki settings.
+| Key                                              | Default    | What it does                                                 |
+| ------------------------------------------------ | ---------- | ------------------------------------------------------------ |
+| `ankiConnect.media.generateAudio`                | `true`     | Cut a sentence audio clip                                    |
+| `ankiConnect.media.generateImage`                | `true`     | Capture a screenshot or animation                            |
+| `ankiConnect.media.imageType`                    | `"static"` | `static` or `avif` (animated)                                |
+| `ankiConnect.media.imageFormat`                  | `"jpg"`    | Static format: `jpg`, `png`, `webp`                          |
+| `ankiConnect.media.imageQuality`                 | `92`       | JPG/WebP quality. PNG ignores it                             |
+| `ankiConnect.media.imageMaxWidth`                | `0`        | Max static width in px. `0` keeps the source size            |
+| `ankiConnect.media.imageMaxHeight`               | `0`        | Max static height in px. `0` keeps the source size           |
+| `ankiConnect.media.animatedFps`                  | `10`       | AVIF frame rate                                              |
+| `ankiConnect.media.animatedMaxWidth`             | `640`      | AVIF max width                                               |
+| `ankiConnect.media.animatedMaxHeight`            | `0`        | AVIF max height. `0` keeps the aspect ratio                  |
+| `ankiConnect.media.animatedCrf`                  | `35`       | AVIF quality. Lower is better and larger                     |
+| `ankiConnect.media.syncAnimatedImageToWordAudio` | `true`     | Hold the first AVIF frame for the length of the word audio   |
+| `ankiConnect.media.normalizeAudio`               | `true`     | Normalize clip loudness                                      |
+| `ankiConnect.media.mirrorMpvVolume`              | `true`     | Apply mpv's current volume to the clip                       |
+| `ankiConnect.media.reviewTiming`                 | `false`    | Pause and let you adjust clip timing before media is created |
+| `ankiConnect.media.audioPadding`                 | `0`        | Seconds added to both ends of audio and AVIF clips           |
+| `ankiConnect.media.fallbackDuration`             | `3`        | Clip length in seconds when subtitle timing is missing       |
+| `ankiConnect.media.maxMediaDuration`             | `30`       | Longest allowed clip in seconds. `0` removes the cap         |
 
-```jsonc
-"ankiConnect": {
-  "isLapis": {
-    "enabled": true,
-    "sentenceCardModel": "Japanese sentences"
-  },
-  "isKiku": {
-    "enabled": true,
-    "fieldGrouping": "manual",
-    "deleteDuplicateInAuto": true
-  },
-  "lapisKiku": {
-    "wordCardKind": "word-and-sentence"
-  }
-}
-```
+**Behavior**
 
-- Enable `isLapis` to mine dedicated sentence cards. SubMiner sets `IsSentenceCard` to `"x"` and fills the sentence fields for the configured model.
-- Enable `isKiku` to turn on duplicate merge behavior for mined Word/Expression hits.
-- When both are enabled, Kiku behavior is applied for grouping while sentence-card model settings are still read from `isLapis`.
-- `isKiku.fieldGrouping` supports `disabled`, `auto`, and `manual` merge modes; see [Field Grouping Modes](#field-grouping-modes).
-- `lapisKiku.wordCardKind` picks the card-type flag set on word cards; see [Word Card Type](#word-card-type). It is read only while `isLapis` or `isKiku` is enabled.
+| Key                                       | Default     | What it does                                                             |
+| ----------------------------------------- | ----------- | ------------------------------------------------------------------------ |
+| `ankiConnect.behavior.autoUpdateNewCards` | `true`      | Fill new cards automatically. When off, use the manual shortcuts         |
+| `ankiConnect.behavior.overwriteAudio`     | `true`      | Replace existing audio. When off, add alongside it                       |
+| `ankiConnect.behavior.overwriteImage`     | `true`      | Replace existing images. When off, add alongside them                    |
+| `ankiConnect.behavior.mediaInsertMode`    | `"append"`  | `append` or `prepend` when not overwriting                               |
+| `ankiConnect.behavior.highlightWord`      | `true`      | Bold the mined word in the sentence field                                |
+| `ankiConnect.behavior.notificationType`   | `"overlay"` | Where mining and status messages go: `overlay`, `system`, `both`, `none` |
 
-### Word Card Type
+**Known words and N+1**
 
-When SubMiner fills the sentence on a mined word card - from Yomitan auto-enrichment, a manual clipboard update, or stats-dashboard word mining - it marks which card that note should generate. `ankiConnect.lapisKiku.wordCardKind` chooses the flag:
+| Key                                               | Default      | What it does                                                                     |
+| ------------------------------------------------- | ------------ | -------------------------------------------------------------------------------- |
+| `ankiConnect.knownWords.highlightEnabled`         | `false`      | Highlight words that already exist in your Anki decks                            |
+| `ankiConnect.knownWords.decks`                    | `{}`         | Decks and word fields to read, for example `{ "Kaishi 1.5k": ["Word"] }`         |
+| `ankiConnect.knownWords.matchMode`                | `"headword"` | Match by `headword` or `surface` text                                            |
+| `ankiConnect.knownWords.refreshMinutes`           | `1440`       | Minutes between cache refreshes                                                  |
+| `ankiConnect.knownWords.addMinedWordsImmediately` | `true`       | Add newly mined words to the cache right away                                    |
+| `ankiConnect.knownWords.maturityEnabled`          | `false`      | Color known words by card maturity using `subtitleStyle.knownWordMaturityColors` |
+| `ankiConnect.knownWords.matureThresholdDays`      | `21`         | Interval in days at which a card counts as mature                                |
+| `ankiConnect.nPlusOne.enabled`                    | `false`      | Highlight the only unknown word in a sentence. Needs known-word data             |
+| `ankiConnect.nPlusOne.minSentenceWords`           | `3`          | Minimum words in a sentence before N+1 applies                                   |
 
-| Value                         | Flag set                |
+Use word fields such as `Expression` or `Word` in `knownWords.decks`, not reading fields. See [Subtitle annotations](/subtitle-annotations) for how matching and maturity tiers work.
+
+### Kiku/Lapis integration {#kiku-lapis-integration}
+
+Note-type behavior for [Lapis](https://github.com/donkuri/lapis), [Kiku](https://kiku.youyoumu.my.id/), and [Senren](https://github.com/BrenoAqua/Senren). With both Lapis and Kiku on, Kiku handles duplicates and the sentence-card model comes from `isLapis`. Kiku and Senren are mutually exclusive. If both are on, Kiku wins and SubMiner logs a warning. See [Anki integration](/anki-integration) for details.
+
+| Key                                          | Default               | What it does                                           |
+| -------------------------------------------- | --------------------- | ------------------------------------------------------ |
+| `ankiConnect.isLapis.enabled`                | `false`               | Mine dedicated sentence cards (`IsSentenceCard`)       |
+| `ankiConnect.isLapis.sentenceCardModel`      | `"Lapis"`             | Note type used for sentence cards                      |
+| `ankiConnect.isKiku.enabled`                 | `false`               | Merge duplicate word cards                             |
+| `ankiConnect.isKiku.fieldGrouping`           | `"disabled"`          | `auto`, `manual`, or `disabled`. See below             |
+| `ankiConnect.isKiku.deleteDuplicateInAuto`   | `true`                | Delete the duplicate after an `auto` merge             |
+| `ankiConnect.isSenren.enabled`               | `false`               | Merge duplicates using Senren's scene-switching format |
+| `ankiConnect.isSenren.fieldGrouping`         | `"auto"`              | `auto`, `manual`, or `disabled`                        |
+| `ankiConnect.isSenren.deleteDuplicateInAuto` | `true`                | Delete the duplicate after an `auto` merge             |
+| `ankiConnect.lapisKiku.wordCardKind`         | `"word-and-sentence"` | Card-type flag set on word cards. See below            |
+
+### Word card type
+
+When SubMiner fills the sentence on a word card, it sets one card-type flag and clears the others. Only applies while `isLapis` or `isKiku` is on. Cards from Mine Sentence and Mine Audio keep their own flag.
+
+| `wordCardKind`                | Flag set                |
 | ----------------------------- | ----------------------- |
 | `word-and-sentence` (default) | `IsWordAndSentenceCard` |
 | `click`                       | `IsClickCard`           |
 | `sentence`                    | `IsSentenceCard`        |
 | `audio`                       | `IsAudioCard`           |
-| `none`                        | none; flags left as-is  |
+| `none`                        | none, flags left as-is  |
 
-The other card-type flags are cleared so a note never claims two card types at once. Notes are skipped when the note type has no field for the chosen flag, and when the note was already mined as a sentence or audio card. Cards created by Mine Sentence and Mine Audio keep their own flag regardless of this setting.
+### Field grouping modes
 
-### N+1 Word Highlighting
-
-When known-word highlighting is enabled, SubMiner builds a local cache of known words from Anki to highlight already learned tokens in subtitle rendering.
-
-Known-word cache policy:
-
-- Initial sync runs when the integration starts if the cache is missing or stale.
-- The refresh interval controls the minimum time between syncs; between refreshes, cached words are reused without querying Anki.
-- `subtitleStyle.nPlusOneColor` sets the color for the single target token when exactly one eligible unknown word exists.
-- The N+1 minimum sentence-word setting controls the token count required before N+1 highlighting can trigger.
-- `subtitleStyle.knownWordColor` sets the known-word highlight color for tokens already in Anki.
-- Set `ankiConnect.knownWords.maturityEnabled` to `true` to color known words by Anki card maturity instead, using the four `subtitleStyle.knownWordMaturityColors` tiers. See [Known-Word Maturity Highlighting](/subtitle-annotations#known-word-maturity-highlighting) for how tiers are derived. Changing it or `matureThresholdDays` forces a full cache refresh.
-- The known-word deck map accepts an object keyed by deck name.
-- Prefer expression/word fields such as `Expression` or `Word`. Avoid reading-only fields unless you intentionally want homophone readings to count as known words.
-- Cache state is persisted to `known-words-cache.json` under the app `userData` directory.
-- The cache is automatically invalidated when the configured scope changes (for example, when deck changes).
-- Cache lookups are in-memory. By default, token headwords are matched against cached `Expression` / `Word` values; set known-word matching to `"surface"` for raw subtitle text matching.
-- A known-word cache match always receives known-word highlighting, even when part-of-speech filters suppress N+1, frequency, or JLPT annotations for that token.
-- If AnkiConnect is unreachable, the cache remains in its previous state and an on-screen/system status message is shown.
-- Known-word sync activity is logged at `INFO`/`DEBUG` level with the `anki` logger scope and includes scope, notes returned, and word counts.
-
-To refresh roughly once per day, set:
-
-```json
-{
-  "ankiConnect": {
-    "knownWords": {
-      "highlightEnabled": true,
-      "refreshMinutes": 1440
-    },
-    "nPlusOne": {
-      "minSentenceWords": 3
-    }
-  }
-}
-```
-
-### Field Grouping Modes
-
-| Mode       | Behavior                                                                                                                   |
-| ---------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `auto`     | Automatically merges the new card's content into the original; duplicate deletion is controlled by `deleteDuplicateInAuto` |
-| `manual`   | Shows an overlay popup to choose which card to keep and whether to delete the duplicate after merge                        |
-| `disabled` | No field grouping; duplicate cards are left as-is                                                                          |
-
-`deleteDuplicateInAuto` controls whether `auto` mode deletes the duplicate after merge (default: `true`). In `manual` mode, the popup asks each time whether to delete the duplicate.
-When the manual merge popup opens, SubMiner pauses playback and closes any open Yomitan popup first so the merge flow can take focus.
+| Mode       | What happens when you mine a duplicate                                                                     |
+| ---------- | ---------------------------------------------------------------------------------------------------------- |
+| `auto`     | Merges the new card into the existing one. `deleteDuplicateInAuto` decides whether the new card is deleted |
+| `manual`   | Pauses playback and opens a dialog to choose which card to keep and whether to delete the other            |
+| `disabled` | Leaves both cards as they are                                                                              |
 
 <video controls playsinline preload="metadata" :poster="withBase('/assets/kiku-integration-poster.jpg')" style="width: 100%; max-width: 960px;">
   <source :src="withBase('/assets/kiku-integration.webm')" type="video/webm" />
@@ -1150,478 +425,181 @@ When the manual merge popup opens, SubMiner pauses playback and closes any open
   Your browser does not support the video tag.
 </video>
 
-<a :href="withBase('/assets/kiku-integration.webm')" target="_blank" rel="noreferrer">Open demo in a new tab</a>
-
-## External Integrations
+## External integrations
 
 ### Jimaku
 
-Configure Jimaku API access and defaults:
+Search and download Japanese subtitles from [Jimaku](https://jimaku.cc). See [Jimaku integration](/jimaku-integration).
 
-```json
-{
-  "jimaku": {
-    "apiKey": "YOUR_API_KEY",
-    "apiKeyCommand": "cat ~/.jimaku_key",
-    "apiBaseUrl": "https://jimaku.cc",
-    "languagePreference": "ja",
-    "maxEntryResults": 10
-  }
-}
-```
-
-Jimaku is rate limited; if you hit a limit, SubMiner will surface the retry delay from the API response.
+| Key                         | Default               | What it does                                               |
+| --------------------------- | --------------------- | ---------------------------------------------------------- |
+| `jimaku.apiKey`             | `""`                  | API key. Optional, but raises your rate limit              |
+| `jimaku.apiKeyCommand`      | `""`                  | Shell command that prints the key. Use instead of `apiKey` |
+| `jimaku.apiBaseUrl`         | `"https://jimaku.cc"` | API base URL                                               |
+| `jimaku.languagePreference` | `"ja"`                | Preferred language: `ja`, `en`, or `none`                  |
+| `jimaku.maxEntryResults`    | `10`                  | Maximum search results                                     |
 
 ### TsukiHime
 
-TsukiHime subtitle search works out of the box and needs no account or API key. It does require the `xz` binary on your `PATH`, because TsukiHime serves extracted subtitles xz-compressed.
+Subtitle search that needs no account or key. It does need `xz` on your `PATH`. The shortcut is `shortcuts.openTsukihime`. See [TsukiHime integration](/tsukihime-integration).
 
-```json
-{
-  "tsukihime": {
-    "apiBaseUrl": "https://api.tsukihime.org/v1",
-    "maxSearchResults": 10
-  }
-}
-```
+| Key                          | Default                          | What it does                                         |
+| ---------------------------- | -------------------------------- | ---------------------------------------------------- |
+| `tsukihime.apiBaseUrl`       | `"https://api.tsukihime.org/v1"` | API base URL. Only change it for a mirror            |
+| `tsukihime.maxSearchResults` | `10`                             | Maximum releases per search (the API caps it at 100) |
 
-| Option                       | Values       | Description                                                                                           |
-| ---------------------------- | ------------ | ----------------------------------------------------------------------------------------------------- |
-| `tsukihime.apiBaseUrl`       | string (URL) | Base URL of the TsukiHime API (default: `https://api.tsukihime.org/v1`). Only change it for a mirror. |
-| `tsukihime.maxSearchResults` | number       | Maximum releases returned per search (default: `10`; the API caps this at 100)                        |
+### TMDB
 
-The keyboard shortcut lives under `shortcuts.openTsukihime` (default `Ctrl+Shift+T`; set to `null` to disable). The older `animetosho` section and `shortcuts.openAnimetosho` are still accepted as deprecated aliases, with the current names taking precedence when both are set.
+Posters, synopses, and show grouping for live-action titles in the stats [Library](/immersion-tracking). Release builds include a TMDB key, so you only need your own to use your own quota or when running from source. Get one free under **Settings > API** on [themoviedb.org](https://www.themoviedb.org/settings/api). Either the API key or the read access token works.
 
-See [TsukiHime Integration](/tsukihime-integration) for the modal workflow, language tabs, and troubleshooting.
+| Key                  | Default | What it does                                               |
+| -------------------- | ------- | ---------------------------------------------------------- |
+| `tmdb.apiKey`        | `""`    | Your TMDB key or token. Overrides the bundled key          |
+| `tmdb.apiKeyCommand` | `""`    | Shell command that prints the key. Use instead of `apiKey` |
 
-### Subtitle Sync
+This product uses the TMDB API but is not endorsed or certified by TMDB.
 
-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).
+### Japanese subtitle generation
 
-- [`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
+Transcribes Japanese subtitles locally with whisper.cpp. Open it with `Ctrl+Shift+G` (`shortcuts.openSubtitleGeneration`) or from the subtitle sidebar. See [Subtitle generation](/subtitle-generation).
 
-```json
-{
-  "subsync": {
-    "alass_path": "",
-    "ffsubsync_path": "",
-    "ffmpeg_path": "",
-    "replace": true
-  }
-}
-```
+| Key                               | Default   | What it does                                                            |
+| --------------------------------- | --------- | ----------------------------------------------------------------------- |
+| `subtitleGeneration.modelPath`    | `""`      | Path to a multilingual whisper.cpp GGML model. Overrides `managedModel` |
+| `subtitleGeneration.managedModel` | `"small"` | Model SubMiner downloads and uses when `modelPath` is empty             |
+| `subtitleGeneration.threads`      | `4`       | CPU threads                                                             |
+| `subtitleGeneration.vadModelPath` | `""`      | Silero VAD model. Set it to focus on spoken dialogue by default         |
+| `subtitleGeneration.whisperPath`  | `""`      | `whisper-cli` path. Empty searches `PATH`                               |
+| `subtitleGeneration.vadPath`      | `""`      | Speech detector path. Empty searches `PATH`                             |
+| `subtitleGeneration.ffmpegPath`   | `""`      | `ffmpeg` path. Empty searches `PATH`                                    |
+| `subtitleGeneration.ffprobePath`  | `""`      | `ffprobe` path. Empty searches `PATH`                                   |
 
-| Option           | Values          | Description                                                                                                               |
-| ---------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------- |
-| `alass_path`     | string path     | Path to `alass` executable. Empty falls back to `/usr/bin/alass`. `alass` must be installed separately.                   |
-| `ffsubsync_path` | string path     | Path to `ffsubsync` executable. Empty falls back to `/usr/bin/ffsubsync`. `ffsubsync` must be installed separately.       |
-| `ffmpeg_path`    | string path     | Path to `ffmpeg` (used for internal subtitle extraction). Empty or `null` falls back to `/usr/bin/ffmpeg`.                |
-| `replace`        | `true`, `false` | When `true` (default), overwrite the active subtitle file on successful sync. When `false`, write `<name>_retimed.<ext>`. |
+### Subtitle sync
 
-Stats dashboard sentence mining also uses `alass_path` when available to align a local English sidecar against the local Japanese sidecar before filling the card translation field. This stats-only retime writes a temporary cached copy and never edits the original subtitle files.
+Retimes a subtitle track with [`alass`](https://github.com/kaegi/alass) (against another subtitle or the video) or [`ffsubsync`](https://github.com/smacke/ffsubsync) (against the video's audio). Install them yourself. Open the picker with `Ctrl+Alt+S` (`shortcuts.triggerSubsync`).
 
-Default trigger is `Ctrl+Alt+S` via `shortcuts.triggerSubsync`.
-Customize it there, or set it to `null` to disable.
+| Key                      | Default | What it does                                                        |
+| ------------------------ | ------- | ------------------------------------------------------------------- |
+| `subsync.alass_path`     | `""`    | `alass` path. Empty uses `/usr/bin/alass`                           |
+| `subsync.ffsubsync_path` | `""`    | `ffsubsync` path. Empty uses `/usr/bin/ffsubsync`                   |
+| `subsync.ffmpeg_path`    | `""`    | `ffmpeg` path. Empty uses `/usr/bin/ffmpeg`                         |
+| `subsync.replace`        | `true`  | Overwrite the subtitle file. When off, write `<name>_retimed.<ext>` |
+
+If a tool lives somewhere else, such as on macOS or Windows, set its path.
 
 ### AniList
 
-AniList integration is opt-in and disabled by default. Enable it to allow SubMiner to update watched episode progress after playback.
+Updates your AniList watch progress after an episode, and controls the character dictionary. With `enabled` on and no token, SubMiner opens a login window. See [AniList integration](/anilist-integration) and [Character dictionary](/character-dictionary).
 
-```json
-{
-  "anilist": {
-    "enabled": true,
-    "accessToken": "",
-    "characterDictionary": {
-      "maxLoaded": 3,
-      "profileScope": "all",
-      "collapsibleSections": {
-        "description": false,
-        "characterInformation": false,
-        "voicedBy": false
-      }
-    }
-  }
-}
-```
-
-| Option                                                         | Values                  | Description                                                                                                   |
-| -------------------------------------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------- |
-| `anilist.enabled`                                              | `true`, `false`         | Enable AniList post-watch progress updates (default: `false`)                                                 |
-| `accessToken`                                                  | string                  | Optional explicit AniList access token override (default: empty string)                                       |
-| `characterDictionary.maxLoaded`                                | number                  | Maximum number of most-recently-used AniList media snapshots included in the merged dictionary (default: `3`) |
-| `characterDictionary.refreshTtlHours`                          | number                  | Hours before a cached media snapshot is refreshed (default: `168`, clamped to 1–8760)                         |
-| `characterDictionary.evictionPolicy`                           | `"delete"`, `"disable"` | What happens to snapshots evicted beyond `maxLoaded` (default: `"delete"`)                                    |
-| `characterDictionary.collapsibleSections.description`          | `true`, `false`         | Open the Description section by default in generated dictionary entries                                       |
-| `characterDictionary.collapsibleSections.characterInformation` | `true`, `false`         | Open the Character Information section by default in generated dictionary entries                             |
-| `characterDictionary.collapsibleSections.voicedBy`             | `true`, `false`         | Open the Voiced by section by default in generated dictionary entries                                         |
-| `characterDictionary.profileScope`                             | `"all"`, `"active"`     | Apply dictionary settings updates to all Yomitan profiles or only active profile                              |
-
-When `enabled` is `true` and `accessToken` is empty, SubMiner opens an AniList setup helper window. Keep `enabled` as `false` to disable all AniList setup/update behavior.
-
-Character dictionary sync behavior:
-
-- Snapshot identity is still AniList **media ID**.
-- Sync/import runs only for the currently watched media when media path/title changes.
-- SubMiner keeps a most-recently-used list of synced AniList media snapshots and rebuilds one merged Yomitan dictionary from that active set.
-- `maxLoaded` controls how many recent AniList media snapshots stay in the merged dictionary at once.
-- The merged dictionary title stays stable as `SubMiner Character Dictionary`, so Yomitan sees one rotating dictionary instead of one dictionary per anime.
-
-Current post-watch behavior:
-
-- SubMiner attempts an update near episode completion using the shared default minimum watch ratio (`0.85`, or `>=85%`) from `src/shared/watch-threshold.ts`, and requires at least `10` minutes watched. The same ratio is also used by local episode watched state transitions.
-- Episode/title detection is `guessit`-first with fallback to SubMiner's filename parser.
-- If `guessit` is unavailable, updates still work via fallback parsing but title matching can be less accurate.
-- If embedded AniList auth UI fails to render, SubMiner opens the authorize URL in your default browser and shows fallback instructions in-app.
-- Failed updates are retried with a persistent backoff queue in the background.
-
-Setup flow details:
-
-1. Set `anilist.enabled` to `true`.
-2. Leave the AniList access-token field empty and restart SubMiner (or run `--anilist-setup`) to trigger setup.
-3. Approve access in AniList.
-4. Callback flow returns to SubMiner via `subminer://anilist-setup?...`, and SubMiner stores the token automatically.
-   - Encryption backend: Linux defaults to `gnome-libsecret`.
-     Override with `--password-store=<backend>` (for example `--password-store=basic_text`).
-
-Token + detection notes:
-
-- The AniList access token can be set directly in config; when blank, SubMiner uses the locally stored encrypted token from setup.
-- Detection quality is best when `guessit` is installed and available on `PATH`.
-- When `guessit` cannot parse or is missing, SubMiner falls back automatically to internal filename parsing.
-
-AniList CLI commands:
-
-- `--anilist-status`: print current AniList token resolution state and retry queue counters.
-- `--anilist-logout`: clear stored AniList token from local persisted state.
-- `--anilist-setup`: open AniList setup/auth flow helper window.
-- `--anilist-retry-queue`: process one ready retry queue item immediately.
+| Key                                                                    | Default | What it does                                                  |
+| ---------------------------------------------------------------------- | ------- | ------------------------------------------------------------- |
+| `anilist.enabled`                                                      | `false` | Enable progress updates                                       |
+| `anilist.accessToken`                                                  | `""`    | Token override. Empty uses the token saved during login       |
+| `anilist.characterDictionary.maxLoaded`                                | `3`     | How many recent shows stay in the merged character dictionary |
+| `anilist.characterDictionary.collapsibleSections.description`          | `false` | Open the Description section by default                       |
+| `anilist.characterDictionary.collapsibleSections.characterInformation` | `false` | Open the Character Information section by default             |
+| `anilist.characterDictionary.collapsibleSections.voicedBy`             | `false` | Open the Voiced by section by default                         |
 
 ### Yomitan
 
-SubMiner normally uses its bundled Yomitan profile under the app config directory. If you want to reuse dictionaries and profile settings from another Electron app, point SubMiner at that app's Yomitan Electron profile in read-only mode.
+Point SubMiner at another app's Yomitan Electron profile to reuse its dictionaries and settings. For GameSentenceMiner on Linux this is usually `~/.config/gsm_overlay`.
 
-For GameSentenceMiner on Linux, the default overlay profile path is typically `~/.config/gsm_overlay`.
+| Key                           | Default | What it does                                                            |
+| ----------------------------- | ------- | ----------------------------------------------------------------------- |
+| `yomitan.externalProfilePath` | `""`    | Absolute or `~` path to the external profile. Empty uses SubMiner's own |
 
-```json
-{
-  "yomitan": {
-    "externalProfilePath": "/home/you/.config/gsm_overlay"
-  }
-}
-```
-
-| Option                | Values      | Description                                                                                                                                                                                                    |
-| --------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `externalProfilePath` | string path | Optional absolute path, or a path beginning with `~` (expanded to your home directory), to another app's Yomitan Electron profile. SubMiner loads that profile read-only and reuses its dictionaries/settings. |
-
-External-profile mode behavior:
-
-- SubMiner uses the external profile's Yomitan extension/session instead of its local copy.
-- SubMiner reads the external profile's currently active Yomitan profile selection and installed dictionaries.
-- SubMiner does not open its own Yomitan settings window in this mode.
-- SubMiner does not import, delete, or update dictionaries/settings in the external profile.
-- SubMiner character-dictionary features are fully disabled in this mode, including auto-sync, manual generation, and subtitle-side character-dictionary annotations.
-- First-run setup does not require any internal dictionaries while this mode is configured. If you later launch without an external Yomitan profile, setup will require at least one internal Yomitan dictionary unless SubMiner already finds one.
+In external-profile mode, SubMiner only reads the profile. It does not open its own Yomitan settings, does not change dictionaries, and turns off all character-dictionary features.
 
 ### Jellyfin
 
-Jellyfin integration is optional and disabled by default. When enabled, SubMiner can authenticate, list libraries/items, and resolve direct/transcoded playback URLs for mpv launch.
+Log in to a Jellyfin server, browse libraries, and play or cast to SubMiner. Login tokens are stored encrypted, not in this file. See [Jellyfin integration](/jellyfin-integration).
 
-```json
-{
-  "jellyfin": {
-    "enabled": true,
-    "serverUrl": "http://127.0.0.1:8096",
-    "recentServers": ["http://127.0.0.1:8096"],
-    "username": "",
-    "remoteControlEnabled": true,
-    "remoteControlAutoConnect": true,
-    "autoAnnounce": false,
-    "defaultLibraryId": "",
-    "directPlayPreferred": true,
-    "directPlayContainers": ["mkv", "mp4", "webm", "mov", "flac", "mp3", "aac"],
-    "transcodeVideoCodec": "h264"
-  }
-}
-```
+| Key                                 | Default                          | What it does                                    |
+| ----------------------------------- | -------------------------------- | ----------------------------------------------- |
+| `jellyfin.enabled`                  | `false`                          | Enable Jellyfin                                 |
+| `jellyfin.serverUrl`                | `""`                             | Server URL, for example `http://localhost:8096` |
+| `jellyfin.username`                 | `""`                             | Default username for `subminer jellyfin -l`     |
+| `jellyfin.remoteControlEnabled`     | `true`                           | Let Jellyfin apps cast to SubMiner              |
+| `jellyfin.remoteControlAutoConnect` | `true`                           | Connect the cast session on startup             |
+| `jellyfin.autoAnnounce`             | `false`                          | Announce SubMiner as a cast target on connect   |
+| `jellyfin.pullPictures`             | `false`                          | Fetch posters for launcher pickers              |
+| `jellyfin.iconCacheDir`             | `"/tmp/subminer-jellyfin-icons"` | Poster cache folder                             |
+| `jellyfin.directPlayPreferred`      | `true`                           | Try direct play before transcoding              |
+| `jellyfin.transcodeVideoCodec`      | `"h264"`                         | Codec requested when transcoding                |
 
-| Option                     | Values          | Description                                                                                            |
-| -------------------------- | --------------- | ------------------------------------------------------------------------------------------------------ |
-| `jellyfin.enabled`         | `true`, `false` | Enable Jellyfin integration and CLI commands (default: `false`)                                        |
-| `serverUrl`                | string (URL)    | Jellyfin server base URL                                                                               |
-| `recentServers`            | string[]        | Recent Jellyfin server URLs shown in setup; entries are trimmed, deduped, and capped at 5              |
-| `username`                 | string          | Default username used by `--jellyfin-login`                                                            |
-| `defaultLibraryId`         | string          | Default library id for `--jellyfin-items` when CLI value is omitted                                    |
-| `remoteControlEnabled`     | `true`, `false` | Enable Jellyfin cast/remote-control session support                                                    |
-| `remoteControlAutoConnect` | `true`, `false` | Auto-connect Jellyfin remote session on app startup (requires Jellyfin integration and remote control) |
-| `autoAnnounce`             | `true`, `false` | Auto-run cast-target visibility announce check on connect (default: `false`)                           |
-| `pullPictures`             | `true`, `false` | Enable poster/icon fetching for launcher Jellyfin pickers                                              |
-| `iconCacheDir`             | string          | Cache directory for launcher-fetched Jellyfin poster icons                                             |
-| `directPlayPreferred`      | `true`, `false` | Prefer direct stream URLs before transcoding                                                           |
-| `directPlayContainers`     | string[]        | Container allowlist for direct play decisions                                                          |
-| `transcodeVideoCodec`      | string          | Preferred transcode video codec fallback (default: `h264`)                                             |
+### Discord rich presence
 
-Jellyfin auth session (`accessToken` + `userId`) is stored in local encrypted storage after login/setup. SubMiner reports the Jellyfin client as `SubMiner`, derives the Jellyfin device id and visible device name from the OS hostname, and owns the client version internally. The Settings window also hides low-level default library fields (`defaultLibraryId`) so normal setup stays focused on server, auth, playback, and remote-control behavior.
+Shows what you are watching on your Discord profile. Needs the Discord desktop app running. If Discord is closed, SubMiner skips updates.
 
-- On Linux, token storage defaults to `gnome-libsecret` for `safeStorage`. Override with `--password-store=<backend>` on launcher/app invocations when needed.
+| Key                                | Default     | What it does                                                       |
+| ---------------------------------- | ----------- | ------------------------------------------------------------------ |
+| `discordPresence.enabled`          | `true`      | Enable rich presence                                               |
+| `discordPresence.presenceStyle`    | `"default"` | Card text: `default`, `meme`, `japanese` (all Japanese), `minimal` |
+| `discordPresence.updateIntervalMs` | `3000`      | Minimum ms between updates                                         |
+| `discordPresence.debounceMs`       | `750`       | Debounce for bursts of playback events                             |
 
-Launcher subcommands:
+### Immersion tracking
 
-- `subminer jellyfin` (or `subminer jf`) opens setup.
-- `subminer jellyfin -l --server ... --username ... --password ...` logs in.
-- `subminer jellyfin --logout` clears stored credentials.
-- `subminer jellyfin -p` opens play picker.
-- `subminer jellyfin -d` starts cast discovery mode in background/tray mode.
-- These launcher commands also accept `--password-store=<backend>` to override the launcher-app forwarded Electron switch.
+Records watch sessions, subtitle lines, and mining in a local SQLite database that feeds the stats dashboard. See [Immersion tracking](/immersion-tracking) for retention and storage details. To turn it off for one run, start with `SUBMINER_DISABLE_IMMERSION_TRACKING=1 subminer`.
 
-See [Jellyfin Integration](/jellyfin-integration) for the full setup and cast-to-device guide.
+| Key                                              | Default      | What it does                                                      |
+| ------------------------------------------------ | ------------ | ----------------------------------------------------------------- |
+| `immersionTracking.enabled`                      | `true`       | Enable tracking                                                   |
+| `immersionTracking.dbPath`                       | `""`         | Database path. Empty uses `immersion.sqlite` in the config folder |
+| `immersionTracking.batchSize`                    | `25`         | Writes per transaction                                            |
+| `immersionTracking.flushIntervalMs`              | `500`        | Maximum ms before queued writes are saved                         |
+| `immersionTracking.queueCap`                     | `1000`       | Queue size. The oldest writes drop when full                      |
+| `immersionTracking.payloadCapBytes`              | `256`        | Maximum event payload size before truncation                      |
+| `immersionTracking.maintenanceIntervalMs`        | `86400000`   | How often pruning and rollups run (24 h)                          |
+| `immersionTracking.retentionMode`                | `"preset"`   | `preset` uses `retentionPreset`. `advanced` uses `retention.*`    |
+| `immersionTracking.retentionPreset`              | `"balanced"` | `minimal`, `balanced`, or `deep-history`                          |
+| `immersionTracking.retention.eventsDays`         | `0`          | Days to keep raw events. `0` keeps everything                     |
+| `immersionTracking.retention.telemetryDays`      | `0`          | Days to keep telemetry                                            |
+| `immersionTracking.retention.sessionsDays`       | `0`          | Days to keep sessions                                             |
+| `immersionTracking.retention.dailyRollupsDays`   | `0`          | Days to keep daily rollups                                        |
+| `immersionTracking.retention.monthlyRollupsDays` | `0`          | Days to keep monthly rollups                                      |
+| `immersionTracking.retention.vacuumIntervalDays` | `0`          | Days between `VACUUM` runs. `0` disables                          |
+| `immersionTracking.lifetimeSummaries.global`     | `true`       | Keep all-time totals                                              |
+| `immersionTracking.lifetimeSummaries.anime`      | `true`       | Keep per-show totals                                              |
+| `immersionTracking.lifetimeSummaries.media`      | `true`       | Keep per-file totals                                              |
 
-Jellyfin remote auto-connect runs only when Jellyfin integration, remote control, and remote auto-connect are all enabled.
+### Stats dashboard
 
-Jellyfin playback auto-launched through SubMiner loads the mpv plugin the same way regular playback does, and shows the visible subtitle overlay automatically so `subtitleStyle` applies to subtitles selected from Jellyfin.
+A local web dashboard at `http://127.0.0.1:<serverPort>`, also available as an overlay inside SubMiner. It reads the immersion tracking database, so tracking must be on. See [Immersion tracking](/immersion-tracking).
 
-When Jellyfin is enabled with a server URL and SubMiner is running, the tray menu also shows a `Jellyfin Discovery` checkbox. It starts or stops discovery for the current runtime session only and does not write config. Starting discovery still requires a valid stored or environment-provided Jellyfin auth session.
+| Key                     | Default       | What it does                                                       |
+| ----------------------- | ------------- | ------------------------------------------------------------------ |
+| `stats.toggleKey`       | `"Backquote"` | Key that toggles the stats overlay (overlay focus only)            |
+| `stats.markWatchedKey`  | `"KeyW"`      | Key that marks the video watched and plays the next playlist entry |
+| `stats.serverPort`      | `6969`        | Dashboard port                                                     |
+| `stats.autoStartServer` | `true`        | Start the dashboard server once tracking is active                 |
+| `stats.autoOpenBrowser` | `false`       | Open the browser when `subminer stats` starts the server           |
 
-### Discord Rich Presence
+### MPV launcher
 
-Discord Rich Presence is enabled by default. SubMiner publishes a polished activity card that reflects current media title, playback state, and session timer unless you turn it off.
+Settings for mpv instances that SubMiner starts, and for the bundled mpv plugin. See [mpv plugin](/mpv-plugin).
 
-```json
-{
-  "discordPresence": {
-    "enabled": true,
-    "presenceStyle": "default",
-    "updateIntervalMs": 3000,
-    "debounceMs": 750
-  }
-}
-```
+| Key                          | Default           | What it does                                                                |
+| ---------------------------- | ----------------- | --------------------------------------------------------------------------- |
+| `mpv.executablePath`         | `""`              | Path to `mpv.exe` on Windows. Empty checks `SUBMINER_MPV_PATH`, then `PATH` |
+| `mpv.launchMode`             | `"normal"`        | Window state: `normal`, `maximized`, or `fullscreen`                        |
+| `mpv.profile`                | `""`              | mpv profile to pass. Combined with a launcher `--profile` if both are set   |
+| `mpv.socketPath`             | platform-specific | mpv IPC socket. See the warning under [Config file](#configuration-file)    |
+| `mpv.backend`                | `"auto"`          | Window tracking: `auto`, `hyprland`, `sway`, `x11`, `macos`, `windows`      |
+| `mpv.autoStartSubMiner`      | `true`            | Start SubMiner in the background when mpv loads a file                      |
+| `mpv.pauseUntilOverlayReady` | `true`            | Keep mpv paused until subtitles are ready, up to 30 seconds                 |
+| `mpv.subminerBinaryPath`     | `""`              | SubMiner app path for the plugin. Empty uses the detected path              |
+| `mpv.aniskipEnabled`         | `true`            | Detect intros with AniSkip and show a skip prompt                           |
+| `mpv.aniskipButtonKey`       | `"TAB"`           | mpv key that skips the intro while the prompt is shown                      |
 
-| Option                    | Values                                           | Description                                                |
-| ------------------------- | ------------------------------------------------ | ---------------------------------------------------------- |
-| `discordPresence.enabled` | `true`, `false`                                  | Enable Discord Rich Presence updates (default: `true`)     |
-| `presenceStyle`           | `"default"`, `"meme"`, `"japanese"`, `"minimal"` | Card text preset (default: `"default"`)                    |
-| `updateIntervalMs`        | number                                           | Minimum interval between activity updates in milliseconds  |
-| `debounceMs`              | number                                           | Debounce window for bursty playback events in milliseconds |
+### YouTube playback settings
 
-Setup steps:
+Language and card-media settings for YouTube playback. YouTube always loads a Japanese primary and English secondary track, preferring manual uploads over auto captions. See [YouTube integration](/youtube-integration).
 
-1. Leave `discordPresence.enabled` as `true` or set it explicitly if you previously disabled it.
-2. Optionally set `discordPresence.presenceStyle` to choose a card text preset.
-3. Restart SubMiner.
+| Key                            | Default         | What it does                                                                                 |
+| ------------------------------ | --------------- | -------------------------------------------------------------------------------------------- |
+| `youtube.primarySubLanguages`  | `["ja", "jpn"]` | Languages that count as a valid primary track, also used for local playback                  |
+| `youtube.mediaCache.mode`      | `"direct"`      | `direct` cuts card media from the stream. `background` downloads the video with yt-dlp first |
+| `youtube.mediaCache.maxHeight` | `720`           | Maximum download height in `background` mode. `0` is unlimited                               |
 
-#### Presence style presets
-
-While playing media, the **Details** line always shows the current media title and **State** shows `Playing mm:ss / mm:ss` or `Paused mm:ss / mm:ss`. The preset controls what appears when idle and the tooltip text on images.
-
-| Preset        | Idle details                       | Small image text   | Vibe                                    |
-| ------------- | ---------------------------------- | ------------------ | --------------------------------------- |
-| **`default`** | `Sentence Mining`                  | `日本語学習中`     | Clean, bilingual flair                  |
-| `meme`        | `Mining and crafting (Anki cards)` | `Sentence Mining`  | Minecraft-inspired joke                 |
-| `japanese`    | `文の採掘中`                       | `イマージョン学習` | Fully Japanese                          |
-| `minimal`     | `SubMiner`                         | _(none)_           | Bare essentials, no small image overlay |
-
-All presets use the `subminer-logo` large image with `SubMiner` tooltip. No activity button is shown by default.
-
-Troubleshooting:
-
-- If the card does not appear, verify Discord desktop app is running.
-- If images do not render, confirm asset keys exactly match uploaded Discord asset names.
-- If Discord is closed/not installed/disconnects, SubMiner continues running and quietly skips presence updates.
-
-### Immersion Tracking
-
-Enable or disable local immersion analytics stored in SQLite for mined subtitles and media sessions. This data also powers the stats dashboard:
-
-```json
-{
-  "immersionTracking": {
-    "enabled": true,
-    "dbPath": "",
-    "batchSize": 25,
-    "flushIntervalMs": 500,
-    "queueCap": 1000,
-    "payloadCapBytes": 256,
-    "maintenanceIntervalMs": 86400000,
-    "retentionMode": "preset",
-    "retentionPreset": "balanced",
-    "retention": {
-      "eventsDays": 0,
-      "telemetryDays": 0,
-      "sessionsDays": 0,
-      "dailyRollupsDays": 0,
-      "monthlyRollupsDays": 0,
-      "vacuumIntervalDays": 0
-    },
-    "lifetimeSummaries": {
-      "global": true,
-      "anime": true,
-      "media": true
-    }
-  }
-}
-```
-
-| Option                         | Values                              | Description                                                                                                 |
-| ------------------------------ | ----------------------------------- | ----------------------------------------------------------------------------------------------------------- |
-| `immersionTracking.enabled`    | `true`, `false`                     | Enable immersion tracking. Defaults to `true`.                                                              |
-| `dbPath`                       | string                              | Optional SQLite database path. Leave empty to use default app-data path at `<config dir>/immersion.sqlite`. |
-| `batchSize`                    | integer (`1`-`10000`)               | Buffered writes per transaction. Default `25`.                                                              |
-| `flushIntervalMs`              | integer (`50`-`60000`)              | Maximum queue delay before flush. Default `500ms`.                                                          |
-| `queueCap`                     | integer (`100`-`100000`)            | In-memory queue cap. Overflow drops oldest writes. Default `1000`.                                          |
-| `payloadCapBytes`              | integer (`64`-`8192`)               | Event payload byte cap before truncation marker. Default `256`.                                             |
-| `maintenanceIntervalMs`        | integer (`60000`-`604800000`)       | Prune + rollup maintenance cadence. Default `86400000` (24h).                                               |
-| `retentionMode`                | `preset`,`advanced`                 | Retention mode. `preset` applies `retentionPreset`, `advanced` uses explicit values only. Default `preset`. |
-| `retentionPreset`              | `minimal`,`balanced`,`deep-history` | Retention preset used when `retentionMode = "preset"`. Default `balanced`.                                  |
-| `retention.eventsDays`         | integer (`0`-`3650`)                | Raw event retention window in days. Default `0` (keep all).                                                 |
-| `retention.telemetryDays`      | integer (`0`-`3650`)                | Telemetry retention window in days. Default `0` (keep all).                                                 |
-| `retention.sessionsDays`       | integer (`0`-`3650`)                | Session retention window in days. Default `0` (keep all).                                                   |
-| `retention.dailyRollupsDays`   | integer (`0`-`36500`)               | Daily rollup retention window. Default `0` (keep all).                                                      |
-| `retention.monthlyRollupsDays` | integer (`0`-`36500`)               | Monthly rollup retention window. Default `0` (keep all).                                                    |
-| `retention.vacuumIntervalDays` | integer (`0`-`3650`)                | Minimum spacing between `VACUUM` passes. `0` disables vacuum. Default `0` (disabled).                       |
-| `lifetimeSummaries.global`     | `true`, `false`                     | Maintain global lifetime stats rows (default: `true`).                                                      |
-| `lifetimeSummaries.anime`      | `true`, `false`                     | Maintain per-anime lifetime stats rows (default: `true`).                                                   |
-| `lifetimeSummaries.media`      | `true`, `false`                     | Maintain per-media lifetime stats rows (default: `true`).                                                   |
-
-You can also disable immersion tracking for a single session using:
-
-```bash
-SUBMINER_DISABLE_IMMERSION_TRACKING=1 subminer
-```
-
-When this is set, SubMiner skips immersion-tracker startup and does not initialize or read the immersion SQLite database for that session.
-
-Default behavior keeps raw events, telemetry, sessions, and rollups forever while still maintaining lifetime summary tables and daily/monthly rollups for faster reads. If you later want bounded retention, switch `retentionMode` or set explicit `retention.*` values.
-
-When `dbPath` is blank or omitted, SubMiner writes telemetry and session summaries to the default app-data location:
-
-```text
-<config directory>/immersion.sqlite
-```
-
-Set `dbPath` only if you want to relocate the database (for backup, syncing, or inspection workflows). The database is created when tracking starts for the first time.
-
-See [Immersion Tracking Storage](/immersion-tracking) for schema details, query templates, dashboard access, retention/rollup behavior, backend portability notes, and the dedicated SQLite verification command.
-
-### Stats Dashboard
-
-Configure the local stats UI served from SubMiner and the in-app stats overlay toggle:
-
-```json
-{
-  "stats": {
-    "toggleKey": "Backquote",
-    "markWatchedKey": "KeyW",
-    "serverPort": 6969,
-    "autoStartServer": true,
-    "autoOpenBrowser": false
-  }
-}
-```
-
-| Option            | Values            | Description                                                                                                          |
-| ----------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------- |
-| `stats.toggleKey` | Electron key code | Overlay-local key code used to toggle the stats overlay. Default `Backquote`.                                        |
-| `markWatchedKey`  | Electron key code | Key code to mark the current video as watched and advance to the next playlist entry. Default `KeyW`.                |
-| `serverPort`      | integer           | Localhost port for the browser stats UI. Default `6969`.                                                             |
-| `autoStartServer` | `true`, `false`   | Start the local stats HTTP server automatically once immersion tracking is active. Default `true`.                   |
-| `autoOpenBrowser` | `true`, `false`   | When `subminer stats` starts the server on demand, also open the dashboard in your default browser. Default `false`. |
-
-Usage notes:
-
-- The browser UI is served at `http://127.0.0.1:<serverPort>`.
-- The overlay toggle is local to the focused visible overlay window; it is not registered as a global OS shortcut.
-- The dashboard reads from the same immersion-tracking database, so keep `immersionTracking.enabled` on if you want data to appear.
-- The UI includes Overview, Library, Trends, Vocabulary, Search, and Sessions tabs.
-
-### MPV Launcher
-
-Configure the mpv executable, profile, and window state for SubMiner-managed mpv launches (launcher playback, Windows `--launch-mpv`, and Jellyfin idle mpv startup):
-
-```json
-{
-  "mpv": {
-    "executablePath": "",
-    "launchMode": "normal",
-    "profile": "",
-    "socketPath": "/tmp/subminer-socket",
-    "backend": "auto",
-    "autoStartSubMiner": true,
-    "pauseUntilOverlayReady": true,
-    "subminerBinaryPath": "",
-    "aniskipEnabled": true,
-    "aniskipButtonKey": "TAB"
-  }
-}
-```
-
-| Option                   | Values                                                                      | Description                                                                                                                                                                         |
-| ------------------------ | --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `executablePath`         | string                                                                      | Absolute path to `mpv.exe` for Windows launch flows. Leave empty to auto-discover from `SUBMINER_MPV_PATH` or `PATH` (default `""`)                                                 |
-| `profile`                | string                                                                      | mpv profile name passed as `--profile=<name>`. Leave empty to pass no profile (default `""`)                                                                                        |
-| `launchMode`             | `"normal"` \| `"maximized"` \| `"fullscreen"`                               | Window state when SubMiner spawns mpv (default `"normal"`)                                                                                                                          |
-| `socketPath`             | string                                                                      | mpv IPC socket path used by SubMiner-managed playback and the bundled mpv plugin (platform-dependent default: `/tmp/subminer-socket`, or `\\\\.\\pipe\\subminer-socket` on Windows) |
-| `backend`                | `"auto"` \| `"hyprland"` \| `"sway"` \| `"x11"` \| `"macos"` \| `"windows"` | Window tracking backend passed to the bundled mpv plugin. Auto detects the current platform (default: `"auto"`)                                                                     |
-| `autoStartSubMiner`      | `true`, `false`                                                             | Start SubMiner in the background when SubMiner-managed mpv loads a file (default: `true`)                                                                                           |
-| `pauseUntilOverlayReady` | `true`, `false`                                                             | Pause mpv on visible-overlay auto-start until SubMiner signals subtitle tokenization readiness, with a 30-second fallback (default: `true`)                                         |
-| `subminerBinaryPath`     | string                                                                      | SubMiner app binary path passed to the bundled mpv plugin. Leave empty to use the launcher-detected app path (default: `""`)                                                        |
-| `aniskipEnabled`         | `true`, `false`                                                             | Enable AniSkip intro detection, chapter markers, and the skip-intro key (default: `true`)                                                                                           |
-| `aniskipButtonKey`       | string                                                                      | mpv key used to skip the detected intro while the skip prompt is visible (default: `"TAB"`)                                                                                         |
-
-If `mpv.profile` is configured and the launcher also receives `--profile`, SubMiner passes both as a comma-separated mpv profile list.
-
-Launch mode behavior:
-
-- **`normal`** - mpv opens at its default window size with no extra flags.
-- **`maximized`** - mpv starts maximized via `--window-maximized=yes`, keeping taskbar access.
-- **`fullscreen`** - mpv starts in true fullscreen via `--fullscreen`.
-
-### YouTube Playback Settings
-
-Set defaults used by managed subtitle auto-selection and the `subminer` launcher YouTube flow:
-
-```json
-{
-  "youtube": {
-    "primarySubLanguages": ["ja", "jpn"],
-    "mediaCache": {
-      "mode": "direct",
-      "maxHeight": 720
-    }
-  }
-}
-```
-
-| Option                 | Values                   | Description                                                                                      |
-| ---------------------- | ------------------------ | ------------------------------------------------------------------------------------------------ |
-| `primarySubLanguages`  | string[]                 | Primary subtitle language priority for managed subtitle auto-selection (default `["ja", "jpn"]`) |
-| `mediaCache.mode`      | `direct` \| `background` | YouTube card audio/image extraction mode (default `direct`)                                      |
-| `mediaCache.maxHeight` | number                   | Maximum background cache download height. Set `0` for unlimited (default `720`)                  |
-
-`mediaCache.mode: "direct"` extracts card media from the active YouTube stream URL. `mediaCache.mode: "background"` starts a separate yt-dlp media download after YouTube playback has loaded, including YouTube URLs opened directly in mpv and resolved stream URLs when mpv still exposes the original YouTube playlist entry. Playback and subtitle loading do not wait for that download. Use background mode if direct card media generation hits YouTube `403` errors from expiring stream URLs.
-
-Background cache downloads are capped by `mediaCache.maxHeight`, which defaults to 720p; set it to `0` to let yt-dlp choose the best available height. Downloads use IPv4 and yt-dlp retry flags to reduce YouTube throttling failures. SubMiner announces when the background cache download starts and when the cache is ready, using the configured notification surface; overlay and OSD messages queue until the overlay or mpv is ready. If you mine cards before the cache is ready, SubMiner creates the text fields immediately, queues the audio/image work for those note IDs, shows a status notification, and fills the media fields once the cached file is ready. If the cache download fails, SubMiner shows a failure notification, shows queued-card failure notifications, and clears the pending updates.
-
-Current launcher behavior:
-
-- For YouTube URLs, SubMiner probes subtitle tracks with yt-dlp after mpv bootstrap and binds auto-selected tracks before normal playback resumes.
-- If YouTube/mpv already exposes an authoritative matching subtitle track, SubMiner reuses it; otherwise it downloads and injects only the missing side.
-- SubMiner loads the primary subtitle plus a best-effort secondary subtitle.
-- Playback waits only for primary subtitle readiness; secondary failures do not block playback.
-- Native mpv secondary subtitle rendering stays hidden during this flow so the SubMiner overlay remains the visible secondary subtitle surface.
-- If primary subtitle loading fails, use `Ctrl+Alt+C` to open the subtitle modal and pick a track.
-
-Track selection:
-
-- YouTube auto-selection always targets a Japanese primary track and an English secondary track, preferring manual uploads over auto-generated captions.
-- `youtube.primarySubLanguages` (default `["ja","jpn"]`) defines which loaded track counts as a satisfactory primary for the "primary subtitle missing" notification and for managed local/playlist subtitle selection.
-- Local playback applies these priorities after mpv reports subtitle track metadata, so sidecar/internal mixed sets can override an incorrect initial `sid=auto` pick.
-- Tracks are resolved and loaded before mpv starts; the older launcher mode switch has been removed.
-
-These settings come from `config.jsonc` (or built-in defaults); there are no CLI flags or environment variables for subtitle language selection.
-
-#### YouTube Subtitle Generation (`youtubeSubgen`)
-
-An advanced, template-hidden section for Whisper-based YouTube subtitle generation: `whisperBin`, `whisperModel`, `whisperVadModel`, `whisperThreads` (default `4`), and `fixWithAi` (default `false`), which post-processes generated subtitles through the [Shared AI Provider](#shared-ai-provider) with optional `youtubeSubgen.ai.model` / `systemPrompt` overrides. These keys are accepted in `config.jsonc` but intentionally omitted from the generated template.
+Use `background` if card media fails with YouTube `403` errors. Cards mined before the download finishes get their text right away and their audio and image once the file is ready.
diff --git a/docs-site/demos.md b/docs-site/demos.md
index 4892e1c8..667e1a90 100644
--- a/docs-site/demos.md
+++ b/docs-site/demos.md
@@ -1,28 +1,30 @@
-# Feature Demos
+# Feature demos
 
-Short recordings of SubMiner's key features and integrations from real playback sessions. A few terms you'll see below: _Yomitan_ is the pop-up dictionary used for word lookups, _Jimaku_ is a community subtitle database, _alass_ and _ffsubsync_ are tools that retime subtitles to match the audio, _Jellyfin_ is a self-hosted media server, and a _texthooker_ is a web page that mirrors the current subtitle as selectable text for browser-based tools.
+Short recordings from real playback sessions.
+
+_Yomitan_ is the pop-up dictionary. _Jimaku_ is a community subtitle database. _alass_ and _ffsubsync_ retime subtitles against the audio. _Jellyfin_ is a self-hosted media server. A _texthooker_ is a web page that mirrors the current subtitle as selectable text.
 
 <script setup>
 import { withBase } from 'vitepress';
 
-const v = '20260301-1';
+const v = '20260819-1';
 </script>
 
-## Anki Card Mining & Enrichment
+## Anki card mining and enrichment
 
-Mine vocabulary cards from Yomitan or directly from subtitle lines. SubMiner automatically attaches the sentence, a timing-accurate audio clip, a screenshot, and a translation.
+Mine a card from Yomitan or straight from a subtitle line. SubMiner attaches the sentence, an audio clip cut to the line timing, and a screenshot.
 
 <video controls playsinline preload="metadata" :poster="withBase(`/assets/minecard-poster.jpg?v=${v}`)">
   <source :src="withBase(`/assets/minecard.webm?v=${v}`)" type="video/webm" />
   <source :src="withBase(`/assets/minecard.mp4?v=${v}`)" type="video/mp4" />
   <a :href="withBase(`/assets/minecard.webm?v=${v}`)" target="_blank" rel="noreferrer">
-    <img :src="withBase(`/assets/minecard.webp?v=${v}`)" alt="SubMiner demo Animated fallback" style="width: 100%; height: auto;" />
+    <img :src="withBase(`/assets/minecard.webp?v=${v}`)" alt="Animated demo of mining a card" style="width: 100%; height: auto;" />
   </a>
 </video>
 
-## Subtitle Download & Sync
+## Subtitle download and sync
 
-Search and download subtitles from Jimaku, then retime them with alass or ffsubsync - all from within SubMiner.
+Search Jimaku, download a track, then retime it with alass or ffsubsync without leaving SubMiner.
 
 <!-- <video controls playsinline preload="metadata" :poster="withBase(`/assets/demos/subtitle-sync-poster.jpg?v=${v}`)">
   <source :src="withBase(`/assets/demos/subtitle-sync.webm?v=${v}`)" type="video/webm" />
@@ -32,9 +34,9 @@ Search and download subtitles from Jimaku, then retime them with alass or ffsubs
 ::: info VIDEO COMING SOON
 :::
 
-## Jellyfin Integration
+## Jellyfin integration
 
-Browse your Jellyfin library, cast to devices, and launch playback directly from SubMiner. Watch progress syncs back to your Jellyfin server.
+Browse your Jellyfin library and play from SubMiner, or cast to SubMiner from another Jellyfin client. Watch progress syncs back to the server.
 
 <!-- <video controls playsinline preload="metadata" :poster="withBase(`/assets/demos/jellyfin-poster.jpg?v=${v}`)">
   <source :src="withBase(`/assets/demos/jellyfin.webm?v=${v}`)" type="video/webm" />
@@ -46,7 +48,7 @@ Browse your Jellyfin library, cast to devices, and launch playback directly from
 
 ## Texthooker
 
-Open subtitles in an external texthooker page for use with browser-based tools and extensions alongside the overlay.
+Mirror subtitles to an external texthooker page so browser extensions can read them while the overlay runs.
 
 <!-- <video controls playsinline preload="metadata" :poster="withBase(`/assets/demos/texthooker-poster.jpg?v=${v}`)">
   <source :src="withBase(`/assets/demos/texthooker.webm?v=${v}`)" type="video/webm" />
diff --git a/docs-site/development.md b/docs-site/development.md
index 308456ab..0f90b7a8 100644
--- a/docs-site/development.md
+++ b/docs-site/development.md
@@ -1,12 +1,12 @@
-# Building & Testing
+# Building and testing
 
-For internal architecture/workflow guidance, use `docs/README.md` at the repo root. This page stays focused on contributor-facing build and test commands.
+Build, run, and test SubMiner from source. Architecture and workflow rules live in the repo's internal docs, starting at [`docs/README.md`](https://github.com/ksyasuda/SubMiner/blob/main/docs/README.md). Module boundaries and layering rules are in [`docs/architecture/README.md`](https://github.com/ksyasuda/SubMiner/blob/main/docs/architecture/README.md). The lane-by-lane test guide is [`docs/workflow/verification.md`](https://github.com/ksyasuda/SubMiner/blob/main/docs/workflow/verification.md).
 
 ## Prerequisites
 
-- [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`)
+- [Bun](https://bun.sh), at the version pinned in `package.json`
+- A system `lua` interpreter for the mpv plugin tests (`bun run test:launcher`, `bun run test:env`)
+- macOS only: `bun run build` compiles a Swift window helper. Set `SUBMINER_SKIP_MACOS_HELPER_BUILD=1` to skip it.
 
 ## Setup
 
@@ -16,36 +16,20 @@ cd SubMiner
 make deps
 ```
 
-`make deps` initializes submodules and installs root, `stats/`, and `vendor/texthooker-ui` dependencies. The Yomitan submodule installs its own dependencies on demand during `bun run build`.
+`make deps` initializes submodules and installs dependencies for the root, `stats/`, and `vendor/texthooker-ui`. The Yomitan submodule installs its own dependencies during `bun run build`.
 
-## Building
+## Build
 
 ```bash
-# Main app build
-bun run build
-
-# Platform packages
+bun run build               # app build, including bundled Yomitan from vendor/subminer-yomitan
 bun run build:appimage      # Linux AppImage
 bun run build:mac           # macOS DMG + ZIP (signed)
 bun run build:mac:unsigned  # macOS DMG + ZIP (unsigned)
 bun run build:win           # Windows NSIS installer + ZIP
-
-# Optional launcher artifact only
-make build-launcher
-# output: dist/launcher/subminer
+make build-launcher         # launcher only, output: dist/launcher/subminer
 ```
 
-`bun run build` includes the Yomitan build step. It builds the bundled Chrome extension directly from the `vendor/subminer-yomitan` submodule into `build/yomitan` using Bun.
-
-## Launcher Artifact Workflow
-
-- Source of truth: `launcher/*.ts`
-- Generated output: `dist/launcher/subminer`
-- Do not hand-edit generated launcher output.
-- Repo-root `./subminer` is a stale artifact path and is rejected by verification checks.
-- Install targets (`make install-linux`, `make install-macos`) copy from `dist/launcher/subminer`.
-
-Verify the workflow:
+The launcher source is `launcher/*.ts`. `dist/launcher/subminer` is generated, so never edit it by hand. The repo-root `./subminer` is a stale path and verification rejects it. `make install-linux` and `make install-macos` copy from `dist/launcher/subminer`. To check the launcher build:
 
 ```bash
 make build-launcher
@@ -53,24 +37,21 @@ dist/launcher/subminer --help >/dev/null
 bash scripts/verify-generated-launcher.sh
 ```
 
-## Running Locally
+## Run locally
 
 ```bash
-bun run dev    # builds + launches with --start --dev
-electron . --start --dev --log-level debug   # equivalent Electron launch with verbose logging
-electron . --background                       # tray/background mode, minimal default logging
-make dev-start                                # build + launch via Makefile
-make dev-watch                                # watch TS + renderer and launch Electron (faster edit loop)
-make dev-watch-macos                          # same as dev-watch, forcing --backend macos
+bun run dev                                  # build, then launch with --start --dev
+make dev-watch                               # watch TS + renderer and relaunch Electron
+make dev-watch-macos                         # same, forcing --backend macos
+electron . --start --dev --log-level debug   # verbose launch of an existing build
+electron . --background                      # tray/background mode
 ```
 
 Development and debug launches use a separate `SubMiner-dev` profile so runtime experiments cannot modify the installed app's configuration or Yomitan dictionaries. To intentionally use the production profile for a development launch, set `SUBMINER_USE_PRODUCTION_PROFILE=1`. Use that override only after backing up the profile.
 
-Always launch source builds through `bun run dev` or `bun run electron`. SubMiner refuses to load its profile when the running Electron major differs from the version pinned by the repository.
+Launch source builds through `bun run dev` or `bun run electron`. SubMiner refuses to load its profile when the running Electron major differs from the version pinned by the repository.
 
-For mpv-plugin-driven testing without exporting `SUBMINER_BINARY_PATH` each run, set a one-time
-dev binary path with `mpv.subminerBinaryPath` in your SubMiner config. The launcher injects it into
-the mpv plugin at runtime:
+To test through the mpv plugin without exporting `SUBMINER_BINARY_PATH` each time, point `mpv.subminerBinaryPath` in your config at the dev script. The launcher passes it to the plugin at runtime:
 
 ```json
 {
@@ -80,35 +61,9 @@ the mpv plugin at runtime:
 }
 ```
 
-## Testing
+## Test
 
-Default lanes:
-
-```bash
-bun run test           # alias for test:fast
-bun run test:fast      # full source lanes: src + launcher-unit + scripts + runtime compat
-bun run test:runtime:compat # compiled/runtime compatibility slice only
-bun run test:env       # launcher/plugin + env-sensitive verification
-bun run test:stats     # stats dashboard UI suite
-bun run test:immersion:sqlite # SQLite persistence lane
-bun run test:subtitle  # maintained alass/ffsubsync subtitle surface
-```
-
-Test lane membership is defined once in `scripts/test-lanes.ts` and discovered by
-directory, so new test files join their lane automatically. `scripts/run-test-lane.mjs`
-runs each test file in its own `bun test` process (per-file isolation) so a hanging
-test or leaked global in one file cannot cascade into the rest of the lane; pass
-`--jobs N` to parallelize or `--single-process` for one shared process.
-
-- `bun run test` and `bun run test:fast` cover the full discovered `src/**` suite, launcher unit tests, `scripts/**` tests, and the compiled/runtime compatibility lane.
-- `bun run test:runtime:compat` covers the compiled/runtime slice directly: `ipc`, `anki-jimaku-ipc`, `overlay-manager`, `config-validation`, `startup-config`, and `registry`.
-- `bun run test:env` covers environment-sensitive checks: launcher smoke/plugin verification plus the Bun source SQLite lane.
-- `bun run test:stats` runs the stats dashboard suite under `stats/src/**`.
-- `bun run test:immersion:sqlite` is the reproducible persistence lane when you need real DB-backed SQLite coverage under Bun.
-
-The Bun-managed discovery lanes intentionally exclude a small compiled/runtime-focused set: `src/core/services/ipc.test.ts`, `src/core/services/anki-jimaku-ipc.test.ts`, `src/core/services/overlay-manager.test.ts`, `src/main/config-validation.test.ts`, `src/main/runtime/startup-config.test.ts`, and `src/main/runtime/registry.test.ts`. `bun run test:runtime:compat` keeps them in the standard workflow via `dist/**`.
-
-Suggested local gate before handoff:
+Run the handoff gate before submitting substantial changes:
 
 ```bash
 bun run typecheck
@@ -118,133 +73,111 @@ bun run build
 bun run test:smoke:dist
 ```
 
-If you changed docs in `docs-site/`, also run:
+For smaller changes, start with the cheapest lane that covers what you touched:
+
+| Command                         | Covers                                                                   |
+| ------------------------------- | ------------------------------------------------------------------------ |
+| `bun run test` / `test:fast`    | All `src/**` tests, launcher unit tests, and `scripts/**` tests          |
+| `bun run test:config`           | Config schema, defaults, and `config.example.jsonc` generation           |
+| `bun run test:launcher`         | Launcher tests plus the Lua plugin tests                                 |
+| `bun run test:env`              | Launcher e2e smoke, Lua plugin tests, SQLite immersion tests from source |
+| `bun run test:scripts`          | Build and release scripts under `scripts/**`                             |
+| `bun run test:stats`            | Stats dashboard UI under `stats/src/**`                                  |
+| `bun run test:runtime:compat`   | Compiled-runtime smoke against `dist/` (run `bun run build` first)       |
+| `bun run test:immersion:sqlite` | Compiles, then runs the SQLite-backed immersion tracker tests            |
+| `bun run test:subtitle`         | alass/ffsubsync subtitle sync                                            |
+| `bun run test:docs:kb`          | Internal docs, `AGENTS.md`, and repo skills                              |
+
+Lane membership is defined in `scripts/test-lanes.ts` and discovered by directory, so a new test file joins its lane automatically. Do not hand-list test files in `package.json`. `scripts/run-test-lane.mjs` runs each file in its own `bun test` process, so a hanging test cannot take down the rest of the lane. Pass `--jobs N` to parallelize or `--single-process` to share one process while debugging.
+
+Launcher smoke artifacts go to `.tmp/launcher-smoke`. CI uploads them when the smoke step fails.
+
+## Format
 
 ```bash
-bun run docs:test
-bun run docs:build
+make pretty               # format the maintained source and stats files
+bun run format:check:src  # check the same set without writing
 ```
 
-For production docs routing, run the versioned build:
+`bun run format` runs Prettier over the whole repo. Use it only when you mean to.
+
+## Config generation
+
+```bash
+bun run electron . --generate-config   # write a default config to ~/.config/SubMiner/config.jsonc (%APPDATA%\SubMiner\config.jsonc on Windows)
+bun run generate:config-example        # regenerate config.example.jsonc from the defaults
+```
+
+`make generate-config` and `make generate-example-config` wrap the same commands.
+
+Config definitions are split by domain under `src/config/definitions/`:
+
+- defaults: `defaults-*.ts`
+- option metadata: `options-*.ts`
+- generated template sections and comments: `template-sections.ts`
+
+`src/config/definitions.ts` composes them into the public API (`DEFAULT_CONFIG`, registries, template export). A new key also needs a resolver entry under `src/config/resolve/`, or the resolved config keeps the default.
+
+## Documentation site
+
+The user docs live in `docs-site/` (VitePress).
+
+```bash
+bun --cwd docs-site install
+bun run docs:dev      # dev server at http://localhost:5173
+bun run docs:test     # docs regression tests (links, pinned strings)
+bun run docs:build    # production build into docs-site/.vitepress/dist
+bun run docs:preview  # preview the build at http://localhost:4173
+```
+
+Run `bun run docs:test` and `bun run docs:build` whenever you change `docs-site/`.
+
+Production uses the versioned build:
 
 ```bash
 bun run docs:build:versioned
 ```
 
-The versioned build writes `.tmp/docs-versioned-site` with latest stable docs at `/`, development docs at `/main/`, and stable archives under `/v/<version>/`. Prerelease tags are skipped. Public assets from `docs-site/public/assets` are shared from root `/assets/` so large demo media is not duplicated into every version archive; generated VitePress CSS and JS assets stay under each version route. Stale `.tmp/docs-versioned-archive-cache` generations are pruned after a successful build, and intermediate `.tmp/docs-versioned-build` workspaces are removed.
+It writes `.tmp/docs-versioned-site`: the latest stable docs at `/` with a generated `/versions` page, and development docs at `/main/`. Prerelease tags are skipped. Stable archives under `/v/<version>/` are built once and stored in R2. Without R2 credentials the build skips archive sync, so a local run only produces `/` and `/main/`.
 
-Focused commands:
+The `docs-pages` GitHub Actions workflow uploads that output to Cloudflare Pages with Wrangler. Cloudflare's Git-integration builds are disabled on purpose, so do not re-enable them in the dashboard. `docs-site/README.md` has the full deployment setup.
 
-```bash
-bun run test:config       # Source-level config schema/validation tests
-bun run test:launcher     # Launcher regression tests (config discovery + command routing)
-bun run test:launcher:smoke:src # Launcher e2e smoke: launcher -> mpv IPC -> overlay start/stop wiring
-bun run test:env                # Launcher smoke + Lua plugin gate
-bun run test:src          # Bun-managed maintained src/** discovery lane
-bun run test:launcher:unit:src # Bun-managed maintained launcher unit lane
-bun run test:scripts      # Bun-managed scripts/** test lane
-bun run test:immersion:sqlite:src # Bun source lane
-```
+## Makefile targets
 
-Dist-level tests are now an explicit smoke lane used to validate compiled/runtime assumptions.
+Run `make help` for the full list.
 
-Launcher smoke artifacts are written to `.tmp/launcher-smoke` locally and uploaded by CI/release workflows when the smoke step fails.
+| Target                      | Description                                                  |
+| --------------------------- | ------------------------------------------------------------ |
+| `make deps`                 | Init submodules and install root, stats, and texthooker deps |
+| `make build`                | Build the platform package for the current OS                |
+| `make build-linux`          | Build the Linux package                                      |
+| `make build-macos`          | Build the signed macOS package                               |
+| `make build-macos-unsigned` | Build the unsigned macOS package                             |
+| `make build-launcher`       | Generate the launcher in `dist/launcher/`                    |
+| `make install`              | Install platform artifacts (wrapper, theme, AppImage or app) |
+| `make pretty`               | Run scoped Prettier formatting                               |
+| `make generate-config`      | Generate a default config                                    |
 
-Smoke and optional deep dist commands:
+## Contributor notes
 
-```bash
-bun run build                 # compile dist artifacts
-bun run test:immersion:sqlite # compile + run SQLite-backed immersion tests under Bun
-bun run test:smoke:dist       # explicit smoke scope for compiled runtime
-```
+- See [Architecture](/architecture) for module boundaries and [IPC + runtime contracts](/ipc-contracts) before adding IPC channels.
+- `src/core/services/overlay-manager.ts` owns overlay window and visibility state.
+- In `src/main/` modules, pass simple dependencies as inline objects. Add a helper or adapter only when it adapts, validates, or gets reused.
+- Packaged Linux desktop launches pass `--background` through `build.linux.executableArgs` in `package.json`.
 
-Use `bun run test:immersion:sqlite` when you need real DB-backed coverage for the immersion tracker.
+## Environment variables
 
-## Formatting
-
-Use the scoped formatter for normal app-repo work:
-
-```bash
-make pretty
-bun run format:check:src
-```
-
-- `make pretty` runs the maintained Prettier allowlists (`format:src` and `format:stats`).
-- `bun run format:check:src` checks the same scoped set without writing changes.
-- `bun run format` remains the broad repo-wide Prettier command; use it intentionally.
-
-## Config Generation
-
-```bash
-# Generate default config to ~/.config/SubMiner/config.jsonc (or %APPDATA%\SubMiner\config.jsonc on Windows)
-bun run electron . --generate-config
-
-# Regenerate the repo's config.example.jsonc from centralized defaults
-bun run generate:config-example
-```
-
-Convenience wrappers still exist:
-
-- `make generate-config`
-- `make generate-example-config`
-
-## Documentation Site
-
-The docs site now lives in `docs-site/` inside the main repo.
-
-From the SubMiner app repo:
-
-```bash
-bun --cwd docs-site install
-bun run docs:dev     # Dev server at http://localhost:5173
-bun run docs:build   # Production build into docs-site/.vitepress/dist
-bun run docs:preview # Preview built site at http://localhost:4173
-bun run docs:test    # Docs regression tests
-```
-
-Deployment: production docs are built with `bun run docs:build:versioned` and uploaded directly to Cloudflare Pages by the `docs-pages` GitHub Actions workflow using Wrangler (from `.tmp/docs-versioned-site`). Cloudflare's automatic Git-integration deployments are intentionally disabled - see `docs-site/README.md` for the deployment contract. Do not re-enable Pages build settings in the Cloudflare dashboard.
-
-## Makefile Reference
-
-Run `make help` for a full list of targets. Key ones:
-
-| Target                      | Description                                                       |
-| --------------------------- | ----------------------------------------------------------------- |
-| `make build`                | Build platform package for detected OS                            |
-| `make build-launcher`       | Generate Bun launcher wrapper at `dist/launcher/subminer`         |
-| `make install`              | Install platform artifacts (wrapper, theme, AppImage/app bundle)  |
-| `make deps`                 | Init submodules and install root/stats/texthooker-ui deps         |
-| `make pretty`               | Run scoped Prettier formatting for maintained source/config files |
-| `make generate-config`      | Generate default config from centralized registry                 |
-| `make build-linux`          | Convenience wrapper for Linux packaging                           |
-| `make build-macos`          | Convenience wrapper for signed macOS packaging                    |
-| `make build-macos-unsigned` | Convenience wrapper for unsigned macOS packaging                  |
-
-## Contributor Notes
-
-- To add/change a config default, edit the matching domain file in `src/config/definitions/defaults-*.ts`.
-- To add/change config option metadata, edit the matching domain file in `src/config/definitions/options-*.ts`.
-- To add/change generated config template blocks/comments, update `src/config/definitions/template-sections.ts`.
-- Keep `src/config/definitions.ts` as the composed public API (`DEFAULT_CONFIG`, registries, template export) that wires domain modules together.
-- Overlay window/visibility state is owned by `src/core/services/overlay-manager.ts`.
-- Runtime architecture/module-boundary conventions are summarized in [Architecture](/architecture), with canonical internal guidance in `docs/architecture/README.md` at the repo root.
-- Linux packaged desktop launches pass `--background` using electron-builder `build.linux.executableArgs` in `package.json`.
-- Prefer direct inline deps objects in `src/main/` modules for simple pass-through wiring.
-- Add a helper/adapter service only when it performs meaningful adaptation, validation, or reuse (not identity mapping).
-
-## Environment Variables
-
-| Variable                           | Description                                                                    |
-| ---------------------------------- | ------------------------------------------------------------------------------ |
-| `SUBMINER_APPIMAGE_PATH`           | Override SubMiner app binary path for launcher playback commands               |
-| `SUBMINER_BINARY_PATH`             | Alias for `SUBMINER_APPIMAGE_PATH`                                             |
-| `SUBMINER_ROFI_THEME`              | Override rofi theme path for launcher picker                                   |
-| `SUBMINER_MPV_PLUGIN_PATH`         | Override the mpv plugin directory injected by the launcher                     |
-| `SUBMINER_LOG_LEVEL`               | Override app logger level (`debug`, `info`, `warn`, `error`)                   |
-| `SUBMINER_MPV_LOG`                 | Override mpv/app shared log file path                                          |
-| `SUBMINER_JIMAKU_API_KEY`          | Override Jimaku API key for launcher subtitle downloads                        |
-| `SUBMINER_JIMAKU_API_KEY_COMMAND`  | Command used to resolve Jimaku API key at runtime                              |
-| `SUBMINER_JIMAKU_API_BASE_URL`     | Override Jimaku API base URL                                                   |
-| `SUBMINER_JELLYFIN_ACCESS_TOKEN`   | Override Jellyfin access token (used before stored encrypted session fallback) |
-| `SUBMINER_JELLYFIN_USER_ID`        | Optional Jellyfin user ID override                                             |
-| `SUBMINER_SKIP_MACOS_HELPER_BUILD` | Set to `1` to skip building the macOS helper binary during `bun run build`     |
+| Variable                           | Description                                                      |
+| ---------------------------------- | ---------------------------------------------------------------- |
+| `SUBMINER_APPIMAGE_PATH`           | SubMiner app binary the launcher uses for playback               |
+| `SUBMINER_BINARY_PATH`             | Alias for `SUBMINER_APPIMAGE_PATH`                               |
+| `SUBMINER_ROFI_THEME`              | rofi theme for the launcher picker                               |
+| `SUBMINER_MPV_PLUGIN_PATH`         | mpv plugin directory the launcher injects                        |
+| `SUBMINER_LOG_LEVEL`               | App log level (`debug`, `info`, `warn`, `error`)                 |
+| `SUBMINER_MPV_LOG`                 | Shared mpv/app log file path                                     |
+| `SUBMINER_JIMAKU_API_KEY`          | Jimaku API key for launcher subtitle downloads                   |
+| `SUBMINER_JIMAKU_API_KEY_COMMAND`  | Command that prints the Jimaku API key                           |
+| `SUBMINER_JIMAKU_API_BASE_URL`     | Jimaku API base URL                                              |
+| `SUBMINER_JELLYFIN_ACCESS_TOKEN`   | Jellyfin access token, used before the stored encrypted session  |
+| `SUBMINER_JELLYFIN_USER_ID`        | Jellyfin user ID                                                 |
+| `SUBMINER_SKIP_MACOS_HELPER_BUILD` | Set to `1` to skip the macOS helper build during `bun run build` |
diff --git a/docs-site/docs-sync.test.ts b/docs-site/docs-sync.test.ts
index 35cf7ba9..89065610 100644
--- a/docs-site/docs-sync.test.ts
+++ b/docs-site/docs-sync.test.ts
@@ -8,7 +8,6 @@ const installationContents = readFileSync(new URL('./installation.md', import.me
 const mpvPluginContents = readFileSync(new URL('./mpv-plugin.md', import.meta.url), 'utf8');
 const developmentContents = readFileSync(new URL('./development.md', import.meta.url), 'utf8');
 const changelogContents = readFileSync(new URL('./changelog.md', import.meta.url), 'utf8');
-const docsPackageContents = readFileSync(new URL('./package.json', import.meta.url), 'utf8');
 const ankiIntegrationContents = readFileSync(
   new URL('./anki-integration.md', import.meta.url),
   'utf8',
@@ -57,7 +56,19 @@ test('docs reflect current launcher and release surfaces', () => {
   expect(configurationContents).not.toContain('youtubeSubgen": {\n    "mode"');
   expect(configurationContents).not.toContain('youtubeSubgen.primarySubLanguages');
   expect(configurationContents).toContain('youtube.primarySubLanguages');
-  expect(configurationContents).toContain('### Shared AI Provider');
+  // The AI provider still exists in src/ai and ankiConnect.ai, but it is not
+  // exposed in the Settings window and is not documented for users. Keep the
+  // user-facing docs free of it so nobody configures a hidden surface.
+  expect(configurationContents).not.toContain('Shared AI Provider');
+  expect(configurationContents).not.toContain('ankiConnect.ai');
+  expect(ankiIntegrationContents).not.toContain('AI Translation');
+  // ankiConnect.fields.translation is a LEGACY_HIDDEN_CONFIG_PATHS key, so it
+  // must not be documented as a current setting.
+  expect(configurationContents).not.toContain('fields.translation');
+  expect(ankiIntegrationContents).not.toContain('SelectionText');
+  // fields.audio holds SubMiner's generated sentence audio; examples should not
+  // point it at the field Yomitan uses for word audio.
+  expect(ankiIntegrationContents).not.toContain('"audio": "ExpressionAudio"');
 
   expect(changelogContents).toContain('v0.5.1 (2026-03-09)');
 });
@@ -89,15 +100,6 @@ test('docs state the real secondary-subtitle and Anki field-matching behavior',
   expect(ankiIntegrationContents).toContain('case-insensitively');
 });
 
-test('docs dev server links version navigation to local dev routes', () => {
-  expect(docsPackageContents).toContain('scripts/build-versioned-docs.ts');
-  expect(docsPackageContents).toContain(
-    'SUBMINER_DOCS_VERSION_LINK_ORIGIN=local bun run ../scripts/build-versioned-docs.ts',
-  );
-  expect(docsPackageContents).toContain('SUBMINER_DOCS_VERSION_LINK_ORIGIN=local');
-  expect(docsPackageContents).toContain('SUBMINER_DOCS_VERSION_MANIFEST');
-});
-
 test('docs changelog keeps the current minor release headings aligned with the root changelog', () => {
   const docsHeadings = extractCurrentMinorHeadings(changelogContents);
   expect(docsHeadings.length).toBeGreaterThan(0);
diff --git a/docs-site/functions/v/[[path]].ts b/docs-site/functions/v/[[path]].ts
new file mode 100644
index 00000000..11ff5e7a
--- /dev/null
+++ b/docs-site/functions/v/[[path]].ts
@@ -0,0 +1,212 @@
+// Cloudflare Pages Function serving frozen `/v/<version>/` doc archives from R2.
+// Archives are uploaded by scripts/build-versioned-docs.ts and never ship in the Pages
+// deployment itself, so they do not count toward the Pages file limit. Requires an R2
+// binding named DOCS_ARCHIVES on the Pages project (see docs-site/README.md).
+
+// Minimal slice of the Workers R2 API used here; avoids a workers-types dependency.
+type R2Range = { offset: number; length?: number } | { suffix: number };
+
+type R2ObjectMeta = {
+  size: number;
+  httpEtag: string;
+  range?: R2Range;
+};
+
+type R2ObjectBody = R2ObjectMeta & { body: ReadableStream };
+
+type R2GetOptions = { range?: Headers; onlyIf?: Headers };
+
+export type ArchiveBucket = {
+  get(key: string, options?: R2GetOptions): Promise<R2ObjectMeta | R2ObjectBody | null>;
+};
+
+type ArchiveContext = {
+  request: Request;
+  env: { DOCS_ARCHIVES: ArchiveBucket };
+};
+
+export type ArchiveRoute =
+  | { kind: 'redirect'; location: string; status: 301 | 302 }
+  | { kind: 'lookup'; version: string; keys: string[] }
+  | { kind: 'not-found' };
+
+const CONTENT_TYPES: Record<string, string> = {
+  css: 'text/css; charset=utf-8',
+  gif: 'image/gif',
+  html: 'text/html; charset=utf-8',
+  ico: 'image/x-icon',
+  jpeg: 'image/jpeg',
+  jpg: 'image/jpeg',
+  js: 'text/javascript; charset=utf-8',
+  json: 'application/json; charset=utf-8',
+  jsonc: 'application/json; charset=utf-8',
+  mjs: 'text/javascript; charset=utf-8',
+  mkv: 'video/x-matroska',
+  mp4: 'video/mp4',
+  png: 'image/png',
+  svg: 'image/svg+xml',
+  ttf: 'font/ttf',
+  txt: 'text/plain; charset=utf-8',
+  webm: 'video/webm',
+  webp: 'image/webp',
+  woff: 'font/woff',
+  woff2: 'font/woff2',
+  xml: 'application/xml; charset=utf-8',
+};
+
+function extensionOf(path: string): string | null {
+  const name = path.slice(path.lastIndexOf('/') + 1);
+  const dot = name.lastIndexOf('.');
+  return dot > 0 ? name.slice(dot + 1).toLowerCase() : null;
+}
+
+function contentTypeFor(key: string): string {
+  return CONTENT_TYPES[extensionOf(key) ?? ''] ?? 'application/octet-stream';
+}
+
+// Maps a request path onto candidate R2 keys, mirroring the Pages clean-URL rules the
+// archives were built for (`cleanUrls: true`).
+export function resolveArchiveRoute(pathname: string, search = ''): ArchiveRoute {
+  if (pathname === '/v' || pathname === '/v/') {
+    return { kind: 'redirect', location: '/versions', status: 302 };
+  }
+
+  const match = /^\/v\/(\d+\.\d+\.\d+)(\/.*)?$/.exec(pathname);
+  if (!match) return { kind: 'not-found' };
+
+  const version = match[1]!;
+  const rest = match[2];
+  if (!rest) {
+    return { kind: 'redirect', location: `/v/${version}/${search}`, status: 301 };
+  }
+
+  let decoded: string;
+  try {
+    decoded = decodeURIComponent(rest);
+  } catch {
+    return { kind: 'not-found' };
+  }
+  if (decoded.split('/').some((segment) => segment === '..' || segment === '.')) {
+    return { kind: 'not-found' };
+  }
+
+  const prefix = `v/${version}`;
+  const path = `${prefix}${decoded}`;
+  const keys = decoded.endsWith('/')
+    ? [`${path}index.html`]
+    : extensionOf(decoded)
+      ? [path]
+      : [`${path}.html`, `${path}/index.html`];
+
+  return { kind: 'lookup', version, keys };
+}
+
+function cacheControlFor(key: string): string {
+  // VitePress content-hashes everything it emits under assets/.
+  if (/\/assets\//.test(key) && extensionOf(key) !== 'html') {
+    return 'public, max-age=31536000, immutable';
+  }
+  return 'public, max-age=3600';
+}
+
+function hasBody(object: R2ObjectMeta | R2ObjectBody): object is R2ObjectBody {
+  return 'body' in object && object.body !== undefined;
+}
+
+function contentRange(range: R2Range, size: number): { start: number; end: number } {
+  if ('suffix' in range) {
+    const length = Math.min(range.suffix, size);
+    return { start: size - length, end: size - 1 };
+  }
+  const length = range.length ?? size - range.offset;
+  return { start: range.offset, end: range.offset + length - 1 };
+}
+
+async function respondWithObject(options: {
+  request: Request;
+  bucket: ArchiveBucket;
+  key: string;
+  status: number;
+}): Promise<Response | null> {
+  const { request, bucket, key } = options;
+  // Ranges and conditional requests only make sense for the page that was asked for,
+  // not the 404 fallback.
+  const isRequestedObject = options.status === 200;
+  const wantsRange = isRequestedObject && request.headers.has('range');
+
+  let object: R2ObjectMeta | R2ObjectBody | null;
+  try {
+    object = await bucket.get(key, {
+      range: wantsRange ? request.headers : undefined,
+      onlyIf: isRequestedObject ? request.headers : undefined,
+    });
+  } catch {
+    // R2 rejects unsatisfiable ranges.
+    return new Response(null, { status: 416 });
+  }
+  if (!object) return null;
+
+  const headers = new Headers({
+    'Content-Type': contentTypeFor(key),
+    'Cache-Control': cacheControlFor(key),
+    ETag: object.httpEtag,
+    'Accept-Ranges': 'bytes',
+    'X-Robots-Tag': 'noindex, follow',
+  });
+
+  // R2 returns the object without a body when an If-None-Match/If-Modified-Since
+  // precondition matched.
+  if (!hasBody(object)) {
+    return new Response(null, { status: 304, headers });
+  }
+
+  let status = options.status;
+  if (wantsRange && object.range) {
+    const { start, end } = contentRange(object.range, object.size);
+    status = 206;
+    headers.set('Content-Range', `bytes ${start}-${end}/${object.size}`);
+    headers.set('Content-Length', String(end - start + 1));
+  } else {
+    headers.set('Content-Length', String(object.size));
+  }
+
+  return new Response(request.method === 'HEAD' ? null : object.body, { status, headers });
+}
+
+export async function onRequest({ request, env }: ArchiveContext): Promise<Response> {
+  if (request.method !== 'GET' && request.method !== 'HEAD') {
+    return new Response('Method Not Allowed', { status: 405, headers: { Allow: 'GET, HEAD' } });
+  }
+
+  const url = new URL(request.url);
+  const route = resolveArchiveRoute(url.pathname, url.search);
+
+  if (route.kind === 'redirect') {
+    return Response.redirect(new URL(route.location, url).toString(), route.status);
+  }
+
+  if (route.kind === 'lookup') {
+    for (const key of route.keys) {
+      const response = await respondWithObject({
+        request,
+        bucket: env.DOCS_ARCHIVES,
+        key,
+        status: 200,
+      });
+      if (response) return response;
+    }
+
+    const notFoundPage = await respondWithObject({
+      request,
+      bucket: env.DOCS_ARCHIVES,
+      key: `v/${route.version}/404.html`,
+      status: 404,
+    });
+    if (notFoundPage) return notFoundPage;
+  }
+
+  return new Response('Not Found', {
+    status: 404,
+    headers: { 'Content-Type': 'text/plain; charset=utf-8', 'X-Robots-Tag': 'noindex, follow' },
+  });
+}
diff --git a/docs-site/immersion-tracking.md b/docs-site/immersion-tracking.md
index 1735a2b7..5aa0624a 100644
--- a/docs-site/immersion-tracking.md
+++ b/docs-site/immersion-tracking.md
@@ -1,18 +1,19 @@
-# Immersion Tracking
+# Immersion tracking
 
-SubMiner can log your watching and mining activity to a local SQLite database, then surface it in the built-in stats dashboard. Tracking is enabled by default and can be turned off if you do not want local analytics.
+SubMiner records what you watch and mine in a local SQLite database and shows it in a stats dashboard. Tracking is on by default. Nothing leaves your machine.
 
-"Immersion" here means time spent watching and reading native Japanese content. **All data stays on your computer** - nothing is uploaded anywhere. (SQLite is just a single-file database; you do not need to install or manage anything.)
+## What gets tracked
 
-When enabled, SubMiner records per-session statistics (watch time, subtitle lines seen, words encountered, cards mined) and maintains exact lifetime summary tables plus daily/monthly rollups. You can view that data in SubMiner's stats UI or query the database directly with any SQLite tool.
+- Watch sessions: time watched, subtitle lines seen, words seen, cards mined, pauses and seeks.
+- Every primary subtitle line you see, with its timing, so you can search and mine from it later.
+- Vocabulary and kanji you encounter, with how often and where.
+- Library entries per show and episode, with cover art from AniList (or TMDB for live action) and YouTube channel metadata.
 
-::: tip For most users
-Just leave tracking on and use the built-in [Stats Dashboard](#stats-dashboard). The retention, performance, SQL, and schema sections further down are reference material for advanced users who want to inspect or tune the database - you can safely skip them.
-:::
+An episode counts as watched once you reach 85% of it.
 
-Episode completion for local `watched` state uses the shared `DEFAULT_MIN_WATCH_RATIO` (`85%`) value from `src/shared/watch-threshold.ts`.
+## Setup
 
-## Enabling
+Tracking needs no setup. To turn it off or move the database:
 
 ```jsonc
 {
@@ -23,346 +24,102 @@ Episode completion for local `watched` state uses the shared `DEFAULT_MIN_WATCH_
 }
 ```
 
-- Leave `dbPath` empty to use the default location (`immersion.sqlite` in SubMiner's app-data directory).
-- Set an explicit path to move the database (useful for backups, cloud syncing, or external tools).
-- To share stats and watch history between two machines, use [`subminer sync <host>`](/launcher-script#sync-between-machines) instead of file-level cloud sync — it merges both databases without one side overwriting the other.
+An empty `dbPath` stores `immersion.sqlite` in SubMiner's config directory (`~/.config/SubMiner/` on Linux). Set a path to keep it elsewhere.
 
-## Stats Dashboard
+To share stats and watch history between machines, use [`subminer sync <host>`](/launcher-script#sync-between-machines). It merges both databases. Copying the file with a cloud sync tool makes one side overwrite the other.
 
-The same immersion data powers the stats dashboard.
+## Open the 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 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.
+- In the overlay: focus it and press the `stats.toggleKey` key (Backquote by default).
+- In a browser: run `subminer stats`, then open `http://127.0.0.1:6969` (or your `stats.serverPort`). Set `stats.autoOpenBrowser` to open it automatically.
+- Background server: `subminer stats -b` starts a stats server that keeps running without the launcher attached. `subminer stats -s` stops it. You can still start SubMiner for playback while it runs.
 
-### Dashboard Tabs
+`subminer stats` fails if `immersionTracking.enabled` is `false`. The server only answers on localhost, so reverse proxies and Tailscale Serve URLs do not work.
 
-#### Overview
+## Stats dashboard
 
-Recent sessions, streak calendar, watch-time history, and a tracking snapshot with completed episodes/anime totals.
+### Overview
+
+Recent sessions, a streak calendar, watch-time history, and totals for completed episodes and shows.
 
 ![Stats Overview](/screenshots/stats-overview.png)
 
-#### Library
+### Library
 
-Cover-art library with search and sorting, per-series progress, episode drill-down, and direct links into mined cards.
+Your shows as cover-art cards with search, sorting, per-series progress, and an episode list linking to mined cards. The **All Titles** / **Anime** / **Live Action** / **YouTube** selector filters the grid. YouTube videos are grouped by channel.
 
-Local files and Jellyfin items with detected season numbers are split into season-specific library entries, so `Season 1` and `Season 2` folders do not merge into one show card.
+Seasons get separate cards when a season number is detected. Live-action titles that AniList cannot match are looked up on [TMDB](/configuration#tmdb). If a title gets no match, open it and use **Link to TMDB** to pick one by hand.
 
-When older stats already grouped multiple seasons under one series entry, SubMiner moves parsed episodes into the season-specific entries on startup and rebuilds the affected summaries.
+The same show can end up on several cards when release names disagree. To fix that:
 
-Jellyfin stream URLs are normalized to stable item links before stats titles are shown, so playback query parameters are not displayed in the dashboard.
+- Merge: click **Select**, tick the duplicate cards, choose **Merge Selected**, and pick the entry to keep. Sessions, cards, and watch time move over, and future episodes with those names join the kept entry.
+- Move one episode: hover its row in the episode list and click **→** to assign it to another entry. SubMiner remembers the correction.
+- Suggested merges appear as **Possible duplicate** above the grid. Choose **Review merge** or **Not duplicates**.
 
-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.
+**Delete Entry** in a title's header removes the show with all its episodes, sessions, and lines. You cannot delete the title that is currently playing.
 
 ![Stats Library](/screenshots/stats-library.png)
 
-#### Trends
+### Trends
 
-Grouped into Activity (per-day/month watch time, cards, words, sessions), Cumulative Totals (running totals incl. new words seen and episodes), Efficiency (words/min, cards/hour, lookups per 100 words), Patterns (watch time by day of week and hour), and per-anime Library charts — all with configurable date ranges and grouping.
+Charts for watch time, cards, words, and sessions per day or month, running totals, efficiency (words per minute, cards per hour), and viewing patterns by weekday and hour. Each chart has its own date range and grouping.
 
 ![Stats Trends](/screenshots/stats-trends.png)
 
-#### Sessions
+### Sessions
 
-Expandable session history with new-word activity, cumulative totals, and pause/seek/card markers. Each session row exposes a hover-revealed ↗ button that navigates to the anime media-detail view for that session; pressing the back button there returns to the Sessions tab.
+Session history with new-word activity and pause, seek, and card markers. The **↗** button on a row opens that show's detail view.
 
 ![Stats Sessions](/screenshots/stats-sessions.png)
 
-#### Vocabulary
+### Vocabulary
 
-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.
+Unique words and kanji you have seen, new words per day, frequency rank tables with Hide Known and Hide Kana filters, and a kanji breakdown. Click a word to see every line it appeared in.
+
+- **Exclusions** hides words from every vocabulary view. You can restore them from the same dialog.
+- **Duplicates** cleans up lines repeated by karaoke openings and animated signs (see [Repeated lines](#repeated-lines)).
 
 ![Stats Vocabulary](/screenshots/stats-vocabulary.png)
 
-#### Search
+### Search
 
-Realtime search across tracked primary subtitle lines and media titles. Results show the source media, session, line number, timing, and sentence text. Secondary subtitle text is not shown or searched here because separate subtitle tracks may not line up sentence-for-sentence. Sentence cards can be mined from any result with a valid local source and timing. Word and audio card buttons appear only when the searched word exactly appears in the primary sentence text; matching text is highlighted in the result.
+Searches the primary subtitle lines and titles in your history. **Search by headword** is on by default, so `知らない` also finds inflected forms. Turn it off for exact text matching. Secondary subtitles are not searched.
 
-Stats server config lives under `stats`:
+## Mining from the dashboard
 
-```jsonc
-{
-  "stats": {
-    "toggleKey": "Backquote",
-    "markWatchedKey": "KeyW",
-    "serverPort": 6969,
-    "autoStartServer": true,
-    "autoOpenBrowser": false,
-  },
-}
-```
+Search results and the Vocabulary word panel can create cards from past lines, as long as the source video file is still available:
 
-- `toggleKey` is overlay-local, not a system-wide shortcut.
-- `markWatchedKey` toggles the watched state of the highlighted entry inside the stats dashboard.
-- `serverPort` controls the localhost dashboard URL.
-- `autoStartServer` starts the local stats HTTP server on launch once immersion tracking is active, or reuses the dedicated background stats server when one is already running. Background app launches (`subminer app`) start the stats server immediately, registering it so later launches reuse it instead of starting another one.
-- `autoOpenBrowser` controls whether `subminer stats` launches the dashboard URL in your browser after ensuring the server is running.
-- `subminer stats` forces the dashboard server to start even when `autoStartServer` is `false`.
-- `subminer stats -b` starts or reuses the dedicated background stats daemon and exits after startup acknowledgement.
-- The background stats daemon is separate from the normal SubMiner overlay app, so you can leave it running and still launch SubMiner later to watch or mine from video.
-- `subminer stats -s` stops the dedicated background stats daemon without closing any browser tabs.
-- `subminer stats` fails with an error when `immersionTracking.enabled` is `false`.
-- `subminer stats cleanup` defaults to vocabulary cleanup, repairs stale `headword`, `reading`, and `part_of_speech` values, attempts best-effort MeCab backfill for legacy rows, and removes rows that still fail vocab filtering.
+- **Mine Word**: full Yomitan lookup for the word, plus sentence, audio, and image.
+- **Mine Sentence**: a sentence card with `IsSentenceCard` set, for Lapis and Kiku note types.
+- **Mine Audio**: an audio card with `IsAudioCard` set.
 
-## Mining Cards from the Stats Page
+Word and audio mining appear only when the word occurs in the sentence. All three use your `ankiConnect` deck, note type, fields, and media settings. Anki must be running, and Mine Word needs Yomitan dictionaries.
 
-The Search tab and the Vocabulary tab's word detail panel both mine from subtitle lines in your viewing history. Search matches sentence text and media titles, and **Search by headword** is enabled by default so dictionary-form searches such as `知らない` can find tracked subtitle lines with inflected variants. Turn that toggle off for exact text/title matching only. Each line with a valid source file offers sentence-card mining; word/audio mining is available when the selected word or searched word appears in the sentence:
+## Repeated lines
 
-- **Mine Word** - performs a full Yomitan dictionary lookup for the word (definition, reading, pitch accent, etc.) via a short-lived hidden helper, then enriches the card with sentence audio, a screenshot or animated AVIF clip, the highlighted sentence, and metadata extracted from the source video file. Requires Anki and Yomitan dictionaries to be loaded.
-- **Mine Sentence** - creates a sentence card directly with the `IsSentenceCard` flag set (for Lapis/Kiku workflows), along with audio and image from the source video.
-- **Mine Audio** - creates an audio-only card with the `IsAudioCard` flag, attaching only the sentence audio clip.
+Karaoke openings and animated signs repeat the same text once per frame. SubMiner collapses these as it records, so one lyric is stored once. Stats recorded before that can hold hundreds of copies and skew Top Repeated Words.
 
-All three modes respect your `ankiConnect` config: deck, model, field mappings, media settings (static vs AVIF, quality, dimensions), audio padding, metadata pattern, and tags. Media generation runs in parallel for faster card creation.
-
-Secondary subtitle text (typically English translations) is stored alongside primary subtitles during playback and can be used as the translation field when mining sentence cards from Search or vocabulary occurrences. The Search tab does not use that text for display or matching.
-
-### Word Exclusion List
-
-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:
+To clean them, use **Duplicates** in the Vocabulary tab: pick a time window, **Scan** to preview, then **Clean Up**. Or 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.
+Leave out `--lookback-days` to scan all history. Word and kanji counts are corrected. Watch time and session totals are not changed.
 
-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.
+## Maintenance commands
 
-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.
+| Command                                    | What it does                                                              |
+| ------------------------------------------ | ------------------------------------------------------------------------- |
+| `subminer stats cleanup`                   | Repair word readings and part of speech, drop words that fail the filters |
+| `subminer stats cleanup -l`                | Recompute lifetime totals from episode history, keeping old totals        |
+| `subminer stats cleanup --duplicate-lines` | Collapse repeated karaoke and sign lines (see above)                      |
 
-## Retention Defaults
+`subminer stats rebuild` and `subminer stats backfill` run the same lifetime repair as `cleanup -l`.
 
-By default, SubMiner keeps all retention tables and raw data (`0` means keep all) while continuing daily/monthly rollup maintenance:
+## Retention
 
-| Data type       | Retention    |
-| --------------- | ------------ |
-| Raw events      | 0 (keep all) |
-| Telemetry       | 0 (keep all) |
-| Sessions        | 0 (keep all) |
-| Daily rollups   | 0 (keep all) |
-| Monthly rollups | 0 (keep all) |
+By default SubMiner keeps everything. To limit history, set `immersionTracking.retentionPreset` to `minimal`, `balanced`, or `deep-history`, or set the `immersionTracking.retention.*Days` values yourself (`0` keeps all). Lifetime totals and vocabulary counts are stored separately and stay exact when old sessions are pruned.
 
-Maintenance runs on startup and every 24 hours. Vacuum runs only when `retention.vacuumIntervalDays` is non-zero.
-
-In practice:
-
-- Overview totals read from lifetime summary tables, so all-time watch time/cards/words stay exact even if raw query paths evolve.
-- 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
-
-The tracker is optimized for "keep everything" defaults:
-
-- Exact all-time totals live in dedicated lifetime summary tables (`imm_lifetime_global`, `imm_lifetime_anime`, `imm_lifetime_media`).
-- Ended-session totals are persisted onto `imm_sessions`, so most dashboard reads do not need to rescan raw telemetry.
-- Daily and monthly rollups remain available for chart queries and coarse trend views.
-- Subtitle text is stored once in `imm_subtitle_lines`; subtitle-line event payloads keep compact metadata only.
-- Cover-art binaries are deduplicated through a shared blob store so episodes in the same series do not each carry duplicate image bytes.
-- Hot tables have dedicated indexes for session time ranges, telemetry sample windows, frequency-ranked vocabulary, and cover-art lookup keys.
-
-## Configurable Knobs
-
-All policy options live under `immersionTracking` in your config:
-
-| Option                         | Description                                                        |
-| ------------------------------ | ------------------------------------------------------------------ |
-| `batchSize`                    | Writes per flush batch                                             |
-| `flushIntervalMs`              | Max delay between flushes (default: 500ms)                         |
-| `queueCap`                     | Max queued writes before oldest are dropped                        |
-| `payloadCapBytes`              | Max payload size per write                                         |
-| `maintenanceIntervalMs`        | How often maintenance runs                                         |
-| `retention.eventsDays`         | Raw event retention                                                |
-| `retention.telemetryDays`      | Telemetry retention                                                |
-| `retention.sessionsDays`       | Session retention                                                  |
-| `retention.dailyRollupsDays`   | Daily rollup retention                                             |
-| `retention.monthlyRollupsDays` | Monthly rollup retention                                           |
-| `retention.vacuumIntervalDays` | Minimum spacing between vacuums                                    |
-| `retentionMode`                | `preset` or `advanced`                                             |
-| `retentionPreset`              | `minimal`, `balanced`, or `deep-history` (used by `retentionMode`) |
-| `lifetimeSummaries.global`     | Maintain global lifetime totals                                    |
-| `lifetimeSummaries.anime`      | Maintain per-anime lifetime totals                                 |
-| `lifetimeSummaries.media`      | Maintain per-media lifetime totals                                 |
-
-## Query Templates
-
-### Session timeline
-
-```sql
-SELECT
-  sample_ms,
-  total_watched_ms,
-  active_watched_ms,
-  lines_seen,
-  tokens_seen,
-  cards_mined
-FROM imm_session_telemetry
-WHERE session_id = ?
-ORDER BY sample_ms DESC, telemetry_id DESC
-LIMIT ?;
-```
-
-### Session throughput summary
-
-```sql
-SELECT
-  s.session_id,
-  s.video_id,
-  s.started_at_ms,
-  s.ended_at_ms,
-  COALESCE(s.active_watched_ms, 0) AS active_watched_ms,
-  COALESCE(s.tokens_seen, 0) AS tokens_seen,
-  COALESCE(s.cards_mined, 0) AS cards_mined,
-  CASE
-    WHEN COALESCE(s.active_watched_ms, 0) > 0
-      THEN COALESCE(s.tokens_seen, 0) / (COALESCE(s.active_watched_ms, 0) / 60000.0)
-    ELSE NULL
-  END AS tokens_per_min,
-  CASE
-    WHEN COALESCE(s.active_watched_ms, 0) > 0
-      THEN (COALESCE(s.cards_mined, 0) * 60.0) / (COALESCE(s.active_watched_ms, 0) / 60000.0)
-    ELSE NULL
-  END AS cards_per_hour
-FROM imm_sessions s
-ORDER BY s.started_at_ms DESC
-LIMIT ?;
-```
-
-### Lifetime anime totals
-
-```sql
-SELECT
-  a.anime_id,
-  a.canonical_title,
-  la.total_sessions,
-  la.total_active_ms,
-  la.total_cards,
-  la.total_tokens_seen,
-  la.total_lines_seen,
-  la.first_watched_ms,
-  la.last_watched_ms
-FROM imm_lifetime_anime la
-JOIN imm_anime a ON a.anime_id = la.anime_id
-ORDER BY la.last_watched_ms DESC
-LIMIT ?;
-```
-
-### Daily rollups
-
-```sql
-SELECT
-  rollup_day,
-  video_id,
-  total_sessions,
-  total_active_min,
-  total_lines_seen,
-  total_tokens_seen,
-  total_cards,
-  cards_per_hour,
-  tokens_per_min,
-  lookup_hit_rate
-FROM imm_daily_rollups
-ORDER BY rollup_day DESC, video_id DESC
-LIMIT ?;
-```
-
-### Monthly rollups
-
-```sql
-SELECT
-  rollup_month,
-  video_id,
-  total_sessions,
-  total_active_min,
-  total_lines_seen,
-  total_tokens_seen,
-  total_cards
-FROM imm_monthly_rollups
-ORDER BY rollup_month DESC, video_id DESC
-LIMIT ?;
-```
-
-## Technical Details
-
-- Write path is asynchronous and queue-backed. Hot paths (subtitle parsing, render, token flows) enqueue telemetry and never await SQLite writes.
-- Queue overflow policy: drop oldest queued writes, keep newest.
-- SQLite tunings: `journal_mode=WAL`, `synchronous=NORMAL`, `foreign_keys=ON`, `busy_timeout=2500`, bounded WAL growth via `journal_size_limit`.
-- Maintenance executes `PRAGMA optimize` after periodic cleanup.
-- Rollups run incrementally from the last processed telemetry sample; startup performs a one-time bootstrap pass.
-- Cover-art blobs are deduplicated into `imm_cover_art_blobs` and referenced from `imm_media_art`.
-- Large-table reads are index-backed for `sample_ms`, session time windows, frequency-ranked words/kanji, and cover-art identity lookups.
-- Workload-dependent tuning knobs remain at defaults unless you change them: `cache_size`, `mmap_size`, `temp_store`, `auto_vacuum`.
-
-### Schema (v18)
-
-The exact schema version lives in `SCHEMA_VERSION` (`src/core/services/immersion-tracker/types.ts`) and is recorded in the `imm_schema_version` table.
-
-Core tables:
-
-- `imm_videos` - video key/title/source metadata
-- `imm_anime` - anime/series metadata referenced by videos and lifetime tables
-- `imm_sessions` - session UUID, video reference, timing/status, final denormalized totals
-- `imm_session_telemetry` - high-frequency session aggregates over time
-- `imm_session_events` - event stream with compact numeric event types
-- `imm_subtitle_lines` - persisted subtitle text and timing per session/video
-- `imm_youtube_videos` - YouTube video/channel metadata for tracked videos
-
-Lifetime summary tables:
-
-- `imm_lifetime_global`
-- `imm_lifetime_anime`
-- `imm_lifetime_media`
-- `imm_lifetime_applied_sessions`
-
-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:
-
-- `imm_words(id, headword, word, reading, part_of_speech, pos1, pos2, pos3, first_seen, last_seen, frequency, frequency_rank)` with `UNIQUE(headword, word, reading)`
-- `imm_kanji(id, kanji, first_seen, last_seen, frequency)`
-- `imm_word_line_occurrences` / `imm_kanji_line_occurrences` - word/kanji ↔ subtitle-line occurrence links
-- `imm_stats_excluded_words` - vocabulary exclusion list managed from the dashboard
-
-Media-art tables:
-
-- `imm_media_art` - per-video cover metadata plus shared blob reference
-- `imm_cover_art_blobs` - deduplicated image bytes keyed by blob hash
+See [Immersion tracking](/configuration#immersion-tracking) and [Stats dashboard](/configuration#stats-dashboard) in the config reference for every option and default.
diff --git a/docs-site/index.md b/docs-site/index.md
index 2454169c..8279e3dc 100644
--- a/docs-site/index.md
+++ b/docs-site/index.md
@@ -7,7 +7,7 @@ titleTemplate: Immersion Mining Workflow for MPV
 hero:
   name: SubMiner
   text: Immersion Mining for MPV
-  tagline: Watch media, mine vocabulary, and craft anki cards without leaving the scene.
+  tagline: Watch, look up a word, and get an Anki card with audio and a screenshot. Without pausing your show.
   image:
     src: /assets/SubMiner.png
     alt: SubMiner logo
@@ -24,63 +24,63 @@ features:
       src: /assets/mpv.svg
       alt: mpv icon
     title: Built for mpv
-    details: Tracks subtitles via mpv IPC in real time. Launch with the wrapper script or the mpv plugin - no external bridge needed.
+    details: Reads subtitle state over mpv's IPC socket. Launch with the wrapper script or the mpv plugin. There is no separate bridge process to run.
     link: /usage
     linkText: How it works
   - icon:
       src: /assets/yomitan-icon.svg
       alt: Yomitan logo
     title: Bundled Yomitan
-    details: Ships with a built-in Yomitan instance for instant word lookups and context-aware card creation directly from subtitle text.
+    details: A Yomitan instance is bundled and preconfigured. Hover a word in the subtitle overlay to look it up and mine it.
     link: /mining-workflow
     linkText: Mining workflow
   - icon:
       src: /assets/anki-card.svg
       alt: Anki card icon
-    title: Anki Card Enrichment
-    details: Auto-fills card fields with sentence, audio clip, screenshot, and translation so you can focus on learning.
+    title: Anki card enrichment
+    details: New cards get the subtitle line, an audio clip cut to the line timing, and a screenshot from that moment.
     link: /anki-integration
     linkText: Anki integration
   - icon:
       src: /assets/highlight.svg
       alt: Highlight icon
-    title: Reading Annotations
-    details: N+1 targeting, character-name matching, frequency highlighting, and JLPT tagging - all layered on subtitle text in real time.
+    title: Reading annotations
+    details: N+1 targeting, character-name matching, frequency highlighting, and JLPT tagging, drawn onto the subtitle line as it plays.
     link: /subtitle-annotations
     linkText: Annotation details
   - icon:
       src: /assets/video.svg
       alt: Video playback icon
-    title: YouTube Playback
-    details: Play YouTube URLs or ytsearch targets directly - SubMiner automatically selects and loads subtitles for the video.
+    title: YouTube playback
+    details: Pass a YouTube URL or a ytsearch target. SubMiner picks a subtitle track for the video and loads it.
     link: /usage#youtube-playback
     linkText: YouTube playback
   - icon:
       src: /assets/jellyfin.svg
       alt: Jellyfin icon
-    title: Jellyfin Integration
-    details: Browse your Jellyfin library, pick media interactively, and play through mpv with full subtitle and mining support.
+    title: Jellyfin integration
+    details: Browse your Jellyfin library from the overlay and play a title through mpv. Subtitles and mining work the same as with local files.
     link: /jellyfin-integration
     linkText: Jellyfin setup
   - icon:
       src: /assets/subtitle-download.svg
       alt: Subtitle download icon
-    title: Subtitle Download & Sync
-    details: Search and pull subtitles from Jimaku, then retime subtitles with alass or ffsubsync - all from the overlay.
+    title: Subtitle download and sync
+    details: Search Jimaku or TsukiHime and download a track, then retime it with alass or ffsubsync. Both run from the overlay.
     link: /jimaku-integration
     linkText: Jimaku integration
   - icon:
       src: /assets/tokenization.svg
       alt: Tracking chart icon
-    title: Stats Dashboard
-    details: Browse session history, streak calendars, vocabulary frequency, and per-series progress in a local dashboard - then mine cards straight from your viewing history.
+    title: Stats dashboard
+    details: A local dashboard with session history, streak calendars, word frequency, and per-series progress. You can mine cards from lines you already watched.
     link: /immersion-tracking
     linkText: Dashboard & tracking
   - icon:
       src: /assets/cross-platform.svg
       alt: Cross-platform icon
-    title: Cross-Platform
-    details: Runs on Linux (Hyprland, Sway, X11), macOS, and Windows with compositor-aware window positioning and platform-native integration.
+    title: Cross-platform
+    details: Runs on Linux (Hyprland, Sway, X11), macOS, and Windows. Overlay positioning is handled per compositor rather than assuming one window manager.
     link: /installation
     linkText: Platform setup
 ---
@@ -88,7 +88,7 @@ features:
 <script setup>
 import { withBase } from 'vitepress';
 
-const demoAssetVersion = '20260223-2';
+const demoAssetVersion = '20260819-1';
 </script>
 
 <div class="landing-shell">
@@ -98,38 +98,38 @@ const demoAssetVersion = '20260223-2';
       <div class="workflow-step" style="animation-delay: 0ms">
         <div class="step-number">01</div>
         <div class="step-title">Start</div>
-        <div class="step-desc">Launch with the wrapper or existing mpv setup and keep subtitles in sync.</div>
+        <div class="step-desc">Launch through the wrapper, or from an mpv setup you already have.</div>
       </div>
       <div class="workflow-connector" aria-hidden="true"></div>
       <div class="workflow-step" style="animation-delay: 60ms">
         <div class="step-number">02</div>
         <div class="step-title">Lookup</div>
-        <div class="step-desc">Hover a token in the interactive overlay, then trigger Yomitan lookup to open context.</div>
+        <div class="step-desc">Hover a token in the overlay to open the Yomitan popup for that word.</div>
       </div>
       <div class="workflow-connector" aria-hidden="true"></div>
       <div class="workflow-step" style="animation-delay: 120ms">
         <div class="step-number">03</div>
         <div class="step-title">Mine</div>
-        <div class="step-desc">Create cards from Yomitan or mine sentence cards directly from subtitle lines.</div>
+        <div class="step-desc">Add the word from Yomitan, or mine the whole line as a sentence card.</div>
       </div>
       <div class="workflow-connector" aria-hidden="true"></div>
       <div class="workflow-step" style="animation-delay: 180ms">
         <div class="step-number">04</div>
         <div class="step-title">Enrich</div>
-        <div class="step-desc">Automatically attach timing-accurate audio, sentence text, and visual evidence.</div>
+        <div class="step-desc">SubMiner fills in the audio clip, the sentence, and a screenshot from that moment.</div>
       </div>
       <div class="workflow-connector" aria-hidden="true"></div>
       <div class="workflow-step" style="animation-delay: 240ms">
         <div class="step-number">05</div>
         <div class="step-title">Track</div>
-        <div class="step-desc">Open the stats dashboard to review sessions, vocabulary trends, and mine cards from past viewing history.</div>
+        <div class="step-desc">Review past sessions and word trends, and mine anything you missed the first time.</div>
       </div>
     </div>
   </section>
 
   <section class="demo-section">
     <h2>See it in action</h2>
-    <p>Subtitles, lookup flow, and card enrichment from a real playback session.</p>
+    <p>Recorded from an actual playback session: subtitle hover, lookup, and the card that comes out the other end.</p>
     <div class="demo-window">
       <div class="demo-window__bar">
         <span class="demo-window__dot"></span>
diff --git a/docs-site/installation.md b/docs-site/installation.md
index 10278a37..20ac38d5 100644
--- a/docs-site/installation.md
+++ b/docs-site/installation.md
@@ -1,46 +1,41 @@
 # Installation
 
-SubMiner is a desktop app that draws an interactive layer - an **overlay** - on top of the [mpv](https://mpv.io) video player. As you watch native Japanese media, you can click or hover any word in the subtitles to look it up, then turn it into an Anki flashcard without pausing to switch apps. Building flashcards from real content you're watching is called **sentence mining**, and it's what SubMiner is built for. It bundles its own copy of **Yomitan** (a pop-up dictionary) and talks to **AnkiConnect** (an add-on that lets other programs add cards to Anki) so cards get filled in automatically.
+SubMiner draws an interactive overlay on top of the [mpv](https://mpv.io) video player. While you watch Japanese media, you hover a word in the subtitles to look it up, then turn it into an Anki card without leaving the video.
 
-Three steps to get started:
+Building cards from what you watch is called **sentence mining**. SubMiner bundles its own copy of **Yomitan** (a pop-up dictionary) and talks to **AnkiConnect** (an Anki add-on that lets other programs create cards), so it can fill in the sentence, audio, and screenshot for you.
 
-1. **Install requirements** - mpv and a few optional extras
-2. **Install SubMiner** - from the AUR, or download from GitHub Releases
-3. **Launch the app** - first-run setup walks you through dictionaries, the launcher, and everything else
+Getting started takes three steps:
 
-## 1. Install Requirements
+1. Install mpv and the optional extras you want.
+2. Install SubMiner.
+3. Launch it and follow the first-run setup.
 
-Only **mpv** is strictly required to run SubMiner. Everything else enhances the experience but is optional.
+## 1. Install requirements
 
-Several entries below exist only for the `subminer` command-line launcher, which is Linux and macOS only. On Windows you launch playback with the **SubMiner mpv** shortcut instead, so you can ignore those rows.
+Only mpv is required. Install ffmpeg too unless you are fine with cards that have no audio or screenshot.
 
-| Dependency           | Status      | Platforms    | What it does                                                                                                                                                   |
-| -------------------- | ----------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| mpv                  | Required    | All          | The video player SubMiner overlays on. Must support `--input-ipc-server`.                                                                                      |
-| ffmpeg               | Recommended | All          | Audio extraction and screenshots for Anki cards. Without it SubMiner still runs, but media fields will be empty.                                               |
-| MeCab + mecab-ipadic | Recommended | All          | Part-of-speech filtering for more precise N+1, JLPT, and frequency annotations. Without it annotations still render, but POS-based filtering is less accurate. |
-| yt-dlp               | Optional    | All          | YouTube playback and subtitle extraction.                                                                                                                      |
-| xz                   | Optional    | All          | Required for TsukiHime subtitle downloads (subtitles are served xz-compressed). Preinstalled on most Linux distros; not present on Windows by default.         |
-| guessit              | Optional    | All          | Better AniSkip title/season/episode parsing.                                                                                                                   |
-| alass                | Optional    | All          | Subtitle sync engine (preferred). Disabled without alass or ffsubsync.                                                                                         |
-| ffsubsync            | Optional    | All          | Audio-based subtitle sync engine. Disabled without alass or ffsubsync.                                                                                         |
-| fzf                  | Optional    | Linux, macOS | Terminal-based video picker in the `subminer` launcher.                                                                                                        |
-| rofi                 | Optional    | Linux        | GUI-based video picker in the `subminer` launcher.                                                                                                             |
-| chafa                | Optional    | Linux, macOS | Thumbnail previews in the fzf picker.                                                                                                                          |
-| ffmpegthumbnailer    | Optional    | Linux, macOS | Video thumbnail generation for the pickers.                                                                                                                    |
-| fuse2                | Required    | Linux        | Needed to run the AppImage.                                                                                                                                    |
+| Dependency               | Needed for                                                                                  | Platforms    |
+| ------------------------ | ------------------------------------------------------------------------------------------- | ------------ |
+| mpv                      | Required. The player SubMiner draws over.                                                   | All          |
+| fuse2                    | Required to run the AppImage.                                                               | Linux        |
+| ffmpeg                   | Recommended. Audio clips and screenshots on cards. Without it those fields stay empty.      | All          |
+| MeCab + mecab-ipadic     | Recommended. More accurate N+1, JLPT, and frequency highlighting.                           | All          |
+| yt-dlp                   | YouTube playback.                                                                           | All          |
+| xz                       | [TsukiHime](/tsukihime-integration) subtitle downloads. Most Linux distros already have it. | All          |
+| guessit                  | Better title, season, and episode detection for [AniSkip](/aniskip-integration).            | All          |
+| alass or ffsubsync       | Subtitle syncing. You need at least one to use it.                                          | All          |
+| fzf, rofi                | The file pickers in the `subminer` command (rofi is Linux only).                            | Linux, macOS |
+| chafa, ffmpegthumbnailer | Thumbnail previews in the pickers.                                                          | Linux, macOS |
+
+To generate Japanese subtitles from audio, you also need whisper.cpp. See [Subtitle generation](/subtitle-generation).
 
 ### Linux
 
-**Window backend** - you need one of these depending on your compositor:
+SubMiner needs to track the mpv window, and how it does that depends on your desktop:
 
-- **Hyprland** - native Wayland support (uses `hyprctl`)
-- **Sway** - native Wayland support (uses `swaymsg`)
-- **X11 / Xwayland** - for X11 sessions or any other Wayland compositor (uses `xdotool` and `xwininfo`)
-
-::: warning Wayland support is compositor-specific
-Wayland has no universal API for window positioning - each compositor exposes its own IPC, so SubMiner needs a dedicated backend per compositor. Only Hyprland and Sway have native Wayland backends. If you run a different Wayland compositor (GNOME, KDE Plasma, river, etc.), both mpv **and** SubMiner must run under X11 or Xwayland. The `subminer` launcher handles this automatically when `--backend x11` is set or the X11 backend is auto-detected.
-:::
+- **Hyprland**: supported natively through `hyprctl`.
+- **Sway**: supported natively through `swaymsg`.
+- **Anything else** (X11, GNOME, KDE Plasma, other Wayland compositors): mpv and SubMiner must run under X11 or Xwayland. Install `xdotool` and `xwininfo`. The `subminer` command picks the X11 backend automatically, or you can force it with `--backend x11`.
 
 <details>
 <summary><b>Arch Linux</b></summary>
@@ -51,9 +46,9 @@ sudo pacman -S --needed mpv ffmpeg
 sudo pacman -S --needed mecab mecab-ipadic
 # Optional
 sudo pacman -S --needed yt-dlp fzf rofi chafa ffmpegthumbnailer
-# Optional: subtitle sync (at least one needed for subtitle syncing)
+# Optional: subtitle sync (install at least one)
 paru -S --needed alass python-ffsubsync
-# X11 / Xwayland (required for non-Hyprland/Sway compositors)
+# Only for desktops other than Hyprland or Sway
 sudo pacman -S --needed xdotool xorg-xwininfo
 ```
 
@@ -68,11 +63,11 @@ sudo apt install mpv ffmpeg
 sudo apt install mecab libmecab-dev mecab-ipadic-utf8
 # Optional
 sudo apt install yt-dlp fzf rofi chafa ffmpegthumbnailer
-# X11 / Xwayland (required for non-Hyprland/Sway compositors)
+# Only for desktops other than Hyprland or Sway
 sudo apt install xdotool x11-utils
 # Optional: subtitle sync
 pip install ffsubsync
-# alass is not in apt - install via cargo: cargo install alass-cli
+cargo install alass-cli
 ```
 
 </details>
@@ -86,18 +81,18 @@ sudo dnf install mpv ffmpeg
 sudo dnf install mecab mecab-ipadic
 # Optional
 sudo dnf install yt-dlp fzf rofi chafa ffmpegthumbnailer
-# X11 / Xwayland (required for non-Hyprland/Sway compositors)
+# Only for desktops other than Hyprland or Sway
 sudo dnf install xdotool xorg-x11-utils
 # Optional: subtitle sync
 pip install ffsubsync
-# alass: cargo install alass-cli
+cargo install alass-cli
 ```
 
 </details>
 
 ### macOS
 
-macOS 11 (Big Sur) or later. Accessibility permission - the macOS setting that lets one app observe and position another app's windows - is required so the overlay can follow the mpv window (see [step 2](#macos-dmg)).
+You need macOS 11 (Big Sur) or later.
 
 ```bash
 brew install mpv ffmpeg
@@ -110,166 +105,101 @@ brew install alass
 pip install ffsubsync
 ```
 
+`mecab` must be on your `PATH` when SubMiner starts. Homebrew puts it in `/opt/homebrew/bin` on Apple Silicon and `/usr/local/bin` on Intel.
+
 ### Windows
 
-Windows 10 or later. No compositor tools or window helpers are needed - native window tracking is built in.
-
-You need **mpv** (required) and **ffmpeg** (strongly recommended, for card audio and screenshots), and both must be on your `PATH`.
-
-::: tip What is PATH?
-`PATH` is the list of folders Windows searches when a program asks to run another program by name. SubMiner runs `mpv` and `ffmpeg` by name, so if their folders are not on `PATH`, SubMiner cannot find them even though they are installed. The routes below mostly handle `PATH` for you; the manual route explains how to add a folder yourself.
-:::
-
-You can install these with a package manager or by hand. Coverage differs, so pick based on what you need:
-
-| Dependency       | winget          | Scoop         |
-| ---------------- | --------------- | ------------- |
-| mpv (required)   | `shinchiro.mpv` | `extras/mpv`  |
-| ffmpeg           | `Gyan.FFmpeg`   | `main/ffmpeg` |
-| yt-dlp (YouTube) | `yt-dlp.yt-dlp` | `main/yt-dlp` |
-| xz (TsukiHime)   | not packaged    | `main/xz`     |
-
-Use **winget** if you want Microsoft's first-party tool and don't need TsukiHime subtitle downloads. Use **Scoop** if you want one package manager to cover everything, since it is the only one that also packages `xz`.
-
-#### Recommended: winget
-
-[winget](https://learn.microsoft.com/windows/package-manager/winget/) is Microsoft's own package manager and ships with Windows 11 and current Windows 10 (it comes with **App Installer** from the Microsoft Store). In **PowerShell** or **Command Prompt**:
+You need Windows 10 or later. Install mpv and ffmpeg with [winget](https://learn.microsoft.com/windows/package-manager/winget/), which ships with Windows 11 and current Windows 10. In PowerShell or Command Prompt:
 
 ```powershell
 winget install shinchiro.mpv
 winget install Gyan.FFmpeg
+winget install yt-dlp.yt-dlp   # optional, for YouTube
 ```
 
-Close and reopen your terminal, then check that both are found:
+Close and reopen the terminal, then check both commands work:
 
 ```powershell
 mpv --version
 ffmpeg -version
 ```
 
-`ffmpeg` is installed as a portable package, so winget links it into a folder that is already on your `PATH` and it should work right away.
-
-`mpv` uses a regular installer, and depending on the version it may **not** add itself to `PATH`. If `mpv --version` says `not recognized`, you have two easy options:
-
-- Note where it installed (usually `%LOCALAPPDATA%\Programs\mpv`) and add that folder to `PATH` using the manual steps below, or
-- Skip `PATH` entirely and set `mpv.executablePath` to the full path of `mpv.exe` during first-run setup.
-
-Once `mpv --version` works, or you have the full path to `mpv.exe` ready, continue to [step 2](#_2-install-subminer).
+ffmpeg must be on `PATH`, because SubMiner runs it by name to make card audio and screenshots. mpv does not have to be. If `mpv --version` says `not recognized`, find `mpv.exe` (usually in `%LOCALAPPDATA%\Programs\mpv`) and either add that folder to `PATH` or enter the full path to `mpv.exe` during first-run setup (`mpv.executablePath`).
 
 <details>
-<summary><b>Alternative: Scoop (covers every dependency, no admin rights)</b></summary>
+<summary><b>Alternative: Scoop (no admin rights, includes xz)</b></summary>
 
-[Scoop](https://scoop.sh) installs into your user profile, needs no administrator prompt, and always puts commands on `PATH`. It is the only Windows package manager that carries all of SubMiner's optional dependencies, including `xz`, so it is the best choice if you want a single tool to manage everything.
+[Scoop](https://scoop.sh) installs into your user profile and always adds commands to `PATH`. It is the only Windows package manager that also packages `xz`, which [TsukiHime](/tsukihime-integration) downloads need.
 
 ```powershell
-# One-time Scoop setup (skip if you already have it)
+# One-time Scoop setup
 Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
 Invoke-RestMethod -Uri https://get.scoop.sh | Invoke-Expression
 
-# mpv lives in the "extras" bucket; everything else is in "main"
 scoop bucket add extras
 scoop install extras/mpv main/ffmpeg
-
-# Optional: yt-dlp for YouTube playback, xz for TsukiHime subtitle downloads
+# Optional
 scoop install main/yt-dlp main/xz
 ```
 
-Close and reopen your terminal, then verify with `mpv --version` and `ffmpeg -version`.
-
 </details>
 
 <details>
-<summary><b>Manual install (download the zips yourself)</b></summary>
+<summary><b>Alternative: manual download</b></summary>
 
-1. Download mpv from [mpv.io/installation](https://mpv.io/installation/) (the Windows builds link) and ffmpeg from [ffmpeg.org/download.html](https://ffmpeg.org/download.html).
-2. Unzip each one somewhere permanent, for example `C:\Tools\mpv` and `C:\Tools\ffmpeg`. Note the folder that actually contains `mpv.exe` and the one containing `ffmpeg.exe` (for ffmpeg this is usually a `bin` subfolder).
-3. Press `Win`, type **Edit the system environment variables**, and open it. Click **Environment Variables…**, select **Path** under **User variables**, click **Edit…**, then use **New** to add each of those two folders. Confirm with **OK** on every dialog. Microsoft documents this in more detail under [environment variables](https://learn.microsoft.com/windows/deployment/usmt/usmt-recognized-environment-variables).
-4. Close and reopen your terminal, since `PATH` changes only apply to newly opened windows. Then check:
+1. Download mpv from [mpv.io/installation](https://mpv.io/installation/) and ffmpeg from [ffmpeg.org/download.html](https://ffmpeg.org/download.html).
+2. Unzip each into a permanent folder, for example `C:\Tools\mpv` and `C:\Tools\ffmpeg`. Find the folders that contain `mpv.exe` and `ffmpeg.exe` (for ffmpeg this is usually `bin`).
+3. Press `Win`, search for **Edit the system environment variables**, and open it. Click **Environment Variables**, select **Path** under **User variables**, click **Edit**, and add both folders with **New**.
+4. Open a new terminal and run `mpv --version` and `ffmpeg -version`. If either says `not recognized`, the folder you added does not contain the `.exe`.
 
-```powershell
-mpv --version
-ffmpeg -version
-```
-
-If you see `not recognized as the name of a cmdlet`, the folder you added is not the one holding the `.exe`. Reopen the Path editor and double-check.
-
-::: tip mpv can skip PATH, ffmpeg cannot
-If you would rather not edit `PATH` for mpv, set `mpv.executablePath` to the full path of `mpv.exe` during first-run setup instead.
-
-There is no equivalent setting for ffmpeg: SubMiner invokes it by bare name when generating card audio and screenshots, so ffmpeg has to be on `PATH`. Without it, cards are still created but their audio and image fields come out empty. (`subsync.ffmpeg_path` only affects subtitle sync, not card media.)
-:::
+For `xz` without Scoop, download [XZ Utils](https://tukaani.org/xz/) and add its folder to `PATH` the same way.
 
 </details>
 
-**Optional extras:** [MeCab for Windows](https://taku910.github.io/mecab/#download) with the UTF-8 dictionary improves annotation accuracy; it is not in any package manager, so install it from that page. `xz` is needed only for [TsukiHime](/tsukihime-integration) subtitle downloads and is not packaged by winget or Chocolatey, so use `scoop install main/xz` or download [XZ Utils](https://tukaani.org/xz/) and add its folder to `PATH`.
-
-The `subminer` command-line launcher and its picker tools (`fzf`, `rofi`, `chafa`, `ffmpegthumbnailer`) are Linux/macOS only; on Windows you use the **SubMiner mpv** shortcut instead.
+For more accurate highlighting, install [MeCab for Windows](https://taku910.github.io/mecab/#download) with the UTF-8 dictionary. The fzf and rofi pickers do not apply on Windows.
 
 ## 2. Install SubMiner
 
 ### Arch Linux (AUR) {#arch-aur}
 
-Install [`subminer-bin`](https://aur.archlinux.org/packages/subminer-bin) from the AUR. The package includes the SubMiner AppImage and the `subminer` launcher.
+Install [`subminer-bin`](https://aur.archlinux.org/packages/subminer-bin). It includes the AppImage and the `subminer` command.
 
 ```bash
 paru -S subminer-bin
 ```
 
-Or manually:
-
-```bash
-git clone https://aur.archlinux.org/subminer-bin.git
-cd subminer-bin
-makepkg -si
-```
-
 ### Linux (AppImage) {#linux-appimage}
 
-Download the latest AppImage from [GitHub Releases](https://github.com/ksyasuda/SubMiner/releases/latest):
-
 ```bash
 mkdir -p ~/.local/bin
 wget https://github.com/ksyasuda/SubMiner/releases/latest/download/SubMiner.AppImage -O ~/.local/bin/SubMiner.AppImage
 chmod +x ~/.local/bin/SubMiner.AppImage
 ```
 
-::: tip Launcher install is optional
-First-run setup can install [Bun](https://bun.sh) and the `subminer` command-line launcher for you automatically. You don't need to download the launcher separately.
-
-If you prefer to install it manually, see [manual launcher install](#manual-launcher-install-linux).
-:::
+First-run setup can install the `subminer` command for you.
 
 ### macOS (DMG) {#macos-dmg}
 
-Download the DMG from [GitHub Releases](https://github.com/ksyasuda/SubMiner/releases/latest), open it, and drag `SubMiner.app` into `/Applications`. A ZIP artifact is also available as a fallback.
+1. Download the DMG from [GitHub Releases](https://github.com/ksyasuda/SubMiner/releases/latest), open it, and drag `SubMiner.app` into `/Applications`.
+2. If macOS blocks the app on first launch, right-click it and choose **Open**, or run:
 
-**Gatekeeper:** If macOS blocks SubMiner on first launch, right-click the app and select **Open** to bypass the warning. Alternatively:
+   ```bash
+   xattr -d com.apple.quarantine /Applications/SubMiner.app
+   ```
 
-```bash
-xattr -d com.apple.quarantine /Applications/SubMiner.app
-```
+3. Open **System Settings > Privacy & Security > Accessibility** and enable SubMiner (add it if it is missing). The overlay cannot follow the mpv window without this.
 
-**Accessibility permission:** Grant accessibility permission so the overlay can track the mpv window:
+First-run setup can install the `subminer` command for you.
 
-1. Open **System Settings** → **Privacy & Security** → **Accessibility**
-2. Enable SubMiner in the list (add it if it does not appear)
+### Windows (installer) {#windows-installer}
 
-::: tip Launcher install is optional
-First-run setup can install [Bun](https://bun.sh) and the `subminer` command-line launcher for you automatically. You don't need to download the launcher separately.
+Download from [GitHub Releases](https://github.com/ksyasuda/SubMiner/releases/latest):
 
-If you prefer to install it manually, see [manual launcher install](#manual-launcher-install-macos).
-:::
+- `SubMiner-<version>.exe`: the installer. Use this one.
+- `SubMiner-<version>-win.zip`: portable version.
+- `subminer.cmd`: optional terminal command (setup can install it for you).
 
-### Windows (Installer) {#windows-installer}
-
-Download the latest installer from [GitHub Releases](https://github.com/ksyasuda/SubMiner/releases/latest):
-
-- `SubMiner-<version>.exe` - installer (recommended)
-- `SubMiner-<version>-win.zip` - portable fallback
-
-Make sure `mpv.exe` is on your `PATH`, or set `mpv.executablePath` in the config during first-run setup.
-
-### From Source
+### From source
 
 <details>
 <summary><b>Linux</b></summary>
@@ -279,12 +209,10 @@ git clone --recurse-submodules https://github.com/ksyasuda/SubMiner.git
 cd SubMiner
 make deps
 bun run build
-
-# Optional: build AppImage
-bun run build:appimage
+bun run build:appimage   # optional: package an AppImage
 ```
 
-Bundled Yomitan is built during `bun run build`.
+Building from source needs [Bun](https://bun.sh) installed.
 
 </details>
 
@@ -298,7 +226,7 @@ make deps
 make build-macos
 ```
 
-The built app will be in the `release` directory (`.dmg` and `.zip`). For unsigned local builds: `bun run build:mac:unsigned`.
+The `.dmg` and `.zip` land in `release/`. For an unsigned local build, run `bun run build:mac:unsigned`.
 
 </details>
 
@@ -321,122 +249,80 @@ bun run build:win
 
 </details>
 
-## 3. Launch & First-Run Setup
+## 3. Launch and first-run setup
 
-Launch SubMiner and the setup wizard will open automatically:
+Start SubMiner. The setup window opens on first launch.
 
-```bash
-# Linux (AUR install)
-subminer app --setup
+- **Linux (AUR)**: `subminer app --setup`
+- **Linux (AppImage)**: `~/.local/bin/SubMiner.AppImage --setup`
+- **macOS**: open `SubMiner.app` from `/Applications`
+- **Windows**: run SubMiner from the Start menu
 
-# Linux (AppImage directly)
-~/.local/bin/SubMiner.AppImage --setup
+Setup walks you through:
 
-# macOS - launch SubMiner.app from /Applications, or:
-subminer app --setup
-```
+1. **Config file.** Created at `~/.config/SubMiner/config.jsonc` (Linux and macOS) or `%APPDATA%\SubMiner\config.jsonc` (Windows).
+2. **Yomitan dictionaries.** Import at least one dictionary, or lookups will not work. SubMiner's Yomitan is separate from any Yomitan in your browser.
+3. **The `subminer` command** (optional). Setup installs it into a folder already on your `PATH`. If there is none on Linux or macOS, it uses `~/.local/bin` and shows the `export PATH=...` line to add to your shell config. On Windows it adds `%LOCALAPPDATA%\SubMiner\bin` to your user `PATH`.
+4. **SubMiner mpv shortcut** (Windows only). A Start menu or desktop shortcut that opens mpv with SubMiner attached.
 
-On **Windows**, just run `SubMiner.exe` - the setup wizard opens automatically on first launch.
+**Finish setup** unlocks once the config exists and at least one dictionary is imported. To reopen setup later, run `subminer app --setup`.
 
-The setup wizard walks you through:
-
-- **Config file** - auto-created at `~/.config/SubMiner/config.jsonc` (Linux/macOS) or `%APPDATA%\SubMiner\config.jsonc` (Windows)
-- **Yomitan dictionaries** - import at least one dictionary so word lookups work
-- **Bun + `subminer` launcher** _(optional)_ - installs the command-line launcher into a writable PATH directory
-- **Windows shortcut** _(Windows only)_ - create a `SubMiner mpv` Start Menu/Desktop shortcut
-
-The `Finish setup` button requires a config file and at least one Yomitan dictionary. Bun and the launcher are optional and never block setup completion.
-
-> [!TIP]
-> You can re-open the setup wizard at any time with `subminer app --setup` or `SubMiner.AppImage --setup`.
-
-### Play a Video
-
-Once setup is complete:
+### Play a video
 
 ```bash
 subminer video.mkv
 ```
 
-You should see the overlay appear over mpv. If subtitles are loaded, they will appear as interactive text in the overlay.
+On Windows, double-click the **SubMiner mpv** shortcut or drag a video onto it.
 
-On **Windows**, the recommended way to play video is with the **SubMiner mpv** shortcut created during setup - double-click it, or drag a video file onto it.
+The overlay appears over mpv, and the subtitle text becomes hoverable. See [Usage](/usage) for everyday use.
 
-### Verify Setup
-
-Run the built-in diagnostic to confirm everything is working:
+### Check your setup
 
 ```bash
 subminer doctor
 ```
 
-This checks for the app binary, mpv, ffmpeg, yt-dlp, fzf, rofi, your config file, and the mpv socket path. Only the app binary and mpv are hard failures; the rest are reported as optional. Fix any hard failures before continuing.
+This checks for the SubMiner app, mpv, ffmpeg, yt-dlp, fzf, rofi, your config file, and the mpv socket path. Only a missing app or mpv counts as a failure. The rest are reported as optional.
 
-## Anki Setup (Recommended)
+## Anki setup
 
-If you plan to mine Anki cards:
+To create cards:
 
-1. Install [Anki](https://apps.ankiweb.net/)
-2. Install [AnkiConnect](https://ankiweb.net/shared/info/2055492159) - open Anki → **Tools → Add-ons → Get Add-ons** → enter code `2055492159`
-3. Restart Anki and keep it running while using SubMiner
+1. Install [Anki](https://apps.ankiweb.net/).
+2. In Anki, open **Tools > Add-ons > Get Add-ons** and enter `2055492159` to install [AnkiConnect](https://ankiweb.net/shared/info/2055492159).
+3. Restart Anki. Keep it open while you use SubMiner.
 
-AnkiConnect listens on `http://127.0.0.1:8765` by default. SubMiner connects automatically with no extra config needed.
-
-For enrichment configuration (sentence, audio, screenshot fields), see [Anki Integration](/anki-integration).
+SubMiner connects to AnkiConnect at its default address with no extra setup. To choose your deck and card fields, see [Anki integration](/anki-integration).
 
 ## Updates
 
 ```bash
 subminer -u
-# or
-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.
+The tray menu's **Check for Updates** also installs updates on Linux, macOS, and Windows. If the AppImage sits in a folder you cannot write to, SubMiner prints the command to run instead of asking for admin rights.
 
-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.
+If you installed from the AUR, update through your package manager instead.
 
-`subminer -u` also performs the AppImage, launcher, and managed support-asset updates directly from the launcher process, which is useful when SubMiner is not currently running.
+## Launching mpv yourself
 
-## How It All Fits Together
+The `subminer` command and the Windows shortcut start mpv with the IPC socket SubMiner needs. If you start mpv another way, add this option or the overlay starts without subtitles:
 
-SubMiner is an overlay that sits on top of mpv. It connects to mpv through an IPC socket, renders subtitles as interactive text using a bundled Yomitan dictionary engine, and optionally creates Anki flashcards via AnkiConnect.
+```bash
+--input-ipc-server=/tmp/subminer-socket      # Linux and macOS
+--input-ipc-server=\\.\pipe\subminer-socket  # Windows
+```
 
-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.
+SubMiner loads its mpv plugin automatically, so there is nothing else to install. See [mpv plugin](/mpv-plugin) for the in-player keybindings.
 
-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.
+## Manual launcher install
 
-## Platform Notes
-
-### macOS
-
-**MeCab paths (Homebrew):**
-
-- Apple Silicon (M1/M2): `/opt/homebrew/bin/mecab`
-- Intel: `/usr/local/bin/mecab`
-
-Ensure `mecab` is available on your PATH when launching SubMiner.
-
-**Fullscreen:** The overlay should appear correctly in fullscreen. If you encounter issues, check that accessibility permissions are granted.
-
-### Windows
-
-- The **SubMiner mpv** shortcut is the recommended way to launch playback. It starts `mpv.exe` with the right IPC socket and subtitle defaults.
-- First-run setup adds only `%LOCALAPPDATA%\SubMiner\bin` to the HKCU user PATH. It does not add `SubMiner.exe` to PATH.
-- IPC socket on Windows is `\\.\pipe\subminer-socket` - do not use `/tmp/subminer-socket`.
-- Config is stored at `%APPDATA%\SubMiner\config.jsonc`.
-
-## Manual Launcher Install
-
-The `subminer` launcher uses a [Bun](https://bun.sh) shebang, so Bun must be installed. First-run setup can handle this automatically, but if you prefer to do it yourself:
+Use these if you skipped the launcher during setup. The launcher finds SubMiner in the usual install locations. For a custom location, set `SUBMINER_BINARY_PATH` to the app executable.
 
 ### Linux {#manual-launcher-install-linux}
 
 ```bash
-# Install Bun
-curl -fsSL https://bun.sh/install | bash
-
-# Download the launcher
 wget https://github.com/ksyasuda/SubMiner/releases/latest/download/subminer -O ~/.local/bin/subminer
 chmod +x ~/.local/bin/subminer
 ```
@@ -444,31 +330,16 @@ chmod +x ~/.local/bin/subminer
 ### macOS {#manual-launcher-install-macos}
 
 ```bash
-# Install Bun
-curl -fsSL https://bun.sh/install | bash
-
-# Download the launcher
 sudo curl -fSL https://github.com/ksyasuda/SubMiner/releases/latest/download/subminer -o /usr/local/bin/subminer
 sudo chmod +x /usr/local/bin/subminer
 ```
 
-## Optional Extras
+### Windows {#manual-launcher-install-windows}
 
-### Linux Support Assets
+Download `subminer.cmd` from [GitHub Releases](https://github.com/ksyasuda/SubMiner/releases/latest) and put it in a folder on your user `PATH`.
 
-SubMiner ships the Linux rofi theme plus the launcher-managed runtime plugin copy in `subminer-assets.tar.gz`:
+## Bundled Bun runtime {#bundled-bun-runtime}
 
-```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/plugin
-cp -R /tmp/plugin/subminer ~/.local/share/SubMiner/plugin/subminer
-```
+The `subminer` command runs on a copy of [Bun](https://bun.sh) 1.3.5 that ships inside the app, so you do not need to install Bun. Bun is MIT licensed and statically links JavaScriptCore (LGPL 2.0) and TinyCC (LGPL 2.1). License texts and a `SOURCE.md` ship in the app under `resources/bun/licenses`, and each GitHub release includes `bun-v1.3.5-source.tar.gz` with the matching sources.
 
-`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.
-
-Override the theme path with `SUBMINER_ROFI_THEME=/absolute/path/to/theme.rasi`.
-
-Next: [Usage](/usage) - learn about the `subminer` wrapper, keybindings, and YouTube playback.
+Next: [Usage](/usage).
diff --git a/docs-site/ipc-contracts.md b/docs-site/ipc-contracts.md
index 44ce3a62..bcd6e5d7 100644
--- a/docs-site/ipc-contracts.md
+++ b/docs-site/ipc-contracts.md
@@ -1,12 +1,12 @@
-# IPC + Runtime Contracts
+# IPC + runtime contracts
 
-SubMiner's Electron app runs two isolated processes - main and renderer - that can only communicate through IPC channels. This boundary is intentional: the renderer is an untrusted surface (it loads Yomitan, renders user-controlled subtitle text, and runs in a Chromium sandbox), so every message crossing the bridge passes through a validation layer before it can reach domain logic.
+The Electron main and renderer processes talk only through IPC channels. The renderer is an untrusted surface: it loads Yomitan and renders subtitle text SubMiner did not write. Every payload that crosses the bridge goes through a validator before domain code sees it.
 
-The contract system enforces this by making channel names, payload shapes, and validators co-located and co-evolved. A change to any IPC surface touches the contract, the validator, the preload bridge, and the handler in the same commit - drift between any of those layers is treated as a bug.
+Channel names, payload validators, the preload bridge, and the handler change together. When you touch an IPC surface, update all four in the same commit.
 
-## Message Flow
+## Message flow
 
-Renderer-initiated calls (`invoke`) pass through four boundaries before reaching a service. Fire-and-forget messages (`send`) follow the same path but skip the response leg. Malformed payloads are caught at the validator and never reach domain code.
+Renderer calls pass through the preload bridge, the main-process handler, and a validator before they reach a service. Malformed payloads stop at the validator.
 
 ```mermaid
 flowchart TB
@@ -36,12 +36,18 @@ flowchart TB
   style E fill:#ed8796,stroke:#494d64,color:#24273a,stroke-width:1.5px
 ```
 
-## Runtime Sockets
+`IPC_CHANNELS` in `src/shared/ipc/contracts.ts` groups channels by pattern:
 
-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.
+- `request`: invoke channels. The renderer awaits a result, for example lookups, config reads, and mining actions. Invalid payloads return a structured failure such as `{ ok: false, ... }` instead of throwing.
+- `command`: fire-and-forget sends, for example focus events, UI state hints, and position updates. Invalid payloads are dropped.
+- `event`: messages pushed from main to the renderer.
 
-- **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.
+## Runtime sockets
+
+The bridge above lives inside the Electron app. Separate OS sockets connect the app to mpv and to the launcher and plugin. They carry no renderer payloads and do not go through the contract and validator layer.
+
+- **mpv IPC socket**: `/tmp/subminer-socket`, or `\\.\pipe\subminer-socket` on Windows. mpv creates it with `--input-ipc-server`. The app's `MpvIpcClient` sends JSON commands here and observes playback and subtitle properties.
+- **App control socket**: `subminer-control-<uid>-<hash>.sock` in the temp directory, or `\\.\pipe\subminer-control-<hash>` on Windows. The launcher and plugin send CLI-style commands (`--start`, `--show-visible-overlay`, `--texthooker`) to a running app here. It also routes a second `subminer` invocation into the existing instance.
 
 ```mermaid
 flowchart LR
@@ -65,60 +71,44 @@ flowchart LR
   style MpvProc fill:#363a4f,stroke:#494d64,color:#cad3f5
 ```
 
-How these sockets are established during launch is covered in [Playback Startup Flow](./architecture#playback-startup-flow).
+[Playback startup flow](./architecture#playback-startup-flow) shows when each socket comes up during a launch.
 
-## Core Surfaces
+## Core files
 
-| 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`          | Channel names and payload types, shared by both processes                           |
+| `src/shared/ipc/validators.ts`         | Runtime payload parsers and type guards                                             |
+| `src/preload.ts`                       | Typed renderer API; only approved channels are exposed                              |
+| `src/core/services/ipc.ts`             | Registers overlay handlers and validates payloads before calling domain logic       |
+| `src/core/services/anki-jimaku-ipc.ts` | Same boundary for Anki and Jimaku operations                                        |
+| `src/main/ipc-runtime.ts`              | Builds handler dependencies (via `src/main/dependencies.ts`) and registers handlers |
+| `src/main/cli-runtime.ts`              | Handles commands from the launcher or mpv plugin, not the renderer                  |
 
-## Contract Rules
+## Contract rules
 
-These rules exist to prevent a class of bugs where the renderer and main process silently disagree about message shapes - which surfaces as undefined fields, swallowed errors, or state corruption.
+- **Use the shared constants.** Take channel names from `contracts.ts`, never string literals.
+- **Validate before handling.** Every renderer payload goes through `validators.ts` before domain logic.
+- **Return structured failures.** Invoke handlers return `{ ok: false, ... }` on failure instead of throwing, so the renderer can tell success from failure without try/catch.
+- **Keep payloads narrow.** Send only what the handler needs, not whole state objects.
+- **Keep handlers thin.** Validate, delegate to a service or composer, return. Route shared state changes through the transition helpers in `src/main/state.ts`.
 
-- **Use shared constants.** Channel names come from `contracts.ts`, never ad-hoc literal strings. This makes channels greppable and refactor-safe.
-- **Validate before handling.** Every `invoke` payload passes through `validators.ts` before reaching domain logic. This catches shape drift at the boundary instead of deep inside a service.
-- **Return structured failures.** Handlers return `{ ok: false, error: string }` on failure rather than throwing. The renderer can always distinguish success from failure without try/catch.
-- **Keep payloads narrow.** Send only what the handler needs. Avoid passing entire state objects across the bridge - it couples the renderer to internal main-process structure.
-- **Co-evolve all layers.** When a payload shape changes, update `contracts.ts`, `validators.ts`, `preload.ts`, and the handler in the same commit. Partial updates are treated as bugs.
-
-## Two Message Patterns
-
-**Invoke (request/response):** The renderer calls a typed bridge method and awaits a result. The main process validates the payload, runs the handler, and returns a structured response. Used for operations where the renderer needs a result - lookups, config reads, mining actions.
-
-**Fire-and-forget (send):** The renderer sends a message with no response. The main process validates and handles it silently. Malformed payloads are dropped. Used for notifications where the renderer doesn't need confirmation - UI state hints, focus events, position updates.
-
-## Add a New IPC Action
+## Add a new IPC action
 
 1. Add the channel constant in `src/shared/ipc/contracts.ts`.
-2. Add or extend the payload validator in `src/shared/ipc/validators.ts`.
+2. Add or extend the validator in `src/shared/ipc/validators.ts`.
 3. Expose a typed bridge method in `src/preload.ts`.
-4. Register the handler in `src/main/ipc-runtime.ts` (or the relevant domain runtime module).
-5. Add tests for both valid and malformed payload cases in `src/core/services/*`.
-6. Update renderer tests when behavior or state transitions change.
-
-## Runtime State Notes
-
-- Prefer runtime/domain composition via `src/main/runtime/composers/*` and `src/main/runtime/domains/*`. IPC handlers should delegate to composers rather than containing orchestration logic.
-- Route shared mutable state updates through transition helpers in `src/main/state.ts` for migrated domains. Direct mutation from IPC handlers bypasses invariant checks.
-- Keep IPC handlers thin - they validate, delegate, and return. Business logic belongs in services.
+4. Register the handler in `src/core/services/ipc.ts` (or `anki-jimaku-ipc.ts`), and supply any new dependency through `src/main/ipc-runtime.ts`.
+5. Test valid and malformed payloads in `src/core/services/*`.
+6. Update renderer tests if behavior or state transitions change.
 
 ## Troubleshooting
 
-- **Unknown payload in handler:** The validator is not being applied before the handler runs. Check that the channel is routed through `ipc-runtime.ts` with validation, not registered directly.
-- **Renderer invoke fails:** Verify the preload bridge method exists and matches the channel constant. Check that the handler is registered and returning (not throwing).
-- **Contract drift:** When invoke calls return unexpected shapes, compare the shared contract, validator, preload bridge, and main handler signatures side by side. One of them was updated without the others.
+- **Handler receives an unexpected payload:** the validator is not applied. Check that the channel is registered through the IPC service with validation, not directly.
+- **Renderer invoke fails:** check that the preload method exists, uses the right channel constant, and that the handler is registered and returns instead of throwing.
+- **Invoke returns an unexpected shape:** compare the contract, validator, preload method, and handler side by side. One of them changed without the others.
 
-## Related Docs
+## Related docs
 
 - [Architecture](/architecture)
-- [Development](/development)
-- [Configuration](/configuration)
-- [Troubleshooting](/troubleshooting)
+- [Building and testing](/development)
diff --git a/docs-site/jellyfin-integration.md b/docs-site/jellyfin-integration.md
index 064cdc18..2c66c07c 100644
--- a/docs-site/jellyfin-integration.md
+++ b/docs-site/jellyfin-integration.md
@@ -1,118 +1,60 @@
-# Jellyfin Integration
+# Jellyfin integration
 
-[Jellyfin](https://jellyfin.org) is a free, self-hosted media server - think of it as your own private streaming service for video you own. If you keep your anime on a Jellyfin server, SubMiner can play episodes through mpv with the full mining overlay.
+If your anime lives on a [Jellyfin](https://jellyfin.org) server, SubMiner can appear as a cast target in any Jellyfin client. Cast an episode and it plays in SubMiner's mpv with the overlay and Yomitan lookup attached.
 
-::: tip Who needs this?
-This page is only relevant if you already run (or have access to) a Jellyfin server. If you watch local files or YouTube, you can skip it. The in-app setup window (`subminer jellyfin`) is the easiest starting point.
-:::
+## Setup
 
-SubMiner can act as a **cast-to-device target** for Jellyfin (similar to jellyfin-mpv-shim). Sign in once, turn on discovery, and SubMiner shows up in the "Play on…" / cast menu of any Jellyfin app - web, phone, or TV. Pick an episode, cast it to SubMiner, and it plays in SubMiner's mpv window with the full overlay and Yomitan click-to-lookup.
+You need a Jellyfin server (Jellyfin 12 is supported) and your username and password.
 
-This is the recommended way to use Jellyfin with SubMiner. A terminal-only option is covered in [Launcher playback](#launcher-playback) at the end.
+1. Start SubMiner and leave it in the system tray.
+2. Open the tray menu and click **Configure Jellyfin**. You can also run `subminer jellyfin`.
+3. Enter the **Server URL** (for example `http://127.0.0.1:8096`), **Username**, and **Password**, then click **Login**.
 
-## Requirements
+SubMiner stores an encrypted session token, not your password, and turns the integration on. Reopen the same window to switch servers or log out.
 
-- A Jellyfin server plus your username and password
-- SubMiner installed and running (see [Installation](/installation))
-- On Linux, the session token is stored with `gnome-libsecret` by default
+## Casting from Jellyfin
 
-## Quick start
+After you sign in, SubMiner connects to Jellyfin at startup and shows up in the cast ("Play on") menu under your computer's hostname. To connect for the current session only, tick **Jellyfin Discovery** in the tray menu.
 
-### 1. Start SubMiner
+1. In the Jellyfin web or mobile app, start playing an episode.
+2. Open the cast menu and pick your computer.
 
-Launch SubMiner so it's running in the system tray.
+SubMiner starts mpv if it is not already running. Pause, seek, stop, and track changes in the Jellyfin app are mirrored in mpv, and watch progress syncs back to Jellyfin. Playback resumes from Jellyfin's saved position.
 
-### 2. Sign in to your server
+SubMiner selects a Japanese subtitle track automatically and resets mpv's subtitle delay to zero. It direct-plays files when it can and asks Jellyfin to transcode the rest.
 
-Open the tray menu and click **Configure Jellyfin**. In the window that opens, enter your **Server URL** (for example `http://127.0.0.1:8096`), **Username**, and **Password**, then click **Login**.
+On Windows, casting finds mpv through `mpv.executablePath`, then `SUBMINER_MPV_PATH`, then `PATH`. An invalid `mpv.executablePath` stops mpv from starting.
 
-On success, SubMiner:
+## Playing from the terminal
 
-- saves an encrypted session token - your password is never stored,
-- turns the Jellyfin integration on, and
-- remembers the server and username for next time.
+The launcher can browse your libraries and play an item without a Jellyfin client:
 
-Reopen this window any time to switch servers or **Logout**.
-
-### 3. Turn on discovery
-
-Discovery is what makes SubMiner appear as a cast target. Two ways to enable it:
-
-- **For the current session** - open the tray menu and tick **Jellyfin Discovery**. (This item appears once you've signed in.)
-- **Automatically on every launch** - already on by default. After your first sign-in, SubMiner auto-connects to Jellyfin at startup, so the cast target is ready without touching the tray. You can change this under [Settings](#settings).
-
-### 4. Cast from any Jellyfin app
-
-In the Jellyfin web UI or mobile app, start playing something, open the **cast / "Play on"** menu, and pick your device - SubMiner appears there named after your computer's hostname. Playback opens in SubMiner.
-
-From then on, pause / resume / seek / stop and audio or subtitle track changes you make in the Jellyfin app are mirrored in SubMiner, and your watch progress syncs back to Jellyfin (now-playing and resume position).
-
-## What happens during playback
-
-- **mpv launches automatically.** If mpv isn't already running when you cast, SubMiner starts it with SubMiner defaults and the bundled mpv plugin, so keybindings work right away.
-- **The overlay is managed by SubMiner,** so your configured `subtitleStyle` controls how subtitles look. Use the [overlay-toggle shortcut](/shortcuts) to hide it for a session.
-- **Resume works.** If Jellyfin has a saved position for the item, SubMiner seeks there on load.
-- **Direct play first.** When the source allows it and the container is in your direct-play allowlist, SubMiner streams the original file; otherwise it requests a transcoded stream from Jellyfin.
-- **Japanese subtitles are auto-selected,** preferring Jellyfin's default and embedded tracks over external sidecar files when several match.
-- **Subtitle timing is corrected when possible.** SubMiner removes Jellyfin's server-selected subtitle stream from the mpv load URL, suppresses the mpv plugin's one-shot subtitle auto-selection and overlay auto-start for managed Jellyfin loads, stages downloaded subtitle tracks without letting mpv auto-switch between tracks, then selects the Japanese track once after applying any saved or inferred timing delay. When Jellyfin provides both Japanese and English subtitle files, SubMiner compares their cue timelines and applies a global delay if one track is clearly offset. Manual delay shifts you make with SubMiner's adjacent-cue controls are saved per item and subtitle track, then restored the next time you select that track.
-
-## Settings
-
-All Jellyfin options live under **Settings → Integrations → Jellyfin** (open settings from the tray's **Open SubMiner Settings**). The ones that matter for casting:
-
-| Setting                         | Default | What it does                                                                                                          |
-| ------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------- |
-| **Enabled**                     | Off     | Turns the Jellyfin integration on. Switched on for you when you sign in.                                              |
-| **Server Url**                  | -       | Your Jellyfin server. Filled in when you sign in.                                                                     |
-| **Remote Control Enabled**      | On      | Lets SubMiner act as a cast target.                                                                                   |
-| **Remote Control Auto Connect** | On      | Connects to Jellyfin at startup so discovery is automatic. Turn off if you'd rather start it from the tray each time. |
-| **Auto Announce**               | Off     | Re-broadcasts visibility on connect. Enable if your device is slow to appear in the cast menu.                        |
-
-Prefer editing the config file? The same keys live under `jellyfin` in `config.jsonc`:
-
-```jsonc
-{
-  "jellyfin": {
-    "enabled": true,
-    "serverUrl": "http://127.0.0.1:8096",
-    "remoteControlEnabled": true,
-    "remoteControlAutoConnect": true,
-  },
-}
+```bash
+subminer jellyfin -p       # fzf picker; `jf` is an alias for `jellyfin`
+subminer -R jellyfin -p    # rofi picker
 ```
 
-See [Configuration](/configuration) for the full list (transcode codec, direct-play containers, default library, and more).
+Sign in first. See [Launcher script](/launcher-script) for the other `jellyfin` subcommands.
+
+## Options
+
+All options are under **Settings > Integrations > Jellyfin**, or `jellyfin` in `config.jsonc`. See [Configuration](/configuration#jellyfin) for the full list and defaults.
+
+| Key                        | What it does                                                         |
+| -------------------------- | -------------------------------------------------------------------- |
+| `enabled`                  | Turns the integration on. Set for you when you sign in.              |
+| `serverUrl`                | Your Jellyfin server. Filled in when you sign in.                    |
+| `remoteControlEnabled`     | Lets SubMiner act as a cast target.                                  |
+| `remoteControlAutoConnect` | Connects at startup. Turn off to start discovery from the tray.      |
+| `autoAnnounce`             | Re-announces the device on connect. Try it if SubMiner appears late. |
+| `transcodeVideoCodec`      | Video codec requested when Jellyfin transcodes.                      |
+
+For headless setups, `SUBMINER_JELLYFIN_ACCESS_TOKEN` and `SUBMINER_JELLYFIN_USER_ID` supply a session without the sign-in window. Treat the token store and `config.jsonc` as secrets.
 
 ## Troubleshooting
 
-**SubMiner doesn't appear in the cast menu**
+**SubMiner is missing from the cast menu.** Check that SubMiner is running, that you are signed in (log in again if the token expired), and that discovery is on. The Jellyfin client and SubMiner must use the same server.
 
-- Make sure SubMiner is running.
-- Make sure you're signed in - reopen **Configure Jellyfin** and log in again if your token expired.
-- Make sure discovery is on (tray **Jellyfin Discovery**, or **Remote Control Auto Connect** in settings).
-- Make sure SubMiner and the Jellyfin client point at the same server.
+**Casting starts but nothing plays.** Confirm the item plays in another Jellyfin client. If mpv was closed, give SubMiner a few seconds to start it.
 
-**Casting starts but nothing plays**
-
-- Confirm the item plays normally in another Jellyfin client.
-- If mpv was closed, give it a moment - SubMiner launches it on demand and retries.
-
-**SubMiner keeps disconnecting**
-
-- Check server/network stability and whether the session token has expired.
-
-## Security notes
-
-- The Jellyfin session (access token + user ID) is kept in SubMiner's local encrypted token storage. Your password is used only to log in and is never saved.
-- Treat the token storage and your `config.jsonc` as secrets - don't commit them.
-- Advanced/headless: the `SUBMINER_JELLYFIN_ACCESS_TOKEN` and `SUBMINER_JELLYFIN_USER_ID` environment variables can supply a session without the sign-in window.
-
-## Launcher playback
-
-If you'd rather stay in the terminal, the `subminer` launcher can browse and play Jellyfin media directly, without casting from a Jellyfin app:
-
-```bash
-subminer jellyfin -p      # alias: subminer jf -p
-```
-
-This opens an fzf picker (add `-R` for rofi) to browse your libraries and episodes, then plays the selected item in SubMiner's mpv with the same overlay, resume, and subtitle behavior described above. Sign in first (step 2) so the launcher can reach your server. See [Launcher Script](/launcher-script) for the rest of the launcher's features.
+**Linux token storage fails.** SubMiner stores the token with `gnome-libsecret` by default. Start your keyring, or pass `--password-store=basic_text`.
diff --git a/docs-site/jimaku-integration.md b/docs-site/jimaku-integration.md
index de387548..51af5f7a 100644
--- a/docs-site/jimaku-integration.md
+++ b/docs-site/jimaku-integration.md
@@ -1,116 +1,62 @@
-# Jimaku Integration
+# Jimaku integration
 
-[Jimaku](https://jimaku.cc) is a community-driven subtitle repository for anime - a shared online library of subtitle files contributed by other learners. SubMiner integrates with the Jimaku API so you can search, browse, and download Japanese subtitle files directly from the overlay - no alt-tabbing or manual file management required. Downloaded subtitles are loaded into mpv immediately.
+[Jimaku](https://jimaku.cc) is a community archive of Japanese subtitles for anime and live action. SubMiner searches it from the overlay, downloads the file you pick, and loads it into mpv.
 
-::: tip Prerequisite: a free API key
-You need a Jimaku account and an API key (a personal access string) before this feature works. Create an account at [jimaku.cc](https://jimaku.cc), copy your key, and add it to your config as shown under [Configuration](#configuration) below. Without a key, the search modal will report "Jimaku API key not set."
-:::
+## Setup
 
-## How It Works
-
-The Jimaku integration runs through an in-overlay modal accessible via a keyboard shortcut (`Ctrl+Shift+J` by default).
-
-When you open the modal, SubMiner parses the current video filename to extract a title, season, and episode number. Common naming conventions are supported - `S01E03`, `1x03`, `E03`, and dash-separated episode numbers all work. If the filename yields a high-confidence match (title + episode), SubMiner auto-searches immediately.
-
-From there:
-
-1. **Search** - SubMiner queries the Jimaku API with the parsed title. Results appear as a list of anime entries (Japanese and English names).
-2. **Browse entries** - Select an entry to load its available subtitle files, filtered by episode if one was detected.
-3. **Browse files** - Files show name, size, and last-modified date. If a language preference is configured, files are sorted accordingly (e.g., Japanese-tagged files first).
-4. **Download** - Selecting a file downloads it to the same directory as the video (or a temp directory for remote/streamed media) and loads it into mpv as a new subtitle track.
-
-If no files match the current episode filter, a "Show all files" button lets you broaden the search to all episodes for that entry.
-
-### 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 |
-
-## Configuration
-
-Add a `jimaku` section to your `config.jsonc`:
+1. Create a free account at [jimaku.cc](https://jimaku.cc) and copy your API key.
+2. Add the key to `config.jsonc`, either directly or through a command that prints it:
 
 ```jsonc
 {
   "jimaku": {
     "apiKey": "YOUR_API_KEY",
-    "apiKeyCommand": "cat ~/.jimaku_key",
-    "apiBaseUrl": "https://jimaku.cc",
-    "languagePreference": "ja",
-    "maxEntryResults": 10
-  }
+    // or, to keep it out of the config file:
+    // "apiKeyCommand": "pass jimaku/api-key",
+  },
 }
 ```
 
-| 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. |
+If both are set, `apiKey` wins. `apiKeyCommand` must print the key within 10 seconds. Without a key, the modal shows "Jimaku API key not set."
 
-The keyboard shortcut is configured separately under `shortcuts`:
+## Usage
 
-```jsonc
-{
-  "shortcuts": {
-    "openJimaku": "Ctrl+Shift+J"
-  }
-}
-```
+1. Press `Ctrl+Shift+J` during playback.
+2. SubMiner fills in the title, season, and episode from the file name. If it finds both a title and an episode, it searches right away. Otherwise, fix the fields and press `Enter`.
+3. Pick the **Anime** or **Live action** tab. Switching tabs repeats the search.
+4. Select an entry, then select a file. Files are filtered to the current episode. Click **Broaden search (all files)** to see every file in the entry.
 
-### API Key
+The file is saved next to the video (or to a temp directory for streams) and loaded into mpv as a new subtitle track.
 
-An API key is required to use the Jimaku integration. You can get one from [jimaku.cc](https://jimaku.cc). There are two ways to provide it:
+| Key              | Action                                 |
+| ---------------- | -------------------------------------- |
+| `Enter`          | Search, or select the highlighted item |
+| `Up` / `Down`    | Move through entries or files          |
+| `Left` / `Right` | Switch tabs                            |
+| `Escape`         | Close                                  |
 
-- **`apiKey`** - set the key directly in config. Simple, but the key is stored in plaintext.
-- **`apiKeyCommand`** - a shell command that outputs the key. Runs with a 10-second timeout. Preferred if you use a secret manager like `pass`, `gpg`, or a keychain tool.
+You can also open the modal with `subminer app --open-jimaku`, or change the shortcut with `shortcuts.openJimaku`.
 
-If both are set, `apiKey` takes priority.
+The file name parser understands `S01E03`, `1x03`, `E03`, `EP03`, and `Title - 03 -` patterns, and reads the season from a parent folder such as `Season 2`. It ignores bracket tags like `[SubGroup]` and year tags like `(2024)`.
 
-## Filename Parsing
+## Options
 
-SubMiner extracts media info from the current video path to pre-fill the search fields. The parser handles:
+| Key                         | What it does                                                        |
+| --------------------------- | ------------------------------------------------------------------- |
+| `jimaku.apiKey`             | API key in plain text.                                              |
+| `jimaku.apiKeyCommand`      | Shell command that prints the API key.                              |
+| `jimaku.languagePreference` | Sorts files tagged with this language first: `ja`, `en`, or `none`. |
+| `jimaku.maxEntryResults`    | Maximum entries per search.                                         |
+| `jimaku.apiBaseUrl`         | API address. Change only for a mirror.                              |
 
-- **Season + episode patterns:** `S01E03`, `1x03`
-- **Episode-only patterns:** `E03`, `EP03`, or dash-separated numbers like `Title - 03 -`
-- **Season folders:** a parent directory named `Season 2` or `S2` fills in the season when the filename lacks one
-- **Bracket tags:** `[SubGroup]`, `[1080p]`, `[HEVC]` - stripped before title extraction
-- **Year tags:** `(2024)` - stripped
-- **Dots and underscores:** treated as spaces
-- **Remote/streamed URLs:** SubMiner checks URL query parameters (`title`, `name`, `q`) and path segments to extract a meaningful title
-
-If the parser produces a high-confidence result (title + episode both detected), the search runs automatically when the modal opens. Otherwise, you can adjust the fields manually before searching.
+See [Configuration](/configuration#jimaku) for defaults.
 
 ## Troubleshooting
 
-**"Jimaku API key not set"**
+**"Jimaku API key not set."** Set `jimaku.apiKey` or `jimaku.apiKeyCommand`. Run the command in your shell to confirm it prints only the key.
 
-Configure `jimaku.apiKey` or `jimaku.apiKeyCommand` in your config. If using `apiKeyCommand`, verify the command works in your shell: it should print the key and exit cleanly.
+**HTTP 429.** You hit Jimaku's rate limit. Wait for the time shown in the message and retry.
 
-**"Jimaku request failed" or HTTP 429**
+**No entries found.** Search with just the show's name, without season or episode words. Jimaku matches against its own titles.
 
-The Jimaku API has rate limits. If you see 429 errors, wait for the retry duration shown in the OSD message and try again.
-
-**No entries found**
-
-Try simplifying the title - remove season/episode qualifiers and search with just the anime name. Jimaku's search matches against its own database of anime titles, so the exact spelling matters.
-
-**No files found for this episode**
-
-The entry may not have per-episode files, or files may be named differently. Click "Show all files" to see everything available for the entry.
-
-**Downloaded subtitle not loading**
-
-Verify mpv is running and connected via IPC. SubMiner loads the subtitle by issuing a `sub-add` command over the mpv socket. If mpv is not connected, the download succeeds but the subtitle cannot be loaded.
-
-## Related
-
-- [Configuration Reference](/configuration#jimaku) - full config options
-- [Mining Workflow](/mining-workflow#related-features) - how Jimaku fits into the sentence mining loop
-- [Troubleshooting](/troubleshooting#jimaku) - additional error guidance
+**The subtitle downloads but does not load.** SubMiner loads it over the mpv socket. Make sure mpv is still running and connected.
diff --git a/docs-site/launcher-script.md b/docs-site/launcher-script.md
index e45b7c32..bd459095 100644
--- a/docs-site/launcher-script.md
+++ b/docs-site/launcher-script.md
@@ -1,206 +1,195 @@
-# Launcher Script
+# Launcher script
 
-The `subminer` launcher is an all-in-one script that handles video selection, mpv startup, and overlay management. It is the recommended way to use SubMiner on Linux and macOS because it guarantees mpv is launched with the correct IPC socket and SubMiner defaults. It's a Bun script distributed as a release asset alongside the AppImage and DMG.
+`subminer` is the command-line entry point for SubMiner. It starts mpv with the socket and options SubMiner needs, opens file pickers, and runs helper commands. This page is the reference for its subcommands and flags. For everyday use, start with [Usage](/usage).
 
-::: tip Windows users
-On Windows, the recommended way to launch playback is the **SubMiner mpv** shortcut created during first-run setup - double-click it, drag a file onto it, or run `SubMiner.exe --launch-mpv` from a terminal. See [Windows mpv Shortcut](/usage#windows-mpv-shortcut) for details.
-:::
-
-## Video Picker
-
-When you run `subminer` without specifying a file, it opens an interactive video picker. By default it uses **fzf** in the terminal; pass `-R` to use **rofi** instead.
-
-### fzf (default)
+You do not need Bun or anything else installed to run it. It uses the runtime bundled with the app. On Windows, the **SubMiner mpv** shortcut is the simpler way to play files (see [Windows mpv shortcut](/usage#windows-mpv-shortcut)).
 
 ```bash
-subminer                               # pick from current directory
-subminer -d ~/Videos                   # pick from a specific directory
-subminer -r -d ~/Anime                 # recursive search
+subminer [options] [file | directory | URL]
+subminer <subcommand> [options]
 ```
 
-fzf shows video files in a fuzzy-searchable list. If `chafa` is installed, you get thumbnail previews in the right pane. Thumbnails are sourced from the freedesktop thumbnail cache first, then generated on the fly with `ffmpegthumbnailer` or `ffmpeg` as fallback.
-
-| Optional tool       | Purpose                           |
-| ------------------- | --------------------------------- |
-| `chafa`             | Render thumbnails in the terminal |
-| `ffmpegthumbnailer` | Generate thumbnails on the fly    |
-
-### rofi
-
-```bash
-subminer -R                            # rofi picker, current directory
-subminer -R -d ~/Videos                # rofi picker, specific directory
-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:
-
-```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/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.
-
-The theme is auto-detected from these paths (first match wins):
-
-- `$SUBMINER_ROFI_THEME` environment variable (absolute path)
-- `$XDG_DATA_HOME/SubMiner/themes/subminer.rasi` (default: `~/.local/share/SubMiner/themes/subminer.rasi`)
-- `/usr/local/share/SubMiner/themes/subminer.rasi`
-- `/usr/share/SubMiner/themes/subminer.rasi`
-- macOS: `~/Library/Application Support/SubMiner/themes/subminer.rasi`
-- `assets/themes/subminer.rasi` next to the launcher script (final fallback)
-
-Override with the `SUBMINER_ROFI_THEME` environment variable:
-
-```bash
-SUBMINER_ROFI_THEME=/path/to/custom-theme.rasi subminer -R
-```
-
-## Watch History
-
-`subminer -H` (or `--history`) browses your local watch history, sourced from the immersion tracker database. It works with both pickers: fzf by default, rofi with `-R -H`.
-
-```bash
-subminer -H                            # fzf history browser
-subminer -R -H                         # rofi history browser
-```
-
-The first menu lists every locally watched series, most recently watched first, using the parsed media title (e.g. the anime title) when available and the directory name otherwise. Selecting a series opens an action menu:
-
-- **Previous episode**: plays the episode before the last watched one and continues into the previous season directory when the season starts
-- **Replay last watched**: replays the most recently watched episode
-- **Next episode**: plays the episode after the last watched one and continues into the next season directory when the season ends
-- **Browse episodes**: lists the video files in the series directory in episode order, using the same fzf/rofi episode picker as directory browsing; if the series has multiple season directories, a season menu appears first
-- **Quit SubMiner**: closes the history session without starting an episode
-
-After an episode ends or you close mpv, the launcher returns to an action menu for the same series. The menu lists Previous, Rewatch, Next, Select episode, and Quit SubMiner in that order, omitting Previous or Next when no episode exists in that direction. Choosing Previous or Next can move between season directories. After you play another episode, Previous, Rewatch, and Next use it instead of the older database entry. Pressing Escape closes the history session.
-
-Series whose directories are not currently accessible (e.g. an unmounted network share) are hidden from the list. Watch history requires the immersion tracker database (`immersionTracking.dbPath`, default `<config dir>/immersion.sqlite`), which SubMiner populates during playback.
-
-## Sync Between Machines
-
-`subminer sync <host>` merges immersion stats and watch history between two machines over SSH, so both end up with the union of sessions, lifetime totals, vocabulary counts, daily/monthly charts, and `--history` entries. `<host>` is anything `ssh` accepts (`user@hostname` or an ssh config alias); SubMiner must be installed on both machines at the same version. The sync engine runs only inside the app (`SubMiner --sync-cli sync ...`): the sync window spawns it that way, `subminer sync` is a thin proxy that forwards to the installed app, and the remote side is found automatically whether it has the launcher or just the app. The command-line launcher is optional everywhere.
-
-```bash
-subminer sync macbook                  # two-way sync with the host "macbook"
-subminer sync macbook --push           # merge local data into macbook only
-subminer sync macbook --pull           # merge macbook data into local only
-subminer sync user@192.168.1.20       # explicit user@host
-subminer sync macbook --remote-cmd ~/bin/subminer  # custom remote SubMiner/launcher path
-subminer sync macbook --check          # test SSH + remote SubMiner without syncing
-subminer sync --ui                     # open the sync window (also in the tray menu)
-```
-
-How it works: each side takes a consistent snapshot of its database (`VACUUM INTO`), the snapshots are exchanged over `scp`, and each machine merges the other's snapshot into its own database. The merge is an insert-only union keyed on stable identifiers (session UUIDs, video keys, series title keys, word/kanji identity), so it is safe to re-run at any time. Syncing twice changes nothing, and nothing is ever overwritten or summed twice. Lifetime totals and rollup charts are updated incrementally, so history older than the session retention window is preserved on both sides.
-
-For a one-way transfer, `--push` snapshots the local database and merges it into the host without changing the local database. `--pull` snapshots the host and merges it into the local database without changing the host. These modes add missing data; they do not delete destination-only data or make the destination an exact mirror.
-
-Command-line sync defaults to a cold-start safety check: close SubMiner (and stop the background stats daemon with `subminer stats -s`) on both machines before running it, or pass `--force`. Syncs started from the Sync window use live mode automatically, including scheduled auto-syncs while SubMiner or playback is active. SQLite WAL provides a consistent snapshot, the transactional merge serializes with live writes, and each machine's unfinished session is excluded from the transfer; that session syncs normally after it finishes. The mpv safety check requires a live socket connection, so a stale socket file left after mpv exits does not block command-line sync. Both machines must be on the same SubMiner version; otherwise, the sync aborts on a stats schema mismatch.
-
-On the remote, sync looks for the `subminer` launcher first (PATH and `~/.local/bin`), then the app binary in `--sync-cli` mode (`SubMiner` on PATH, then the standard macOS `/Applications` and `~/Applications` installs), checking standard SubMiner and Bun locations (`~/.local/bin`, `~/.bun/bin`, Homebrew, `/usr/local/bin`, `/usr/bin`, and `/bin`) even when the non-interactive SSH shell omits them from `PATH`. An AppImage in a custom location can be addressed with `--remote-cmd /path/to/SubMiner.AppImage` (or symlink it as `SubMiner` somewhere on the remote PATH).
-
-Windows remotes are supported: enable Windows' built-in **OpenSSH Server** and sync detects the remote shell (cmd or PowerShell) automatically, finding SubMiner in its default install location (`%LOCALAPPDATA%\Programs\SubMiner`), the launcher shim (`%LOCALAPPDATA%\SubMiner\bin`), or on PATH. Temp files on the remote are created and removed by SubMiner itself (`sync --make-temp` / `--remove-temp`), so no POSIX tools are required on the remote side.
-
-Two lower-level modes are used internally over SSH and also work standalone for manual transfers (e.g. via a USB drive):
-
-```bash
-subminer sync --snapshot /tmp/stats.sqlite   # write a consistent snapshot of the local database
-subminer sync --merge /tmp/stats.sqlite      # merge a snapshot file into the local database
-```
-
-Unfinished sessions (a crash mid-playback) are skipped until the app finalizes them; they sync on the next run. Word/kanji "known" state from Anki is not part of the database and does not sync. Each machine derives it from its own Anki collection.
-
-`subminer sync <host> --check` verifies a host without touching any data: it probes the SSH connection, locates SubMiner on the remote (launcher or app binary), and reports its version. `--json` switches any sync mode to machine-readable NDJSON progress output (this is what the sync window consumes).
-
-`sync --make-temp` creates a restricted temporary directory and prints its path; `sync --remove-temp <dir>` removes one created by that command. They are internal SSH transfer helpers, exposed for compatibility but normally invoked only by sync itself. `SubMiner --sync-cli sync ...` is the packaged app's headless compatibility entrypoint; use `SubMiner --sync-cli --help` for its sync-specific help. The `subminer sync` launcher command selects this entrypoint automatically and runs AppImages in Node-only mode, so remote sync does not require a graphical session.
-
-### Sync window
-
-`subminer sync --ui` opens a dedicated window for the same engine in a detached app process, returning the shell immediately. Closing that standalone-launched window exits its app instance. Opening **Sync Stats & History** from the tray keeps the resident app running when the window closes:
-
-- **Devices:** saved hosts with a per-host direction (two-way / push / pull), an auto-sync toggle, last-sync status, and one-click **Sync now** / **Test** / **Remove**. Hosts synced from the command line appear here automatically.
-- **Add a device:** test SSH + remote SubMiner availability before saving, with a setup checklist for first-time SSH configuration.
-- **Activity:** live stage-by-stage progress, remote output, and separate merge summaries (sessions, words, kanji, rollups) for each machine updated by the run. Runs can be cancelled and can proceed while the app, stats server, or playback is active.
-- **Snapshots:** create manual database snapshots (stored in `/tmp/subminer-db-snapshots/` by default), merge a snapshot file into the local database, or reveal/delete existing snapshots.
-
-Hosts with **Auto-sync** enabled are synced in the background on a configurable interval (default every 60 minutes), including during active playback; results surface as overlay notifications. The unfinished playback session is skipped until a later sync sees it finalized. Host bookkeeping lives in `<config dir>/sync-hosts.json`.
-
-## Common Commands
-
-```bash
-subminer video.mkv                      # play a specific file (managed launches auto-start the visible overlay by default)
-subminer https://youtu.be/...           # YouTube playback (requires yt-dlp)
-subminer --backend x11 video.mkv        # Force x11 backend for a specific file
-subminer -u                             # check for SubMiner updates
-subminer logs -e                        # export sanitized log ZIP
-subminer stats                          # open immersion dashboard
-subminer stats -b                       # start background stats daemon
-```
-
-## Subcommands
-
-| Subcommand                                 | Purpose                                                                                           |
-| ------------------------------------------ | ------------------------------------------------------------------------------------------------- |
-| `subminer jellyfin` / `jf`                 | Jellyfin workflows (`-d` discovery, `-p` play, `-l` login, `--logout`, `--setup`)                 |
-| `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                                                                 |
-| `subminer logs -e`                         | Export a sanitized local-date log ZIP and print its path                                          |
-| `subminer config path`                     | Print active config file path                                                                     |
-| `subminer config show`                     | Print active config contents                                                                      |
-| `subminer mpv status`                      | Check mpv socket readiness                                                                        |
-| `subminer mpv socket`                      | Print active socket path                                                                          |
-| `subminer mpv idle`                        | Launch detached idle mpv instance                                                                 |
-| `subminer sync <host>`                     | Two-way stats/history sync with another machine over SSH                                          |
-| `subminer sync <host> --push`              | Merge local stats/history into another machine only                                               |
-| `subminer sync <host> --pull`              | Merge another machine's stats/history into the local database only                                |
-| `subminer sync <host> --check`             | Test SSH connection and remote launcher availability                                              |
-| `subminer sync --ui`                       | Open the sync window (saved devices, auto-sync, snapshots)                                        |
-| `subminer dictionary <path>` / `dict`      | Generate character dictionary ZIP from file/dir target                                            |
-| `subminer dictionary --candidates <path>`  | List AniList candidate matches for character dictionary correction                                |
-| `subminer dictionary --select <id> <path>` | Pin an AniList media ID for that target series                                                    |
-| `subminer texthooker`                      | Launch texthooker-only mode                                                                       |
-| `subminer texthooker -o`                   | Launch texthooker and open it in the default browser                                              |
-| `subminer app` / `bin`                     | Pass arguments directly to SubMiner binary (e.g. `subminer app --setup`)                          |
-
-Use `subminer <subcommand> -h` for command-specific help.
+Run `subminer -h` or `subminer <subcommand> -h` for built-in help.
 
 ## Options
 
-| Flag                  | Description                                                                  |
-| --------------------- | ---------------------------------------------------------------------------- |
-| `-d, --directory`     | Video search directory (default: cwd)                                        |
-| `-r, --recursive`     | Search directories recursively                                               |
-| `-R, --rofi`          | Use rofi instead of fzf                                                      |
-| `-H, --history`       | Browse local watch history (see [Watch History](#watch-history))             |
-| `-v, --version`       | Print the launcher's own version (can differ from the installed app binary)  |
-| `-u, --update`        | Check for SubMiner updates and update the app/launcher when possible         |
-| `--start`             | Explicitly start overlay after mpv launches                                  |
-| `-S, --start-overlay` | Force the visible overlay on start                                           |
-| `-T, --no-texthooker` | Disable texthooker server                                                    |
-| `-p, --profile`       | mpv profile name (no default; omitted unless set)                            |
-| `-a, --args`          | Pass additional mpv arguments as a quoted string                             |
-| `-b, --backend`       | Force window backend (`auto`, `hyprland`, `sway`, `x11`, `macos`, `windows`) |
-| `--settings`          | Open the SubMiner settings window                                            |
-| `--log-level`         | Logger verbosity (`debug`, `info`, `warn`, `error`)                          |
+| Flag                  | Description                                                                         |
+| --------------------- | ----------------------------------------------------------------------------------- |
+| `-d, --directory`     | Directory to browse (default: current directory)                                    |
+| `-r, --recursive`     | Search subdirectories                                                               |
+| `-R, --rofi`          | Use rofi instead of fzf                                                             |
+| `-H, --history`       | Browse [watch history](#watch-history)                                              |
+| `-b, --backend`       | Window backend: `auto`, `hyprland`, `sway`, `x11`, `macos`, `windows`               |
+| `-p, --profile`       | mpv profile to load                                                                 |
+| `-a, --args`          | Extra mpv options as one quoted string, e.g. `--args "--volume=80"`                 |
+| `--start`             | Start the overlay after mpv launches. Only needed if `mpv.autoStartSubMiner` is off |
+| `-S, --start-overlay` | Show the overlay on start                                                           |
+| `-T, --no-texthooker` | Do not start the texthooker server                                                  |
+| `--settings`          | Open the settings window                                                            |
+| `--log-level`         | `debug`, `info`, `warn`, or `error`                                                 |
+| `-u, --update`        | Check for and install updates                                                       |
+| `-v, --version`       | Print the launcher's version                                                        |
 
-App-binary flags such as `--setup`, `--dev`, and `--debug` are not launcher flags - pass them through with `subminer app`, for example `subminer app --setup`.
+The target can be a video file, a directory (opens the picker there), a URL, or `ytsearch:"query"` for the first YouTube search result.
 
-On Linux, `subminer -u` updates from the launcher process itself. It can check and replace the AppImage, launcher, runtime plugin copy, and rofi theme even when SubMiner is already running in the tray.
+App flags such as `--setup` and `--dev` are not launcher flags. Pass them through with `subminer app`, for example `subminer app --setup`.
 
-Managed launches inject `auto_start=yes`, `auto_start_visible_overlay=yes`, and `auto_start_pause_until_ready=yes` as plugin script-opts from SubMiner's config defaults (`mpv.autoStartSubMiner`, `auto_start_overlay`), so explicit start flags are usually unnecessary. The plugin's own built-in defaults are off - mpv launched outside SubMiner does not auto-start the overlay.
+## Subcommands
+
+| Command                                    | What it does                                                                                                         |
+| ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- |
+| `subminer stats`                           | Start the stats dashboard server. Opens your browser if `stats.autoOpenBrowser` is on                                |
+| `subminer stats -b` / `-s`                 | Start (or reuse) the stats server in the background / stop it                                                        |
+| `subminer stats cleanup`                   | Backfill vocabulary metadata and prune stale rows (same as `-v`)                                                     |
+| `subminer stats cleanup -l`                | Rebuild lifetime totals from the retained sessions                                                                   |
+| `subminer stats cleanup -d`                | Collapse repeated lines from typeset subtitles. Add `--dry-run` to preview, `--lookback-days <n>` to limit the range |
+| `subminer stats rebuild` / `backfill`      | Same as `stats cleanup -l`                                                                                           |
+| `subminer sync <host>`                     | Sync stats and watch history with another machine. See [below](#sync-between-machines)                               |
+| `subminer doctor`                          | Check the app, mpv, ffmpeg, yt-dlp, pickers, config, and mpv socket                                                  |
+| `subminer doctor --refresh-known-words`    | Refresh the known-word cache from Anki                                                                               |
+| `subminer settings`                        | Open the settings window                                                                                             |
+| `subminer generate-subs [video]`           | Generate [Japanese subtitles](/subtitle-generation) with whisper.cpp                                                 |
+| `subminer jellyfin` / `jf`                 | [Jellyfin](/jellyfin-integration) actions: `setup`, `login`, `logout`, `play`, `discovery`                           |
+| `subminer dictionary <path>` / `dict`      | Build a [character dictionary](/character-dictionary) for a file or directory                                        |
+| `subminer dictionary --candidates <path>`  | List AniList matches for that target                                                                                 |
+| `subminer dictionary --select <id> <path>` | Pin an AniList ID for that target                                                                                    |
+| `subminer texthooker`                      | Run only the texthooker server. `-o` opens it in your browser                                                        |
+| `subminer logs -e`                         | Export a sanitized log ZIP and print its path                                                                        |
+| `subminer config path` / `show`            | Print the config file path or its contents                                                                           |
+| `subminer mpv status`                      | Exit 0 if the mpv socket is ready, 1 if not                                                                          |
+| `subminer mpv socket`                      | Print the mpv socket path                                                                                            |
+| `subminer mpv idle`                        | Start an idle mpv in the background with SubMiner's options                                                          |
+| `subminer app` / `bin`                     | Pass arguments to the SubMiner app, e.g. `subminer app --stop`                                                       |
+
+`stats cleanup` runs one mode at a time. `--lookback-days` must be at least 1. Without it, cleanup scans all history.
+
+`generate-subs` options: `--download-model`, `--model <name>`, `--model-path <file>`, `--output <file>`, and `--audio-stream <index>` (an ffprobe stream index). `--model-path` cannot be combined with `--model` or `--download-model`.
+
+A texthooker is a web page that shows the current subtitle as plain text, so browser extensions and other tools can read along.
+
+## Video picker
+
+With no file argument, `subminer` opens a picker for the current directory, or for `-d <dir>`. Add `-r` to include subdirectories.
+
+- **fzf** (default) runs in the terminal. With `chafa` installed, it shows thumbnail previews.
+- **rofi** (`-R`, Linux) opens a graphical menu with thumbnails.
+
+Thumbnails come from your system thumbnail cache, or are generated with `ffmpegthumbnailer` or `ffmpeg`.
+
+The launcher installs its rofi theme automatically. To use your own, set `SUBMINER_ROFI_THEME`:
+
+```bash
+SUBMINER_ROFI_THEME=/path/to/theme.rasi subminer -R
+```
+
+## Watch history
+
+`subminer -H` lists the shows you have watched, most recent first. Add `-R` to use rofi. Pick a show, then choose:
+
+- **Previous episode** or **Next episode**, moving into the neighboring season folder when needed
+- **Replay last watched**
+- **Browse episodes**, with a season menu first if the show has several season folders
+- **Quit SubMiner**
+
+When an episode ends, the menu comes back for the same show. Press `Escape` to leave.
+
+History comes from the immersion stats database, which SubMiner fills during playback. Shows whose folders are not reachable, such as an unmounted network drive, are hidden.
+
+## mpv options and profiles
+
+The launcher starts mpv with these options:
+
+```
+--input-ipc-server=/tmp/subminer-socket
+--alang=ja,jp,jpn,japanese,en,eng,english,enus,en-us
+--slang=ja,jp,jpn,japanese,en,eng,english,enus,en-us
+--sub-auto=fuzzy
+--sub-file-paths=.;subs;subtitles
+--sid=auto
+--secondary-sid=auto
+--sub-visibility=no
+--secondary-sub-visibility=no
+```
+
+mpv's own subtitles are hidden because the overlay draws them. Add more options with `-a`, or load an mpv profile with `-p <name>` or `mpv.profile` in the config. No profile is loaded by default.
+
+To launch mpv yourself with the same setup, put the options in a profile in `~/.config/mpv/mpv.conf`:
+
+```ini
+[subminer]
+input-ipc-server=/tmp/subminer-socket
+alang=ja,jp,jpn,japanese,en,eng,english,enus,en-us
+slang=ja,jp,jpn,japanese,en,eng,english,enus,en-us
+sub-auto=fuzzy
+sub-file-paths=.;subs;subtitles
+sid=auto
+secondary-sid=auto
+secondary-sub-visibility=no
+```
+
+Launches through `subminer` start the overlay automatically unless `mpv.autoStartSubMiner` is off. mpv started outside SubMiner does not start the overlay on its own.
+
+## Sync between machines
+
+`subminer sync <host>` merges immersion stats and watch history between two computers over SSH. Both end up with the combined sessions, totals, vocabulary, charts, and `-H` history. `<host>` is anything `ssh` accepts, such as `user@hostname` or an alias from your SSH config.
+
+Both machines need the same SubMiner version. The remote only needs the app. The `subminer` command is optional there.
+
+```bash
+subminer sync macbook                    # two-way sync
+subminer sync macbook --push             # send local data to macbook only
+subminer sync macbook --pull             # bring macbook data here only
+subminer sync macbook --check            # test SSH and the remote install, change nothing
+subminer sync macbook --remote-cmd ~/Apps/SubMiner.AppImage   # SubMiner in a custom place on the remote
+subminer sync --ui                       # open the sync window
+```
+
+Syncing only adds data. It never overwrites or double-counts, so you can run it as often as you like. `--push` and `--pull` do not delete anything on the receiving side.
+
+Before a command-line sync, close SubMiner on both machines and stop the stats server with `subminer stats -s`, or pass `--force`. The sync window does not need this. It syncs while SubMiner and playback are running, and skips the session in progress until it finishes.
+
+Transfers are compressed. When both machines have `rsync` (macOS and Linux), later syncs send only what changed. Windows machines use `scp`.
+
+Known-word status from Anki does not sync. Each machine reads it from its own Anki collection.
+
+<details>
+<summary><b>More sync options</b></summary>
+
+| Option              | Description                                                 |
+| ------------------- | ----------------------------------------------------------- |
+| `-f, --force`       | Skip the check that SubMiner is closed                      |
+| `--db <file>`       | Use a different local stats database                        |
+| `--json`            | Print progress as NDJSON                                    |
+| `--snapshot <file>` | Write a snapshot of the local database, e.g. to copy by USB |
+| `--merge <file>`    | Merge a snapshot file into the local database               |
+
+A Windows remote needs the built-in **OpenSSH Server** enabled. SubMiner finds itself in the default install location there.
+
+If the remote cannot find SubMiner, point `--remote-cmd` at the app or launcher, or link it as `SubMiner` somewhere on the remote `PATH`.
+
+Received snapshots are cached in `sync-transfer-cache/` in the config directory to speed up later syncs. Deleting it is safe.
+
+</details>
+
+### Sync window
+
+`subminer sync --ui`, or **Sync Stats & History** in the tray, opens a window where you can:
+
+- Save devices, each with a direction (two-way, push, or pull), and run **Sync now** or **Test**.
+- Turn on **Auto-sync** for a device. It syncs in the background every 60 minutes by default, including during playback.
+- Watch progress and see what was merged on each machine.
+- Create, merge, or delete database snapshots.
+
+Saved devices live in `sync-hosts.json` in the config directory.
+
+## Environment variables
+
+| Variable                 | Use                                                                   |
+| ------------------------ | --------------------------------------------------------------------- |
+| `SUBMINER_BINARY_PATH`   | Path to the SubMiner app, if it is not in a standard install location |
+| `SUBMINER_APPIMAGE_PATH` | Same, for an AppImage (Linux)                                         |
+| `SUBMINER_ROFI_THEME`    | Path to a custom rofi theme                                           |
 
 ## Logging
 
-- Default log level is `warn` (launcher and app; configurable via `logging.level`)
-- `--dev` / `--debug` are app-binary flags that control app dev-mode, not logging verbosity - use `--log-level` for that
+The default log level is `warn`. Change it for one run with `--log-level`, or permanently with `logging.level` in the config. The app's `--dev` and `--debug` flags turn on developer mode. They do not change the log level.
diff --git a/docs-site/mining-workflow.md b/docs-site/mining-workflow.md
index 08c40957..d8e12227 100644
--- a/docs-site/mining-workflow.md
+++ b/docs-site/mining-workflow.md
@@ -1,192 +1,87 @@
-# Mining Workflow
+# Mining workflow
 
-This guide walks through the sentence mining loop - from watching a video to creating Anki cards with audio, screenshots, and context.
+SubMiner turns lines from the video you are watching into Anki cards. You look up a word on the overlay, add it with Yomitan, and SubMiner fills in the sentence, an audio clip, and a screenshot. For Anki setup, field mapping, and media options, see [Anki integration](/anki-integration).
 
-## Overview
+## Look up a word
 
-_Sentence mining_ means turning real sentences you encounter while watching native video into Anki flashcards, so you learn vocabulary in the context where you actually met it. SubMiner automates the tedious parts of that loop.
+1. Hover the subtitle line on the overlay. Each word is its own hover target.
+2. Press your Yomitan scan key or modifier (whatever your Yomitan profile uses, for example `Shift`).
+3. The Yomitan popup opens for that word.
 
-SubMiner runs as a transparent overlay on top of mpv (the video player). As subtitles play, the overlay displays them as interactive text. You hover a word, trigger a Yomitan dictionary lookup with your configured lookup key/modifier, then create an Anki card with a single action. SubMiner automatically attaches the sentence, an audio clip, and a screenshot to that card - no manual copy-pasting or screen capturing.
+Playback pauses while you hover the subtitle and while the Yomitan popup is open. Turn this off with `subtitleStyle.autoPauseVideoOnHover` and `subtitleStyle.autoPauseVideoOnYomitanPopup`.
 
-> **Yomitan** is the popup dictionary that shows definitions when you hover or scan a word. **AnkiConnect** is the add-on that lets SubMiner talk to Anki. Both are set up during installation - see [Anki Integration](/anki-integration) if you have not configured them yet.
+## Add a word card
 
-## Creating Anki Cards
+Click the add button in the Yomitan popup. SubMiner sees the new note and fills it in:
 
-There are four ways to create or enrich cards, depending on your workflow.
+| Field    | Content                                                |
+| -------- | ------------------------------------------------------ |
+| Sentence | The current subtitle line, with the mined word in bold |
+| Audio    | A clip cut from the video using the subtitle's timing  |
+| Image    | A screenshot, or an animated AVIF clip of the line     |
+| MiscInfo | Source file name and timestamp                         |
 
-### 1. Auto-Update from Yomitan
+Which note fields receive each item is set in [`ankiConnect.fields`](/anki-integration#field-mapping). With the default proxy mode the card is filled as soon as Yomitan adds it. If you disable the proxy, SubMiner polls Anki and fills the card a few seconds later.
 
-This is the most common flow. Yomitan creates a card in Anki, and SubMiner enriches it automatically.
+## Update the last card by hand
 
-1. Hover a word, then trigger Yomitan lookup → Yomitan popup appears.
-2. Click the Anki icon in Yomitan to add the word.
-3. SubMiner receives or detects the new card:
-   - **Proxy mode** (default, `ankiConnect.proxy.enabled: true`): immediate enrich after a successful `addNote` / `addNotes` is pushed through the local proxy.
-   - **Polling mode** (fallback, when the proxy is disabled): detects new cards via AnkiConnect polling (`ankiConnect.pollingRate`, default 3 seconds).
-4. SubMiner updates the card with:
-   - **Sentence**: The current subtitle line.
-   - **Audio**: Extracted from the video using the subtitle's start/end timing (plus optional configured padding).
-   - **Image**: A screenshot or animated clip from the current playback position.
-   - **Translation**: From the secondary subtitle track, or generated via AI if configured.
-   - **MiscInfo**: Metadata like filename and timestamp.
+Use this when auto-update is off, or when the line you want is not the one on screen.
 
-Configure which fields to fill in `ankiConnect.fields`. See [Anki Integration](/anki-integration) for details.
+1. Add the word with Yomitan.
+2. Press `Ctrl/Cmd+C` to copy the current line. To combine lines, press `Ctrl/Cmd+Shift+C`, then a digit `1` to `9` for how many recent lines to include.
+3. Press `Ctrl/Cmd+V`. SubMiner writes the clipboard text into the last-added card's sentence field and adds fresh audio and an image.
 
-### 2. Manual Update from Clipboard
+A manual update always replaces the sentence audio, even when `ankiConnect.behavior.overwriteAudio` is `false`.
 
-If you prefer a hands-on approach (animecards-style), you can copy the current subtitle to the clipboard and then paste it onto the last-added Anki card:
+## Mine a sentence card
 
-1. Add a word via Yomitan as usual.
-2. Press `Ctrl/Cmd+C` to copy the current subtitle line to the clipboard.
-   - 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.
+Press `Ctrl/Cmd+S` to create a sentence card from the current line without a Yomitan lookup. Press `Ctrl/Cmd+Shift+S`, then a digit `1` to `9`, to combine several recent lines into one card. The digit prompt closes after `shortcuts.multiCopyTimeoutMs`.
 
-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.
+Sentence cards use the note type named in `ankiConnect.isLapis.sentenceCardModel` and write to its `Sentence` and `SentenceAudio` fields. That note type must exist in Anki. See [sentence cards](/anki-integration#sentence-cards-lapis).
 
-This is useful when auto-update is disabled or when you want explicit control over which subtitle line gets attached to the card.
+## Mark an audio card
 
-| Shortcut                   | Action                          | Config key                              |
-| -------------------------- | ------------------------------- | --------------------------------------- |
-| `Ctrl/Cmd+C`               | Copy current subtitle           | `shortcuts.copySubtitle`                |
-| `Ctrl/Cmd+Shift+C` + digit | Copy multiple recent lines      | `shortcuts.copySubtitleMultiple`        |
-| `Ctrl/Cmd+V`               | Update last card from clipboard | `shortcuts.updateLastCardFromClipboard` |
+After adding a word, press `Ctrl/Cmd+Shift+A`. SubMiner sets the Lapis/Kiku `IsAudioCard` flag on the last-added card and fills `Sentence`, `SentenceAudio`, the image, and MiscInfo.
 
-### 3. Mine Sentence (Hotkey)
+## Merge repeated words
 
-Create a standalone sentence card without going through Yomitan:
+If you mine a word you already have a card for, SubMiner can merge the new sentence, audio, and image into the existing card instead of keeping a duplicate. This needs the Kiku or Senren note type with field grouping turned on. In manual mode a dialog shows both cards and lets you pick which one to keep. See [field grouping](/anki-integration#field-grouping-kiku-senren).
 
-- **Mine current sentence**: `Ctrl/Cmd+S` (configurable via `shortcuts.mineSentence`)
-- **Mine multiple lines**: `Ctrl/Cmd+Shift+S` followed by a digit 1–9 to select how many recent subtitle lines to combine (the digit selector times out after 3 seconds, configurable via `shortcuts.multiCopyTimeoutMs`).
+## Subtitle display
 
-The sentence card uses the note type configured in `isLapis.sentenceCardModel` and always maps sentence/audio to `Sentence` and `SentenceAudio`.
+The overlay has a primary subtitle bar (the Japanese line you mine from) and a secondary bar for a translation track. Each bar is hidden, visible, or shown only on hover.
 
-::: warning Requires Lapis/Kiku note type
-Sentence card creation requires `ankiConnect.isLapis.sentenceCardModel` to name a [Lapis](https://github.com/donkuri/lapis) or [Kiku](https://github.com/youyoumu/kiku) compatible note type that exists in Anki (default: `"Lapis"`). See [Anki Integration - Sentence Cards](/anki-integration#sentence-cards-lapis) for setup.
-:::
+| Shortcut           | Action                             |
+| ------------------ | ---------------------------------- |
+| `V`                | Cycle primary bar mode             |
+| `Ctrl/Cmd+Shift+V` | Cycle secondary bar mode           |
+| `Shift+J`          | Cycle the secondary subtitle track |
+| Right-click        | Pause or resume                    |
+| Right-click + drag | Move the subtitles                 |
 
-### 4. Mark as Audio Card
+Set the starting modes with `subtitleStyle.primaryDefaultMode` and `secondarySub.defaultMode`. The full list of keys is on [Keyboard shortcuts](/shortcuts).
 
-After adding a word via Yomitan, press the audio card shortcut (`Ctrl/Cmd+Shift+A` by default, `shortcuts.markAudioCard`) to mark the card as an audio card. This sets the audio-card flag and fills sentence, image, and metadata fields alongside the full-subtitle audio clip.
+## Controller
 
-::: warning Requires Lapis/Kiku note type
-Audio card marking uses the same `ankiConnect.isLapis.sentenceCardModel` note type as sentence cards. See [Anki Integration - Sentence Cards](/anki-integration#sentence-cards-lapis) for setup.
-:::
+With a gamepad and keyboard-only mode on, you can mine without a mouse: move across words with the left stick, look up with `A`, mine with `X`, and close the popup with `B`. The keyboard keeps working alongside it. See [controller support](/usage#controller-support).
 
-### Field Grouping (Kiku)
+## Fix subtitle timing (subsync)
 
-If you mine the same word from different sentences, SubMiner can merge the cards instead of creating duplicates. This feature is designed for use with [Kiku](https://github.com/youyoumu/kiku) and similar note types that support grouped fields.
+If the subtitles are out of sync, press `Ctrl+Alt+S` to open the subsync dialog. It uses [alass](https://github.com/kaegi/alass) or [ffsubsync](https://github.com/smacke/ffsubsync), which you install separately.
 
-1. You add a word via Yomitan.
-2. SubMiner detects the new card and checks if a card with the same expression already exists.
-3. If a duplicate is found (this requires `ankiConnect.isKiku.fieldGrouping` to be set to `"auto"` or `"manual"`; it defaults to `"disabled"`):
-   - **Auto mode** (`ankiConnect.isKiku.fieldGrouping: "auto"`): Merges automatically. Both sentences, audio clips, and images are combined into the existing card. The duplicate is optionally deleted.
-   - **Manual mode** (`ankiConnect.isKiku.fieldGrouping: "manual"`): A modal appears showing both cards side by side. You choose which card to keep and preview the merged result before confirming.
+1. Pick the engine.
+2. For alass, pick a reference: a subtitle track with correct timing (the secondary track by default) or the video file.
+3. Pick the track to retime (the active primary track by default).
+4. Run it. SubMiner loads the retimed subtitle back into the same slot.
 
-See [Anki Integration - Field Grouping](/anki-integration#field-grouping-kiku) for configuration options, merge behavior, and modal keyboard shortcuts.
-
-## Overlay Model
-
-SubMiner uses one overlay window with modal surfaces. It carries two subtitle bars - a primary reading bar and a secondary translation/context bar - plus modal dialogs that open on top.
-
-Toggle the entire overlay window with `Alt+Shift+O` (global) or `y-t` (mpv plugin).
-
-### Primary Subtitle Layer
-
-The primary bar renders subtitles as tokenized hoverable word spans. Each word is a separate element with reading and headword data attached. This plane is styled independently from mpv subtitles and supports:
-
-- Word-level hover targets for Yomitan lookup
-- Auto pause/resume on subtitle hover (enabled by default via `subtitleStyle.autoPauseVideoOnHover`)
-- Auto pause/resume while the Yomitan popup is open (enabled by default via `subtitleStyle.autoPauseVideoOnYomitanPopup`)
-- Right-click to pause/resume
-- Right-click + drag to reposition subtitles
-- **Reading annotations** - known words, N+1 targets, character-name matches, JLPT levels, and frequency hits can all be visually highlighted
-
-### Secondary Subtitle Bar
-
-The secondary bar is a compact top-strip region in the same overlay window. It shows a secondary subtitle track (typically English) for translation/context while keeping the primary reading flow below. It is useful for:
-
-- 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).
-
-It is controlled by `secondarySub` configuration and shares its lifecycle with the main overlay window. Cycle which track feeds it with `Shift+J`.
-
-### Display Modes
-
-Both the primary and secondary subtitle bars share the same three visibility modes, and each can be changed independently at runtime:
-
-- **Hidden** - the bar is not shown.
-- **Visible** - the bar is always shown.
-- **Hover** - the bar is revealed only while you hover over the overlay.
-
-By default the **primary** bar is `visible` (`subtitleStyle.primaryDefaultMode`) and the **secondary** bar is `hover` (`secondarySub.defaultMode`).
-
-Cycle each bar's mode at runtime with its own shortcut:
-
-| Shortcut           | Action                                                   | Config key                     |
-| ------------------ | -------------------------------------------------------- | ------------------------------ |
-| `V`                | Cycle primary subtitle mode (hidden → visible → hover)   | overlay-local                  |
-| `Ctrl/Cmd+Shift+V` | Cycle secondary subtitle mode (hidden → visible → hover) | `shortcuts.toggleSecondarySub` |
-
-### Modal Surfaces
-
-Jimaku search, field-grouping, runtime options, and manual subsync open as modal surfaces on top of the same overlay window.
-
-## Looking Up Words
-
-1. Hover over the subtitle area - the overlay activates pointer events.
-2. Hover the word you want. SubMiner keeps per-token boundaries so Yomitan can target that token cleanly.
-3. Trigger Yomitan lookup with your configured lookup key/modifier (for example `Shift` if that is how your Yomitan profile is set up).
-4. Yomitan opens its lookup popup for the hovered token.
-5. From the popup, add the word to Anki.
-
-### Controller Workflow
-
-With a gamepad connected and keyboard-only mode enabled, the full mining loop works without a mouse or keyboard:
-
-1. **Navigate** - push the left stick left/right to move the token highlight across subtitle words.
-2. **Look up** - press `A` to trigger Yomitan lookup on the highlighted word.
-3. **Browse the popup** - push the left stick up/down to smooth-scroll through the Yomitan popup, or use the right stick for larger jumps.
-4. **Cycle audio** - press `R1` to move to the next dictionary audio entry, `L1` to play the current one.
-5. **Mine** - press `X` to create an Anki card for the current sentence (same as `Ctrl+S`).
-6. **Close** - press `B` to dismiss the Yomitan popup and return to subtitle navigation.
-7. **Pause/resume** - press `L3` (left stick click) to toggle mpv pause at any time.
-
-After controller support is enabled, the controller and keyboard can be used interchangeably - switching mid-session is seamless. Toggle keyboard-only mode on or off with `Y` on the controller.
-
-See [Usage - Controller Support](/usage#controller-support) for setup details and [Configuration - Controller Support](/configuration#controller-support) for the full mapping and tuning options.
-
-## Subtitle Sync (Subsync)
-
-If your subtitle file is out of sync with the audio, SubMiner can resynchronize it using [alass](https://github.com/kaegi/alass) or [ffsubsync](https://github.com/smacke/ffsubsync).
-
-1. Open the subsync modal from the overlay.
-2. Select the sync engine (alass or ffsubsync).
-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.
-
-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.
-
-Install the sync tools separately - see [Troubleshooting](/troubleshooting#subtitle-sync-subsync) if the tools are not found.
+For remote streams such as Jellyfin, only alass with a subtitle reference is available, because ffsubsync and the video reference need the local file. If the tools are not found, see [Troubleshooting](/troubleshooting#subtitle-sync-subsync).
 
 ## Texthooker
 
-SubMiner runs a local HTTP server at `http://127.0.0.1:5174` (fixed default port; overridable only via the mpv plugin's `texthooker_port` script-opt) that serves a texthooker UI. This allows external tools - such as a browser-based Yomitan instance - to receive subtitle text in real time.
+SubMiner can serve a texthooker page at `http://127.0.0.1:5174` that shows each subtitle line as it arrives, so you can do lookups in a browser instead of on the overlay. Start it with `texthooker.launchAtStartup`, the `--texthooker` flag, or the mpv plugin's `texthooker_enabled` option. Change the port with the plugin's `texthooker_port` option. To build your own client, see the [WebSocket / texthooker API](/websocket-texthooker-api).
 
-The texthooker page displays the current subtitle and updates as new lines arrive. This is useful if you prefer to do lookups in a browser rather than through the overlay's built-in Yomitan.
+## Related features
 
-If you want to build your own browser client, websocket consumer, or automation relay, see [WebSocket / Texthooker API & Integration](/websocket-texthooker-api).
-
-## Related Features
-
-These features support the mining loop but have their own dedicated pages:
-
-- **[Jimaku subtitle search](/jimaku-integration)** - search and download anime subtitle files directly from the overlay (`Ctrl+Shift+J` by default), then load them into mpv.
-- **[N+1 word highlighting](/subtitle-annotations#n-1-word-highlighting)** - cross-reference your Anki decks to highlight known words, making true N+1 sentences (exactly one unknown word) easy to spot during immersion.
-- **[Immersion tracking](/immersion-tracking)** - log watching and mining activity to a local database and view session times, words seen, and cards mined in the built-in stats dashboard.
-
-Next: [Anki Integration](/anki-integration) - field mapping, media generation, and card enrichment configuration.
+- [Jimaku](/jimaku-integration): search and download subtitle files from the overlay (`Ctrl+Shift+J`).
+- [Subtitle annotations](/subtitle-annotations): highlight known words, N+1 targets, JLPT levels, and frequency.
+- [Immersion tracking](/immersion-tracking): log watch time and cards mined, and view them in the stats dashboard.
diff --git a/docs-site/mpv-plugin.md b/docs-site/mpv-plugin.md
index 01112d8c..0f05818e 100644
--- a/docs-site/mpv-plugin.md
+++ b/docs-site/mpv-plugin.md
@@ -1,155 +1,112 @@
-# MPV Plugin
+# MPV plugin
 
-**What this is:** mpv is the video player SubMiner overlays subtitles on. The SubMiner mpv plugin is a small Lua script that runs _inside_ mpv and gives you in-player keybindings to control the SubMiner overlay (start/stop/toggle, skip intro, etc.) without leaving the player window.
+The SubMiner mpv plugin is a Lua script that runs inside mpv. It adds in-player keys to start, stop, and toggle the overlay, and it runs your SubMiner shortcuts from inside mpv.
 
-**Who needs this page:** Most users never touch the plugin directly - SubMiner-managed launches (the app, the `subminer` launcher, or the Windows shortcut) inject the bundled plugin automatically for that session, so there is nothing to install into mpv's global `scripts` directory. Read on if you launch mpv from another tool and want SubMiner's in-player controls, or you want to script mpv against SubMiner.
+## Setup
 
-The plugin ships as a modular Lua package under `plugin/subminer/` (entry point `main.lua`, which loads `init.lua` and sibling modules). Earlier releases shipped a single global `main.lua`; runtime loading replaces it.
+You usually do not install anything. Every SubMiner-managed launch (the app, the `subminer` launcher, and the Windows SubMiner mpv shortcut) loads the bundled plugin for that session only. Regular mpv playback is not affected.
 
-## Runtime Loading
+On Linux, the launcher's copy lives in `$XDG_DATA_HOME/SubMiner/plugin/subminer` (default `~/.local/share/SubMiner/plugin/subminer`), or under `/usr/local/share/SubMiner` or `/usr/share/SubMiner` for system installs. `subminer -u` and the tray updater keep it current.
 
-Launch mpv through the SubMiner app, the `subminer` launcher, or the packaged Windows SubMiner mpv shortcut. These paths pass mpv a bundled plugin path for that playback session only, leaving regular mpv playback untouched.
+To use the plugin when mpv is started by another program, load its `main.lua` and enable IPC:
 
-On Linux, the launcher-managed runtime plugin copy lives under the SubMiner data dir (`$XDG_DATA_HOME/SubMiner/plugin/subminer` by default, plus `/usr/local/share/SubMiner` or `/usr/share/SubMiner` for system installs). `subminer -u` and the tray updater keep that managed copy current. This is separate from mpv's global `scripts/` directory.
+```bash
+mpv --script="$HOME/.local/share/SubMiner/plugin/subminer/main.lua" \
+  --input-ipc-server=/tmp/subminer-socket video.mkv
+```
 
-If setup detects an older global SubMiner plugin in mpv's `scripts` directory, use **Remove legacy mpv plugin** in first-run setup. The global plugin is not needed once runtime loading is available.
-
-mpv must have IPC enabled for SubMiner to connect:
+To enable IPC for every mpv session, add it to `mpv.conf`:
 
 ```ini
-# ~/.config/mpv/mpv.conf
 input-ipc-server=/tmp/subminer-socket
 ```
 
-On Windows, use a named pipe instead:
+On Windows, use a named pipe:
 
 ```ini
 input-ipc-server=\\.\pipe\subminer-socket
 ```
 
-## Configuration (script-opts)
-
-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                                                            |
+If first-run setup finds an old SubMiner plugin in mpv's global `scripts` directory, click **Remove legacy mpv plugin**. It is no longer needed.
 
 ## Keybindings
 
-Most plugin actions use a `y` chord prefix - press `y`, then the second key (a "chord"):
+Most plugin keys are chords: press `y`, then the second key.
 
-| Chord           | Action                                 |
-| --------------- | -------------------------------------- |
-| `y-y`           | Open menu                              |
-| `y-s`           | Start overlay                          |
-| `y-S`           | Stop overlay                           |
-| `y-t`           | Toggle visible overlay                 |
-| `y-o`           | Open settings window                   |
-| `y-r`           | Restart overlay                        |
-| `y-c`           | Check status                           |
-| `y-h`           | Open session help / keybinding modal   |
-| `v`             | Toggle primary subtitle bar visibility |
-| `TAB` (default) | Skip intro (AniSkip)                   |
+| Key   | Action                                 |
+| ----- | -------------------------------------- |
+| `y-y` | Open the SubMiner menu                 |
+| `y-s` | Start the overlay                      |
+| `y-S` | Stop the overlay                       |
+| `y-t` | Toggle the visible overlay             |
+| `y-o` | Open the settings window               |
+| `y-r` | Restart the overlay                    |
+| `y-c` | Check status                           |
+| `y-h` | Open the session help modal            |
+| `v`   | Toggle SubMiner's primary subtitle bar |
 
-The AniSkip key is **not** a `y` chord and is not bound by the plugin: the SubMiner app binds it over the mpv IPC socket while it is connected. It defaults to `TAB` and is configurable via `mpv.aniskipButtonKey`. When a custom key (other than `TAB` or `y-k`) is configured, the legacy `y-k` chord is also bound as a fallback. See [AniSkip Integration](/aniskip-integration) for setup and details.
+`v` replaces mpv's own subtitle visibility toggle.
 
-The bare `v` binding is a forced mpv binding. It overrides mpv's default primary subtitle visibility toggle and routes the action to SubMiner's primary subtitle bar instead.
+The skip-intro key (`TAB` by default) comes from the SubMiner app, not the plugin. See [AniSkip integration](/aniskip-integration).
 
-## Shared Shortcuts (Session Bindings)
+The `y-y` menu lists Start overlay, Stop overlay, Toggle overlay, Open options, Restart overlay, Check status, and Stats. Press an item's number to run it. Stats only reminds you to press `` ` `` in the overlay.
 
-The `y-*` chords above are built into the plugin. Everything else you configure under [`shortcuts.*`](/shortcuts) - plus any custom [`keybindings`](/configuration) and the stats toggle/mark-watched keys - is **injected into mpv at runtime**, so the same shortcut works both inside mpv and in the SubMiner overlay. You do not edit any mpv config to enable them.
+## Your shortcuts in mpv
 
-How it works:
+Everything you set under [`shortcuts`](/shortcuts), your custom `keybindings`, and the stats keys also work while mpv has focus. SubMiner writes them to `session-bindings.json` in its config directory, and the plugin registers them as mpv keys. When you change a shortcut, mpv picks it up immediately.
 
-1. The SubMiner app compiles your configured shortcuts, custom keybindings, and stats keys into a normalized list and writes it to `session-bindings.json` in the SubMiner config directory.
-2. On load, the plugin reads that file and registers each entry as a forced mpv key binding, translating each accelerator into the matching mpv key name.
-3. When a binding fires, the plugin either runs a SubMiner action (by invoking the SubMiner binary with the corresponding CLI flag, e.g. `--mine-sentence`) or runs a raw mpv command, depending on what the shortcut maps to.
+`CommandOrControl` becomes `Cmd` on macOS and `Ctrl` elsewhere. Multi-line copy and mine shortcuts wait for a digit key `1` to `9`, and `Esc` cancels. If two shortcuts map to the same key, or a key has no mpv equivalent, SubMiner logs a warning and skips it.
 
-Because the bindings come from the same configuration the overlay uses, you maintain one set of shortcuts for both surfaces.
+## Script options
 
-Live updates: changing a shortcut in the app rewrites `session-bindings.json` and sends the plugin a `subminer-reload-session-bindings` script message, so mpv re-registers the bindings immediately - no mpv restart required.
+The plugin reads `script-opts` with the `subminer-` prefix, for example `--script-opts=subminer-backend=hyprland`. Managed launches set these from your SubMiner config, so edit the config instead. The shipped `plugin/subminer.conf` is empty on purpose, so it never overrides those values.
 
-Notes:
+| Option                                         | Default          | SubMiner config key          | What it does                                                          |
+| ---------------------------------------------- | ---------------- | ---------------------------- | --------------------------------------------------------------------- |
+| `binary_path`                                  | `""`             | `mpv.subminerBinaryPath`     | SubMiner binary. Empty uses [auto-detection](#binary-auto-detection). |
+| `socket_path`                                  | platform default | `mpv.socketPath`             | mpv IPC socket                                                        |
+| `backend`                                      | `auto`           | `mpv.backend`                | Window backend: `auto`, `hyprland`, `sway`, `x11`, `macos`            |
+| `auto_start`                                   | `no`             | `mpv.autoStartSubMiner`      | Start SubMiner when a file loads                                      |
+| `auto_start_visible_overlay`                   | `no`             | `auto_start_overlay`         | Show the overlay when auto-starting                                   |
+| `auto_start_pause_until_ready`                 | `yes`            | `mpv.pauseUntilOverlayReady` | Keep mpv paused until subtitles are ready                             |
+| `auto_start_pause_until_ready_timeout_seconds` | `30`             |                              | Resume anyway after this many seconds                                 |
+| `overlay_loading_osd`                          | `no`             |                              | Show a loading message while the overlay starts                       |
+| `texthooker_enabled`                           | `no`             |                              | Start the texthooker with the overlay                                 |
+| `texthooker_port`                              | `5174`           |                              | Texthooker port                                                       |
+| `osd_messages`                                 | `yes`            |                              | Show plugin status messages in mpv                                    |
+| `log_level`                                    | `info`           |                              | Plugin log level                                                      |
 
-- Accelerators are normalized per platform - `CommandOrControl` resolves to `Cmd` on macOS and `Ctrl` elsewhere.
-- Multi-line actions (`copySubtitleMultiple`, `mineSentenceMultiple`) register temporary `1`–`9` digit follow-up bindings after the trigger key, with `Esc` to cancel.
-- If two shortcuts compile to the same key, or an accelerator can't be mapped to an mpv key, the app logs a warning and skips that binding instead of registering a broken one.
+Without script options, `socket_path` is `/tmp/subminer-socket`, or `\\.\pipe\subminer-socket` on Windows. On Windows, the plugin also rewrites `/tmp/subminer-socket` to the named pipe.
 
-## Menu
+The table's defaults are the plugin's own. Managed launches override them from your config; see [Configuration](/configuration#mpv-launcher).
 
-Press `y-y` to open an interactive menu (rendered with mpv's console selector):
+## Binary auto-detection
+
+With `binary_path` empty, the plugin looks in these places:
+
+| Platform | Locations                                                                                                                                                                                                  |
+| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Linux    | `~/.local/bin/SubMiner.AppImage`, `/opt/SubMiner/SubMiner.AppImage`, `/usr/local/bin/SubMiner` or `subminer`, `/usr/bin/SubMiner` or `subminer`                                                            |
+| macOS    | `/Applications/SubMiner.app`, `~/Applications/SubMiner.app`                                                                                                                                                |
+| Windows  | A running SubMiner process, the App Paths registry entry, `SubMiner.exe` on `PATH`, then `%LOCALAPPDATA%\Programs\SubMiner`, `C:\Program Files\SubMiner`, `C:\Program Files (x86)\SubMiner`, `C:\SubMiner` |
+
+## Backend detection
+
+With `backend=auto`, the plugin picks the first match:
+
+1. macOS
+2. Hyprland (`HYPRLAND_INSTANCE_SIGNATURE` is set)
+3. Sway (`SWAYSOCK` is set)
+4. X11 (`XDG_SESSION_TYPE=x11` or `DISPLAY` is set)
+5. Otherwise X11, with a warning
+
+Native Wayland support covers only Hyprland and Sway. On other Wayland compositors, run both mpv and SubMiner under Xwayland and install `xdotool` and `xwininfo`.
+
+## Script messages
+
+Other mpv scripts, `input.conf`, or the mpv console can control the plugin:
 
 ```text
-SubMiner:
-1. Start overlay
-2. Stop overlay
-3. Toggle overlay
-4. Open options
-5. Restart overlay
-6. Check status
-7. Stats
-```
-
-Select an item by pressing its number.
-
-## Binary Auto-Detection
-
-When `binary_path` is empty, the plugin searches platform-specific locations:
-
-**Linux:**
-
-1. `~/.local/bin/SubMiner.AppImage`
-2. `/opt/SubMiner/SubMiner.AppImage`
-3. `/usr/local/bin/SubMiner` / `/usr/local/bin/subminer`
-4. `/usr/bin/SubMiner` / `/usr/bin/subminer`
-
-**macOS:**
-
-1. `/Applications/SubMiner.app/Contents/MacOS/SubMiner`
-2. `~/Applications/SubMiner.app/Contents/MacOS/SubMiner`
-
-**Windows:**
-
-A PowerShell system lookup runs first (running SubMiner process, registry App Paths, `Get-Command`), then static paths:
-
-1. `%LOCALAPPDATA%\Programs\SubMiner\SubMiner.exe` (the default per-user install location)
-2. `C:\Program Files\SubMiner\SubMiner.exe`
-3. `C:\Program Files (x86)\SubMiner\SubMiner.exe`
-4. `C:\SubMiner\SubMiner.exe`
-
-On Windows the plugin also normalizes a Unix-style `socket_path` (`/tmp/subminer-socket`) to the named pipe `\\.\pipe\subminer-socket` at runtime.
-
-## Backend Detection
-
-When `backend=auto`, the plugin detects the window manager:
-
-1. **macOS** - detected via platform or `OSTYPE`.
-2. **Hyprland** - detected via `HYPRLAND_INSTANCE_SIGNATURE`.
-3. **Sway** - detected via `SWAYSOCK`.
-4. **X11** - detected via `XDG_SESSION_TYPE=x11` or `DISPLAY`.
-5. **Fallback** - defaults to X11 with a warning.
-
-::: tip Wayland is compositor-specific
-Native Wayland support is only available for Hyprland and Sway. If you use a different Wayland compositor, auto-detection will fall back to X11 - both mpv and SubMiner must be running under Xwayland, and `xdotool` and `xwininfo` must be installed.
-:::
-
-## Script Messages
-
-The plugin can be controlled from other mpv scripts or the mpv command line using script messages:
-
-```
 script-message subminer-start
 script-message subminer-stop
 script-message subminer-toggle
@@ -157,46 +114,21 @@ script-message subminer-menu
 script-message subminer-options
 script-message subminer-restart
 script-message subminer-status
-script-message subminer-autoplay-ready
-script-message subminer-stats-toggle
-script-message subminer-visible-overlay-shown
-script-message subminer-visible-overlay-hidden
-script-message subminer-managed-subtitles-loading
-script-message subminer-overlay-loading-ready
-script-message subminer-reload-session-bindings
 ```
 
-The last five are primarily used by the SubMiner app to notify the plugin of overlay/loading state and to trigger session-binding reloads.
+`subminer-start` accepts overrides:
 
-The AniSkip messages (`subminer-skip-intro`, `subminer-aniskip-refresh`) still exist, but they are handled by the SubMiner app over the IPC socket rather than by the plugin - see [AniSkip Integration](/aniskip-integration#triggering-from-mpv).
-
-The `subminer-start` message accepts overrides:
-
-```
+```text
 script-message subminer-start backend=hyprland socket=/custom/path texthooker=no log-level=debug
 ```
 
-`log-level` here controls only logging verbosity passed to SubMiner.
-`--debug` is a separate app/dev-mode flag in the main CLI and should not be used here for logging.
+`log-level` sets SubMiner's log verbosity. Do not use `--debug` for this; it turns on the app's dev mode.
 
-## Lifecycle
+The plugin also handles messages the SubMiner app sends it (`subminer-autoplay-ready`, `subminer-visible-overlay-shown`, `subminer-visible-overlay-hidden`, `subminer-managed-subtitles-loading`, `subminer-overlay-loading-ready`, `subminer-reload-session-bindings`). You do not need to send these yourself. The AniSkip messages are listed on the [AniSkip page](/aniskip-integration#triggering-from-mpv).
 
-For how the plugin's auto-start fits into the full launch sequence - including when the launcher starts the overlay instead of the plugin - see [Playback Startup Flow](./architecture#playback-startup-flow).
+## Auto-start behavior
 
-- **File loaded**: If `auto_start=yes`, the plugin starts the overlay.
-- **Auto-start pause gate**: If `auto_start_visible_overlay=yes` and `auto_start_pause_until_ready=yes`, launcher starts mpv paused. On cold managed background startup, SubMiner opens the tray and visible overlay shell before tokenization warmups finish, then the plugin resumes playback after SubMiner reports tokenization-ready (with a 30-second timeout fallback).
-- **Duplicate auto-start events**: Repeated `file-loaded` hooks while overlay is already running are ignored for auto-start triggers (prevents duplicate start attempts).
-- **MPV shutdown**: The plugin clears its hover/OSD/gate state on shutdown; the overlay app notices the closed IPC socket and shuts itself down.
-- **Texthooker**: When `texthooker_enabled=yes`, the plugin appends `--texthooker` to the overlay start command so the app starts the texthooker server alongside the overlay.
-
-## Using with the `subminer` Wrapper
-
-The `subminer` wrapper script handles mpv launch, socket setup, and overlay lifecycle automatically. You do not need the plugin if you always use the wrapper.
-
-The plugin is useful when you:
-
-- Launch mpv from other tools (file managers, media centers).
-- Want on-demand overlay control without the wrapper.
-- Use mpv's built-in file browser or playlist features.
-
-You can install both - the plugin provides chord keybindings for convenience, while the wrapper handles the full lifecycle.
+- With `auto_start=yes`, the plugin starts SubMiner on each file load. Repeated loads while SubMiner is running do not start it again.
+- With `auto_start_visible_overlay=yes` and `auto_start_pause_until_ready=yes`, mpv stays paused until SubMiner reports that subtitles are ready, or until the timeout passes.
+- With `texthooker_enabled=yes`, the texthooker starts with the overlay.
+- When mpv quits, SubMiner sees the closed socket and shuts down its overlay.
diff --git a/docs-site/package.json b/docs-site/package.json
index 747f333d..83a425e5 100644
--- a/docs-site/package.json
+++ b/docs-site/package.json
@@ -5,10 +5,10 @@
   "description": "In-repo VitePress documentation site for SubMiner",
   "packageManager": "bun@1.3.5",
   "scripts": {
-    "docs:dev": "SUBMINER_DOCS_VERSION_LINK_ORIGIN=local bun run ../scripts/build-versioned-docs.ts && SUBMINER_DOCS_VERSION_LINK_ORIGIN=local SUBMINER_DOCS_VERSION_MANIFEST=\"$(bun run ../scripts/print-docs-version-manifest.ts)\" VITE_EXTRA_EXTENSIONS=jsonc vitepress dev --host 0.0.0.0 --port 5173 --strictPort",
+    "docs:dev": "VITE_EXTRA_EXTENSIONS=jsonc vitepress dev --host 0.0.0.0 --port 5173 --strictPort",
     "docs:build": "VITE_EXTRA_EXTENSIONS=jsonc vitepress build",
     "docs:preview": "VITE_EXTRA_EXTENSIONS=jsonc vitepress preview --host 0.0.0.0 --port 4173 --strictPort",
-    "test": "bun test plausible.test.ts index.assets.test.ts docs-sync.test.ts links.test.ts seo.test.ts .vitepress/theme/status-line.test.ts ../scripts/docs-versioning.test.ts"
+    "test": "bun test plausible.test.ts index.assets.test.ts archive-function.test.ts docs-sync.test.ts links.test.ts seo.test.ts .vitepress/theme/status-line.test.ts ../scripts/docs-versioning.test.ts"
   },
   "dependencies": {
     "@catppuccin/vitepress": "^0.1.2",
diff --git a/docs-site/plausible.test.ts b/docs-site/plausible.test.ts
index 25cbb2b2..905d0c5b 100644
--- a/docs-site/plausible.test.ts
+++ b/docs-site/plausible.test.ts
@@ -42,27 +42,11 @@ test('versioned docs reuse current VitePress internals for old page snapshots',
   expect(versionedBuildContents).toContain('overlayCurrentVitePress(snapshotDocsSite)');
 });
 
-test('versioned docs build reports archive cache hits and rebuilds', () => {
-  expect(versionedBuildContents).toContain(
-    'console.info(`[docs] archive cache key ${archiveCacheKey.slice(0, 12)}`)',
-  );
-  expect(versionedBuildContents).toContain('console.info(`[docs] cache hit ${version}`)');
-  expect(versionedBuildContents).toContain('console.info(`[docs] rebuilding archive ${version}`)');
-});
-
-test('versioned docs build deduplicates public assets and prunes stale workspaces', () => {
+test('versioned docs build deduplicates main public assets and removes build workspaces', () => {
   expect(versionedBuildContents).toContain('dedupeVersionedPublicAssets({');
-  expect(versionedBuildContents).toContain('pruneArchiveCacheGenerations({');
   expect(versionedBuildContents).toContain('rmSync(buildRoot, { recursive: true, force: true });');
 });
 
-test('versioned docs archive cache key ignores generated and test-only files', () => {
-  expect(versionedBuildContents).toContain('isSharedInternalsHashIgnoredPath(path)');
-  expect(versionedBuildContents).toContain('|| /\\.test\\.[cm]?[jt]s$/.test(path)');
-  expect(versionedBuildContents).toContain('process.env.SUBMINER_DOCS_VERSION_LINK_ORIGIN');
-  expect(versionedBuildContents).not.toContain('hash.update(String(stat.mode))');
-});
-
 test('docs builds exclude the internal README from VitePress page entries', () => {
   expect(docsConfigContents).toContain("srcExclude: ['subagents/**', 'README.md']");
 });
diff --git a/docs-site/public/assets/minecard-poster.jpg b/docs-site/public/assets/minecard-poster.jpg
index c338624e..68228757 100644
Binary files a/docs-site/public/assets/minecard-poster.jpg and b/docs-site/public/assets/minecard-poster.jpg differ
diff --git a/docs-site/public/assets/minecard.gif b/docs-site/public/assets/minecard.gif
deleted file mode 100644
index 989212b3..00000000
Binary files a/docs-site/public/assets/minecard.gif and /dev/null differ
diff --git a/docs-site/public/assets/minecard.jpg b/docs-site/public/assets/minecard.jpg
deleted file mode 100644
index 0734e8b1..00000000
Binary files a/docs-site/public/assets/minecard.jpg and /dev/null differ
diff --git a/docs-site/public/assets/minecard.mkv b/docs-site/public/assets/minecard.mkv
deleted file mode 100644
index 65cf05d7..00000000
Binary files a/docs-site/public/assets/minecard.mkv and /dev/null differ
diff --git a/docs-site/public/assets/minecard.mp4 b/docs-site/public/assets/minecard.mp4
index 1865a6de..94773a6a 100644
Binary files a/docs-site/public/assets/minecard.mp4 and b/docs-site/public/assets/minecard.mp4 differ
diff --git a/docs-site/public/assets/minecard.png b/docs-site/public/assets/minecard.png
deleted file mode 100644
index 3d8c767a..00000000
Binary files a/docs-site/public/assets/minecard.png and /dev/null differ
diff --git a/docs-site/public/assets/minecard.webm b/docs-site/public/assets/minecard.webm
index eaf7e42a..580e3bd3 100644
Binary files a/docs-site/public/assets/minecard.webm and b/docs-site/public/assets/minecard.webm differ
diff --git a/docs-site/public/assets/minecard.webp b/docs-site/public/assets/minecard.webp
index 97400630..f064dda6 100644
Binary files a/docs-site/public/assets/minecard.webp and b/docs-site/public/assets/minecard.webp differ
diff --git a/docs-site/public/config.example.jsonc b/docs-site/public/config.example.jsonc
index 1408eab7..22640179 100644
--- a/docs-site/public/config.example.jsonc
+++ b/docs-site/public/config.example.jsonc
@@ -6,6 +6,32 @@
  */
 {
 
+  // ==========================================
+  // Subtitle Selection
+  // Select primary and secondary mpv subtitle tracks from the overlay.
+  // Hot-reload: enabling or disabling updates the session shortcut immediately.
+  // ==========================================
+  "subtitleSelection": {
+    "enabled": false // Use the SubMiner modal to select primary and secondary subtitle tracks. When enabled, its shortcut overrides mpv subtitle selection. Values: true | false
+  }, // Select primary and secondary mpv subtitle tracks from the overlay.
+
+  // ==========================================
+  // Japanese Subtitle Generation
+  // Generate timed Japanese subtitles from local audio using whisper.cpp.
+  // Configure an existing GGML model path or explicitly download a SubMiner-managed model.
+  // Hot-reload: settings apply to the next generation or model download.
+  // ==========================================
+  "subtitleGeneration": {
+    "whisperPath": "", // Optional path override for whisper.cpp. Leave empty to find whisper-cli on PATH.
+    "modelPath": "", // Path to an existing multilingual whisper.cpp GGML model. Leave empty to use a SubMiner-managed model. A configured path always takes precedence.
+    "managedModel": "small", // Multilingual whisper.cpp model to use when modelPath is empty. Download it explicitly from the generation modal or launcher. Values: tiny | tiny-q5_1 | tiny-q8_0 | base | base-q5_1 | base-q8_0 | small | small-q5_1 | small-q8_0 | medium | medium-q5_0 | medium-q8_0 | large-v1 | large-v2 | large-v2-q5_0 | large-v2-q8_0 | large-v3 | large-v3-q5_0 | large-v3-turbo | large-v3-turbo-q5_0 | large-v3-turbo-q8_0
+    "threads": 4, // Positive integer CPU thread count for whisper.cpp Japanese transcription.
+    "ffmpegPath": "", // Optional FFmpeg path override for audio extraction. Leave empty to find ffmpeg on PATH.
+    "ffprobePath": "", // Optional FFprobe path override for audio tracks and timing. Leave empty to find ffprobe on PATH.
+    "vadModelPath": "", // Path to a whisper.cpp Silero VAD model. Enables dialogue-focused generation while retaining uncertain audible sections, which may include songs. Leave empty to transcribe the full audio.
+    "vadPath": "" // Optional speech detector executable override. With vadModelPath configured, leave empty to find whisper-vad-speech-segments or vad-speech-segments on PATH.
+  }, // Generate timed Japanese subtitles from local audio using whisper.cpp.
+
   // ==========================================
   // Visible Overlay Auto-Start
   // Show the visible subtitle overlay automatically after managed mpv playback starts SubMiner.
@@ -206,6 +232,8 @@
     "openRuntimeOptions": "CommandOrControl+Shift+O", // Accelerator that opens the runtime options modal.
     "openJimaku": "Ctrl+Shift+J", // Accelerator that opens the Jimaku subtitle search modal.
     "openTsukihime": "Ctrl+Shift+T", // Accelerator that opens the TsukiHime subtitle search modal (configured secondary/Japanese primary tabs).
+    "openSubtitleSelection": "g-s", // Open subtitle selection when enabled. Use g-s to press g then s. Set null to unbind.
+    "openSubtitleGeneration": "Ctrl+Shift+G", // Accelerator that opens the standalone Japanese subtitle generation modal.
     "openSessionHelp": "CommandOrControl+Slash", // Accelerator that opens the session help / keybinding cheatsheet.
     "openControllerSelect": "Alt+C", // Accelerator that opens the controller selection and learn-mode modal.
     "openControllerDebug": "Alt+Shift+C", // Accelerator that opens the controller debug modal with live axis/button readouts.
@@ -523,7 +551,7 @@
   // ==========================================
   // AnkiConnect Integration
   // Automatic Anki updates and media generation options.
-  // Hot-reload: ankiConnect.ai.enabled, media.normalizeAudio/mirrorMpvVolume, knownWords, nPlusOne, fields.word/audio/image/sentence/miscInfo, behavior.autoUpdateNewCards, isLapis.sentenceCardModel, isKiku.fieldGrouping, and lapisKiku.wordCardKind update live while SubMiner is running.
+  // Hot-reload: ankiConnect.ai.enabled, media.normalizeAudio/mirrorMpvVolume/reviewTiming, knownWords, nPlusOne, fields.word/audio/wordAudio/image/sentence/miscInfo, behavior.autoUpdateNewCards, isLapis.sentenceCardModel, isKiku.fieldGrouping, isSenren.fieldGrouping, and lapisKiku.wordCardKind update live while SubMiner is running.
   // Shared AI provider transport settings are read from top-level ai and typically require restart.
   // Most other AnkiConnect settings still require restart.
   // ==========================================
@@ -544,6 +572,7 @@
     "fields": {
       "word": "Expression", // Card field for the mined word or expression text.
       "audio": "ExpressionAudio", // Card field that receives generated sentence audio.
+      "wordAudio": "ExpressionAudio", // Existing word-audio field read to time the frozen first frame of animated images. This mapping is only used for synchronization.
       "image": "Picture", // Card field that receives the captured screenshot or animated image.
       "sentence": "Sentence", // Card field that receives the source sentence text.
       "miscInfo": "MiscInfo", // Card field that receives the miscellaneous info pattern (see ankiConnect.metadata.pattern).
@@ -569,9 +598,10 @@
       "syncAnimatedImageToWordAudio": true, // For animated AVIF images, prepend a frozen first frame matching the existing word-audio duration so motion starts with sentence audio. Values: true | false
       "normalizeAudio": true, // Normalize generated sentence audio loudness during media extraction. Changes apply live. Values: true | false
       "mirrorMpvVolume": true, // Apply mpv's current software volume curve to generated sentence audio. Changes apply live. Values: true | false
+      "reviewTiming": false, // Review and preview subtitle media timing before SubMiner creates or enriches a mined card. Values: true | false
       "audioPadding": 0, // Seconds of padding appended to both ends of generated sentence audio and animated AVIF clips.
       "fallbackDuration": 3, // Fallback clip duration in seconds when subtitle timing data is unavailable.
-      "maxMediaDuration": 30 // Maximum allowed media clip duration in seconds.
+      "maxMediaDuration": 30 // Maximum allowed media clip duration in seconds. 0 disables the cap.
     }, // Media setting.
     "knownWords": {
       "highlightEnabled": false, // Enable fast local highlighting for words already known in Anki. Values: true | false
@@ -606,6 +636,11 @@
       "fieldGrouping": "disabled", // Kiku duplicate-card field grouping mode. Values: auto | manual | disabled
       "deleteDuplicateInAuto": true // When Kiku field grouping is "auto", delete the duplicate source card after grouping completes. Values: true | false
     }, // Is kiku setting.
+    "isSenren": {
+      "enabled": false, // Enable Senren-specific duplicate handling (scene-switching field grouping, including miscInfo grouping). Mutually exclusive with isKiku.enabled. Values: true | false
+      "fieldGrouping": "auto", // Senren duplicate-card field grouping mode (scene switching). Values: auto | manual | disabled
+      "deleteDuplicateInAuto": true // When Senren field grouping is "auto", delete the duplicate source card after grouping completes. Values: true | false
+    }, // Is senren setting.
     "lapisKiku": {
       "wordCardKind": "word-and-sentence" // Card-type flag SubMiner marks on Kiku/Lapis word cards. Only one flag is set at a time; the others are cleared. Requires isKiku.enabled or isLapis.enabled. Values: word-and-sentence | click | sentence | audio | none
     } // Lapis kiku setting.
@@ -634,6 +669,16 @@
     "maxSearchResults": 10 // Maximum TsukiHime search results returned.
   }, // TsukiHime subtitle search configuration for Japanese primary and configured secondary subtitles. No API key required.
 
+  // ==========================================
+  // TMDB
+  // TMDB (The Movie Database) metadata for live-action dramas and movies in the stats Library: posters, synopses, and grouping by show.
+  // Hot-reload: TMDB changes apply to the next TMDB request.
+  // ==========================================
+  "tmdb": {
+    "apiKey": "", // Your own TMDB API key or read access token for live-action posters and synopses in the stats Library. Release builds bundle a project key, so set this only to use your own quota or when running from source (free under Settings > API on themoviedb.org).
+    "apiKeyCommand": "" // Shell command that prints the TMDB API key to stdout. Used instead of apiKey to avoid storing the key in plain text.
+  }, // TMDB (The Movie Database) metadata for live-action dramas and movies in the stats Library: posters, synopses, and grouping by show.
+
   // ==========================================
   // YouTube Playback Settings
   // Defaults for managed subtitle language preferences and YouTube subtitle loading.
diff --git a/docs-site/seo.test.ts b/docs-site/seo.test.ts
index 99980516..9b682fe0 100644
--- a/docs-site/seo.test.ts
+++ b/docs-site/seo.test.ts
@@ -1,7 +1,4 @@
 import { expect, test } from 'bun:test';
-import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import type { TransformContext } from 'vitepress';
 import docsConfig from './.vitepress/config';
@@ -63,19 +60,17 @@ test('main docs canonical uses /main/ and emits noindex', async () => {
 });
 
 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'],
+  ['v0.14.0', '/v/0.14.0/', 'https://docs.subminer.moe/v/0.14.0/usage'],
+  ['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) => {
+  async (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}`);
 
@@ -89,36 +84,19 @@ test.each([
       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 () => {
+test('archive nav keeps page links in-version and version links release-independent', async () => {
   const previousCwd = process.cwd();
   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;
-  const previousManifest = process.env.SUBMINER_DOCS_VERSION_MANIFEST;
-  const previousVersionLinkOrigin = process.env.SUBMINER_DOCS_VERSION_LINK_ORIGIN;
   process.chdir(docsSiteDir);
   process.env.SUBMINER_DOCS_CHANNEL = 'stable-archive';
   process.env.SUBMINER_DOCS_BASE = '/v/0.12.0/';
   process.env.SUBMINER_DOCS_VERSION = 'v0.12.0';
-  process.env.SUBMINER_DOCS_LATEST_STABLE = 'v0.14.0';
-  process.env.SUBMINER_DOCS_VERSION_LINK_ORIGIN = 'production';
-  process.env.SUBMINER_DOCS_VERSION_MANIFEST = JSON.stringify({
-    latestStable: 'v0.14.0',
-    channels: [
-      { label: 'Latest stable', path: '/' },
-      { label: 'main', path: '/main/' },
-    ],
-    versions: [
-      { version: 'v0.14.0', path: '/v/0.14.0/' },
-      { version: 'v0.12.0', path: '/v/0.12.0/' },
-    ],
-  });
   try {
     const { default: archiveConfig } = await import('./.vitepress/config?stable-archive-links');
 
@@ -131,39 +109,24 @@ test('stable archive theme links stay on the selected version', async () => {
       text: string;
       items?: Array<{ text: string; link: string }>;
     }>;
-    const configurationNav = nav.find((item) => item.text === 'Configuration');
-    const versionNav = nav.find((item) => item.text === 'v0.12.0');
-    const referenceSidebar = sidebar.find((item) => item.text === 'Reference');
-    const configurationSidebar = referenceSidebar?.items?.find(
-      (item) => item.text === 'Configuration',
-    );
+    const configurationSidebar = sidebar
+      .find((item) => item.text === 'Reference')
+      ?.items?.find((item) => item.text === 'Configuration');
 
-    expect(configurationNav?.link).toBe('/configuration');
+    expect(nav.find((item) => item.text === 'Configuration')?.link).toBe('/configuration');
     expect(configurationSidebar?.link).toBe('/configuration');
-    expect(versionNav?.items).toContainEqual({
-      text: 'Latest stable (v0.14.0)',
-      link: 'https://docs.subminer.moe/',
-      target: '_self',
-      noIcon: true,
-    });
-    expect(versionNav?.items).toContainEqual({
-      text: 'main',
-      link: 'https://docs.subminer.moe/main/',
-      target: '_self',
-      noIcon: true,
-    });
-    expect(versionNav?.items).toContainEqual({
-      text: 'v0.14.0',
-      link: 'https://docs.subminer.moe/v/0.14.0/',
-      target: '_self',
-      noIcon: true,
-    });
-    expect(versionNav?.items).toContainEqual({
-      text: 'v0.12.0',
-      link: 'https://docs.subminer.moe/v/0.12.0/',
-      target: '_self',
-      noIcon: true,
-    });
+    // Frozen archives must not embed the release list, or every new tag would
+    // invalidate them. They point at the root-only /versions page instead.
+    expect(nav.find((item) => item.text === 'v0.12.0')?.items).toEqual([
+      { text: 'Latest stable', link: 'https://docs.subminer.moe/', target: '_self', noIcon: true },
+      { text: 'main', link: 'https://docs.subminer.moe/main/', target: '_self', noIcon: true },
+      {
+        text: 'All versions',
+        link: 'https://docs.subminer.moe/versions',
+        target: '_self',
+        noIcon: true,
+      },
+    ]);
     expect(archiveConfig.themeConfig?.logo).toEqual({
       light: '/assets/SubMiner.png',
       dark: '/assets/SubMiner.png',
@@ -173,268 +136,9 @@ test('stable archive theme links stay on the selected version', async () => {
     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;
-    process.env.SUBMINER_DOCS_VERSION_MANIFEST = previousManifest;
-    process.env.SUBMINER_DOCS_VERSION_LINK_ORIGIN = previousVersionLinkOrigin;
   }
 });
 
-test('local stable archive version links stay on the dev server', async () => {
-  const previousCwd = process.cwd();
-  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;
-  const previousManifest = process.env.SUBMINER_DOCS_VERSION_MANIFEST;
-  const previousVersionLinkOrigin = process.env.SUBMINER_DOCS_VERSION_LINK_ORIGIN;
-  process.chdir(docsSiteDir);
-  process.env.SUBMINER_DOCS_CHANNEL = 'stable-archive';
-  process.env.SUBMINER_DOCS_BASE = '/v/0.10.0/';
-  process.env.SUBMINER_DOCS_VERSION = 'v0.10.0';
-  process.env.SUBMINER_DOCS_LATEST_STABLE = 'v0.14.0';
-  process.env.SUBMINER_DOCS_VERSION_LINK_ORIGIN = 'local';
-  process.env.SUBMINER_DOCS_VERSION_MANIFEST = JSON.stringify({
-    latestStable: 'v0.14.0',
-    channels: [
-      { label: 'Latest stable', path: '/' },
-      { label: 'main', path: '/main/' },
-    ],
-    versions: [
-      { version: 'v0.14.0', path: '/v/0.14.0/' },
-      { version: 'v0.10.0', path: '/v/0.10.0/' },
-    ],
-  });
-  try {
-    const { default: archiveConfig } = await import('./.vitepress/config?local-archive-links');
-
-    const nav = archiveConfig.themeConfig?.nav as Array<{
-      text: string;
-      items?: Array<{ text: string; link: string }>;
-    }>;
-    const versionNav = nav.find((item) => item.text === 'v0.10.0');
-
-    expect(versionNav?.items).toContainEqual({
-      text: 'Latest stable (v0.14.0)',
-      link: '../../',
-      target: '_self',
-      noIcon: true,
-    });
-    expect(versionNav?.items).toContainEqual({
-      text: 'main',
-      link: '../../main/',
-      target: '_self',
-      noIcon: true,
-    });
-    expect(versionNav?.items).toContainEqual({
-      text: 'v0.14.0',
-      link: '../0.14.0/',
-      target: '_self',
-      noIcon: true,
-    });
-    expect(versionNav?.items).toContainEqual({
-      text: 'v0.10.0',
-      link: './',
-      target: '_self',
-      noIcon: true,
-    });
-  } finally {
-    process.chdir(previousCwd);
-    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;
-    process.env.SUBMINER_DOCS_VERSION_MANIFEST = previousManifest;
-    process.env.SUBMINER_DOCS_VERSION_LINK_ORIGIN = previousVersionLinkOrigin;
-  }
-});
-
-test('dev docs version links use local targets for version route testing', async () => {
-  const previousCwd = process.cwd();
-  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;
-  const previousManifest = process.env.SUBMINER_DOCS_VERSION_MANIFEST;
-  const previousVersionLinkOrigin = process.env.SUBMINER_DOCS_VERSION_LINK_ORIGIN;
-  process.chdir(docsSiteDir);
-  delete process.env.SUBMINER_DOCS_CHANNEL;
-  delete process.env.SUBMINER_DOCS_BASE;
-  delete process.env.SUBMINER_DOCS_VERSION;
-  // Set explicitly (like the sibling version-nav tests) so this assertion stays
-  // pinned to the manifest under test instead of the config's fallback constant.
-  process.env.SUBMINER_DOCS_LATEST_STABLE = 'v0.14.0';
-  process.env.SUBMINER_DOCS_VERSION_LINK_ORIGIN = 'local';
-  process.env.SUBMINER_DOCS_VERSION_MANIFEST = JSON.stringify({
-    latestStable: 'v0.14.0',
-    channels: [
-      { label: 'Latest stable', path: '/' },
-      { label: 'main', path: '/main/' },
-    ],
-    versions: [
-      { version: 'v0.14.0', path: '/v/0.14.0/' },
-      { version: 'v0.12.0', path: '/v/0.12.0/' },
-      { version: 'v0.11.2', path: '/v/0.11.2/' },
-    ],
-  });
-  try {
-    const { default: devConfig } = await import('./.vitepress/config?dev-version-links');
-
-    const nav = devConfig.themeConfig?.nav as Array<{
-      text: string;
-      items?: Array<{ text: string; link: string }>;
-    }>;
-    const versionNav = nav.find((item) => item.text === 'v0.14.0');
-
-    expect(versionNav?.items).toContainEqual({
-      text: 'Latest stable (v0.14.0)',
-      link: '/',
-      target: '_self',
-      noIcon: true,
-    });
-    expect(versionNav?.items).toContainEqual({
-      text: 'main',
-      link: '/main/',
-      target: '_self',
-      noIcon: true,
-    });
-    expect(versionNav?.items).toContainEqual({
-      text: 'v0.12.0',
-      link: '/v/0.12.0/',
-      target: '_self',
-      noIcon: true,
-    });
-    expect(versionNav?.items?.map((item) => item.text)).toEqual([
-      'Latest stable (v0.14.0)',
-      'main',
-      'v0.14.0',
-      'v0.12.0',
-      'v0.11.2',
-    ]);
-  } finally {
-    process.chdir(previousCwd);
-    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;
-    process.env.SUBMINER_DOCS_VERSION_MANIFEST = previousManifest;
-    process.env.SUBMINER_DOCS_VERSION_LINK_ORIGIN = previousVersionLinkOrigin;
-  }
-});
-
-test('dev server redirects unserved version routes to production docs', () => {
-  let routeHandler:
-    | ((req: { url?: string }, res: DevRedirectResponse, next: () => void) => void)
-    | undefined;
-  const fakeServer = {
-    middlewares: {
-      use(handler: typeof routeHandler) {
-        routeHandler = handler;
-      },
-    },
-  };
-  const plugins = Array.isArray(docsConfig.vite?.plugins)
-    ? docsConfig.vite.plugins
-    : [docsConfig.vite?.plugins].filter(Boolean);
-  const redirectPlugin = plugins.find(
-    (plugin): plugin is { name: string; configureServer: (server: never) => void } =>
-      Boolean(plugin) &&
-      typeof plugin === 'object' &&
-      'name' in plugin &&
-      plugin.name === 'subminer-docs-local-version-redirects' &&
-      'configureServer' in plugin,
-  );
-  expect(redirectPlugin).toBeDefined();
-  redirectPlugin?.configureServer(fakeServer as never);
-
-  const response = new DevRedirectResponse();
-  let nextCalled = false;
-  routeHandler?.({ url: '/v/0.14.0/?from=dev' }, response, () => {
-    nextCalled = true;
-  });
-
-  expect(nextCalled).toBe(false);
-  expect(response.statusCode).toBe(302);
-  expect(response.headers.location).toBe('https://docs.subminer.moe/v/0.14.0/?from=dev');
-
-  const rootResponse = new DevRedirectResponse();
-  routeHandler?.({ url: '/configuration' }, rootResponse, () => {
-    nextCalled = true;
-  });
-  expect(rootResponse.ended).toBe(false);
-  expect(nextCalled).toBe(true);
-});
-
-test('dev server serves local archive files for local version links', async () => {
-  const previousVersionLinkOrigin = process.env.SUBMINER_DOCS_VERSION_LINK_ORIGIN;
-  const previousArchiveDir = process.env.SUBMINER_DOCS_LOCAL_ARCHIVE_DIR;
-  const archiveDir = mkdtempSync(join(tmpdir(), 'subminer-docs-archive-'));
-  mkdirSync(join(archiveDir, 'v/0.14.0'), { recursive: true });
-  writeFileSync(join(archiveDir, 'v/0.14.0/index.html'), '<h1>local archive</h1>');
-  process.env.SUBMINER_DOCS_VERSION_LINK_ORIGIN = 'local';
-  process.env.SUBMINER_DOCS_LOCAL_ARCHIVE_DIR = archiveDir;
-  try {
-    const { default: localDevConfig } = await import(
-      `./.vitepress/config?local-dev-redirects-${Date.now()}`
-    );
-    let routeHandler:
-      | ((req: { url?: string }, res: DevRedirectResponse, next: () => void) => void)
-      | undefined;
-    const fakeServer = {
-      middlewares: {
-        use(handler: typeof routeHandler) {
-          routeHandler = handler;
-        },
-      },
-    };
-    const plugins = Array.isArray(localDevConfig.vite?.plugins)
-      ? localDevConfig.vite.plugins
-      : [localDevConfig.vite?.plugins].filter(Boolean);
-    const redirectPlugin = plugins.find(
-      (plugin): plugin is { name: string; configureServer: (server: never) => void } =>
-        Boolean(plugin) &&
-        typeof plugin === 'object' &&
-        'name' in plugin &&
-        plugin.name === 'subminer-docs-local-version-redirects' &&
-        'configureServer' in plugin,
-    );
-    redirectPlugin?.configureServer(fakeServer as never);
-
-    const response = new DevRedirectResponse();
-    let nextCalled = false;
-    routeHandler?.({ url: '/v/0.14.0/?from=dev' }, response, () => {
-      nextCalled = true;
-    });
-
-    expect(nextCalled).toBe(false);
-    expect(response.statusCode).toBe(200);
-    expect(response.headers['content-type']).toBe('text/html; charset=utf-8');
-    expect(response.headers.location).toBeUndefined();
-    expect(response.body).toBe('<h1>local archive</h1>');
-  } finally {
-    process.env.SUBMINER_DOCS_VERSION_LINK_ORIGIN = previousVersionLinkOrigin;
-    process.env.SUBMINER_DOCS_LOCAL_ARCHIVE_DIR = previousArchiveDir;
-    rmSync(archiveDir, { recursive: true, force: true });
-  }
-});
-
-class DevRedirectResponse {
-  statusCode = 200;
-  headers: Record<string, string> = {};
-  ended = false;
-  body = '';
-
-  setHeader(name: string, value: string) {
-    this.headers[name.toLowerCase()] = value;
-  }
-
-  end(chunk?: string | Uint8Array) {
-    if (chunk) {
-      this.body = typeof chunk === 'string' ? chunk : new TextDecoder().decode(chunk);
-    }
-    this.ended = true;
-  }
-}
-
 test('docs sitemap excludes duplicate README page from indexable URLs', async () => {
   const items = [{ url: '' }, { url: 'README' }, { url: 'usage' }];
 
diff --git a/docs-site/shortcuts.md b/docs-site/shortcuts.md
index 645cd144..5ecde18e 100644
--- a/docs-site/shortcuts.md
+++ b/docs-site/shortcuts.md
@@ -1,169 +1,144 @@
-# Keyboard Shortcuts
+# Keyboard shortcuts
 
-This page is the complete reference for every keystroke SubMiner responds to. If you are just getting started, focus on the **Mining Shortcuts** and **Overlay Controls** sections - those cover the day-to-day mining loop. The rest can wait until you need them.
+Every key SubMiner responds to, with its default binding. `Ctrl/Cmd` means `Ctrl` on Windows and Linux and `Cmd` on macOS (`CommandOrControl` in config).
 
-A few terms used throughout:
+Shortcuts work when the overlay has focus. With the [mpv plugin](/mpv-plugin), `shortcuts.*` and `keybindings` entries also work while mpv has focus. If a key does nothing, click the video once. Set any shortcut to `null` to disable it. Changes to `shortcuts`, `keybindings`, and `subtitleSidebar` apply without a restart.
 
-- **Overlay** - the transparent SubMiner window that sits on top of mpv and shows the interactive subtitles. Most shortcuts only work while this window has focus (click the video once if a shortcut seems to do nothing).
-- **`Ctrl/Cmd`** - use `Ctrl` on Windows/Linux and `Cmd` (⌘) on macOS. In the config file this is written as `CommandOrControl`.
-- **Accelerator** - Electron's name for a shortcut string like `Alt+Shift+O`.
+## Global
 
-All shortcuts are configurable in `config.jsonc` under `shortcuts` and `keybindings`. Set any shortcut to `null` to disable it.
+| Shortcut      | Action                 | Config key                             |
+| ------------- | ---------------------- | -------------------------------------- |
+| `Alt+Shift+O` | Toggle visible overlay | `shortcuts.toggleVisibleOverlayGlobal` |
+| `Alt+Shift+Y` | Open Yomitan settings  | Fixed                                  |
 
-## App-Wide Shortcuts
+`Alt+Shift+Y` is registered with the OS and works from any app. If another app already uses it, SubMiner cannot take it and you cannot rebind it.
 
-| 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)               |
+## Mining
 
-::: 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.
-:::
+| Shortcut           | Action                                              | Config key                              |
+| ------------------ | --------------------------------------------------- | --------------------------------------- |
+| `Ctrl/Cmd+S`       | Mine current line as a sentence card                | `shortcuts.mineSentence`                |
+| `Ctrl/Cmd+Shift+S` | Mine several lines as one sentence card             | `shortcuts.mineSentenceMultiple`        |
+| `Ctrl/Cmd+C`       | Copy current line                                   | `shortcuts.copySubtitle`                |
+| `Ctrl/Cmd+Shift+C` | Copy several lines                                  | `shortcuts.copySubtitleMultiple`        |
+| `Ctrl/Cmd+V`       | Update last-added card from the clipboard           | `shortcuts.updateLastCardFromClipboard` |
+| `Ctrl/Cmd+G`       | Run the field grouping check on the last-added card | `shortcuts.triggerFieldGrouping`        |
+| `Ctrl/Cmd+Shift+A` | Mark last-added card as an audio card               | `shortcuts.markAudioCard`               |
 
-## Mining Shortcuts
+After a multi-line shortcut, press `1` to `9` for how many lines to combine, counting back from and including the current line. The prompt closes after `shortcuts.multiCopyTimeoutMs`.
 
-These work when the overlay window has focus.
+When text is selected in the [subtitle sidebar](/subtitle-sidebar), `Ctrl/Cmd+C` copies that selection instead.
 
-| Shortcut           | Action                                          | Config key                              |
-| ------------------ | ----------------------------------------------- | --------------------------------------- |
-| `Ctrl/Cmd+S`       | Mine current subtitle as sentence card          | `shortcuts.mineSentence`                |
-| `Ctrl/Cmd+Shift+S` | Mine multiple lines (press 1–9 to select count) | `shortcuts.mineSentenceMultiple`        |
-| `Ctrl/Cmd+C`       | Copy current subtitle text                      | `shortcuts.copySubtitle`                |
-| `Ctrl/Cmd+Shift+C` | Copy multiple lines (press 1–9 to select count) | `shortcuts.copySubtitleMultiple`        |
-| `Ctrl/Cmd+V`       | Update last Anki card from clipboard text       | `shortcuts.updateLastCardFromClipboard` |
-| `Ctrl/Cmd+G`       | Trigger field grouping (Kiku merge check)       | `shortcuts.triggerFieldGrouping`        |
-| `Ctrl/Cmd+Shift+A` | Mark last card as audio card                    | `shortcuts.markAudioCard`               |
+## Playback
 
-The multi-line shortcuts open a digit selector with a 3-second timeout (`shortcuts.multiCopyTimeoutMs`). Press `1`–`9` to select how many recent subtitle lines to combine. When the shortcut starts from mpv, SubMiner focuses the visible overlay for that selector instead of reserving the number keys in the mpv plugin.
+These are the default `keybindings` entries. Remap or disable them in the `keybindings` array.
 
-## Overlay Controls
+| Shortcut           | Action                                   |
+| ------------------ | ---------------------------------------- |
+| `Space`            | Pause or resume                          |
+| `F`                | Toggle fullscreen                        |
+| `J`                | Cycle primary subtitle track             |
+| `Shift+J`          | Cycle secondary subtitle track           |
+| `ArrowRight`       | Seek forward 5 seconds                   |
+| `ArrowLeft`        | Seek back 5 seconds                      |
+| `ArrowUp`          | Seek forward 60 seconds                  |
+| `ArrowDown`        | Seek back 60 seconds                     |
+| `Shift+H`          | Jump to previous subtitle                |
+| `Shift+L`          | Jump to next subtitle                    |
+| `Ctrl+Shift+Left`  | Shift subtitle delay to the previous cue |
+| `Ctrl+Shift+Right` | Shift subtitle delay to the next cue     |
+| `Z`                | Subtitle delay -100 ms                   |
+| `Shift+Z`          | Subtitle delay +100 ms                   |
+| `X`                | Subtitle delay +100 ms                   |
+| `Ctrl+Shift+H`     | Replay current subtitle, then pause      |
+| `Ctrl+Shift+L`     | Play next subtitle, then pause           |
+| `Ctrl+Alt+P`       | Open playlist browser                    |
+| `Ctrl+Alt+C`       | Open YouTube subtitle picker             |
+| `Q`                | Quit mpv                                 |
+| `Ctrl+W`           | Quit mpv                                 |
 
-These control playback and subtitle display. They require overlay window focus.
+Built into the overlay, not configurable:
 
-| Shortcut             | Action                                                     |
-| -------------------- | ---------------------------------------------------------- |
-| `Space`              | Toggle mpv pause                                           |
-| `F`                  | Toggle fullscreen                                          |
-| `V`                  | Cycle primary subtitle bar mode (hidden → visible → hover) |
-| `J`                  | Cycle primary subtitle track                               |
-| `Shift+J`            | Cycle secondary subtitle track                             |
-| `Ctrl+Alt+P`         | Open playlist browser for current directory + queue        |
-| `ArrowRight`         | Seek forward 5 seconds                                     |
-| `ArrowLeft`          | Seek backward 5 seconds                                    |
-| `ArrowUp`            | Seek forward 60 seconds                                    |
-| `ArrowDown`          | Seek backward 60 seconds                                   |
-| `Shift+H`            | Jump to previous subtitle                                  |
-| `Shift+L`            | Jump to next subtitle                                      |
-| `Ctrl+Shift+Left`    | Shift subtitle delay to previous subtitle cue              |
-| `Ctrl+Shift+Right`   | Shift subtitle delay to next subtitle cue                  |
-| `z`                  | Shift subtitles 100 ms earlier                             |
-| `Shift+Z`            | Delay subtitles by 100 ms                                  |
-| `x`                  | Delay subtitles by 100 ms                                  |
-| `Ctrl+Shift+H`       | Replay current subtitle (play to end, then pause)          |
-| `Ctrl+Shift+L`       | Play next subtitle (jump, play to end, then pause)         |
-| `Q`                  | Quit mpv                                                   |
-| `Ctrl+W`             | Quit mpv                                                   |
-| `Right-click`        | Toggle pause (outside subtitle area)                       |
-| `Right-click + drag` | Reposition subtitles (on subtitle area)                    |
+| Input                     | Action                                             |
+| ------------------------- | -------------------------------------------------- |
+| `V`                       | Cycle primary subtitle bar: hidden, visible, hover |
+| Right-click               | Pause or resume (outside the subtitle area)        |
+| Right-click + drag        | Move the subtitles                                 |
+| Drop files on the overlay | Replace the mpv playlist                           |
+| `Shift` + drop files      | Append to the mpv playlist                         |
 
-The mpv-command rows above (`Space`, `F`, `J`, `Shift+J`, the seek/sub-seek/sub-step/sub-delay keys, replay/play-next, and quit) are merged from the `keybindings` config array and can be remapped or disabled there. `V` and the mouse actions are built-in overlay behaviors and are not part of the `keybindings` array. The playlist browser opens a split overlay modal with sibling video files on the left and the live mpv playlist on the right.
+## Overlay features
 
-On macOS managed playback, SubMiner disables mpv's menu-bar shortcuts so configured SubMiner shortcuts like `Cmd+Shift+O` reach the mpv plugin instead of opening native mpv menu actions.
+| Shortcut           | Action                                                 | Config key                                 |
+| ------------------ | ------------------------------------------------------ | ------------------------------------------ |
+| `Ctrl/Cmd+Shift+V` | Cycle secondary subtitle bar: hidden, visible, hover   | `shortcuts.toggleSecondarySub`             |
+| `Ctrl/Cmd+Shift+O` | Open runtime options                                   | `shortcuts.openRuntimeOptions`             |
+| `Ctrl/Cmd+/`       | Open session help                                      | `shortcuts.openSessionHelp`                |
+| `Ctrl/Cmd+D`       | Open character dictionary manager                      | `shortcuts.openCharacterDictionaryManager` |
+| `Ctrl/Cmd+N`       | Toggle notification history                            | `shortcuts.toggleNotificationHistory`      |
+| `Ctrl/Cmd+A`       | Append the video path on the clipboard to the playlist | `shortcuts.appendClipboardVideoToQueue`    |
+| `Ctrl+Shift+J`     | Open Jimaku subtitle search                            | `shortcuts.openJimaku`                     |
+| `Ctrl+Shift+T`     | Open TsukiHime subtitle search                         | `shortcuts.openTsukihime`                  |
+| `Ctrl+Shift+G`     | Open Japanese subtitle generation                      | `shortcuts.openSubtitleGeneration`         |
+| `Ctrl+Alt+S`       | Open subtitle sync (subsync)                           | `shortcuts.triggerSubsync`                 |
+| `g` then `s`       | Pick primary and secondary subtitles (when enabled)    | `shortcuts.openSubtitleSelection`          |
+| `\`                | Toggle subtitle sidebar                                | `subtitleSidebar.toggleKey`                |
+| `` ` ``            | Toggle stats overlay                                   | `stats.toggleKey`                          |
+| `W`                | Mark video watched and play the next one in the queue  | `stats.markWatchedKey`                     |
+| `Alt+C`            | Open controller setup and remapping                    | `shortcuts.openControllerSelect`           |
+| `Alt+Shift+C`      | Open controller debug view                             | `shortcuts.openControllerDebug`            |
 
-Mouse-hover playback behavior is configured separately from shortcuts: `subtitleStyle.autoPauseVideoOnHover` defaults to `true` (pause on subtitle hover, resume on leave).
+The sidebar key has a separate mpv-side binding, `shortcuts.toggleSubtitleSidebar`. The sidebar only opens when SubMiner has parsed the active subtitle file. In the sidebar, `Enter` seeks to the focused line.
 
-## Subtitle & Feature Shortcuts
+The subtitle picker (`g` then `s`) is off until you turn it on in **Settings, Behavior, Subtitle Selection**. Press the second key within one second. If `g` already has an action in SubMiner or mpv, the sequence is disabled and a warning is shown. See [subtitle selection](/configuration#subtitle-selection).
 
-| 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`                     |
+## mpv plugin keys
 
-`shortcuts.openAnimetosho` remains accepted as a deprecated alias for `shortcuts.openTsukihime`. The current name takes precedence when both are configured.
+Press `y`, then the second key.
 
-The stats toggle is handled inside the focused visible overlay window. It is configurable through the top-level `stats.toggleKey` setting and defaults to `Backquote`.
+| Keys  | Action                     |
+| ----- | -------------------------- |
+| `y-y` | Open the SubMiner menu     |
+| `y-s` | Start the overlay          |
+| `y-S` | Stop the overlay           |
+| `y-t` | Toggle the visible overlay |
+| `y-o` | Open Yomitan settings      |
+| `y-r` | Restart the overlay        |
+| `y-c` | Show overlay status        |
+| `y-h` | Open session help          |
+| `v`   | Cycle primary subtitle bar |
 
-The subtitle sidebar toggle is overlay-local and only opens when SubMiner has a parsed cue list for the active subtitle source.
+The plugin's `v` replaces mpv's own subtitle visibility toggle. When the overlay has focus, `y` then `d` toggles DevTools.
 
-## Controller Shortcuts
+## Customizing
 
-These overlay-local shortcuts open controller utilities for the Chrome Gamepad API integration.
-
-| Shortcut      | Action                               | Configurable                     |
-| ------------- | ------------------------------------ | -------------------------------- |
-| `Alt+C`       | Open controller config + remap modal | `shortcuts.openControllerSelect` |
-| `Alt+Shift+C` | Open controller debug modal          | `shortcuts.openControllerDebug`  |
-
-Controller input only drives the overlay while keyboard-only mode is enabled. The controller mapping and tuning live under the top-level `controller` config block; keyboard-only mode still works normally without a controller.
-
-## MPV Plugin Chords
-
-When the mpv plugin is installed, all commands use a `y` chord prefix - press `y`, then the second key (the overlay-side chord times out after 1 second; the mpv plugin uses native mpv key sequences).
-
-| Chord | Action                                                     |
-| ----- | ---------------------------------------------------------- |
-| `y-y` | Open SubMiner menu (OSD)                                   |
-| `y-s` | Start overlay                                              |
-| `y-S` | Stop overlay                                               |
-| `y-t` | Toggle visible overlay                                     |
-| `v`   | Cycle primary subtitle bar mode (hidden → visible → hover) |
-| `y-o` | Open Yomitan settings                                      |
-| `y-r` | Restart overlay                                            |
-| `y-c` | Check overlay status                                       |
-| `y-h` | Open session help                                          |
-
-The bare `v` plugin binding intentionally overrides mpv's native primary subtitle visibility toggle so it cycles the SubMiner primary subtitle bar (hidden → visible → hover) instead.
-
-When the overlay has focus, press `y` then `d` to toggle DevTools (debugging helper).
-
-## Drag-and-Drop
-
-| Gesture                   | Action                                           |
-| ------------------------- | ------------------------------------------------ |
-| Drop file(s) onto overlay | Replace current mpv playlist with dropped files  |
-| `Shift` + drop file(s)    | Append all dropped files to current mpv playlist |
-
-## Customizing Shortcuts
-
-All `shortcuts.*` keys accept [Electron accelerator strings](https://www.electronjs.org/docs/latest/tutorial/keyboard-shortcuts), for example `"CommandOrControl+D"`. Use `null` to disable a shortcut.
+`shortcuts.*` values are [Electron accelerator strings](https://www.electronjs.org/docs/latest/tutorial/keyboard-shortcuts).
 
 ```jsonc
 {
   "shortcuts": {
     "mineSentence": "CommandOrControl+S",
-    "copySubtitle": "CommandOrControl+C",
-    "toggleVisibleOverlayGlobal": "Alt+Shift+O",
     "openJimaku": null, // disabled
   },
 }
 ```
 
-The `keybindings` array overrides or extends the overlay's built-in key handling for mpv commands:
+`keybindings` entries map a key to an mpv command. They are merged with the defaults above. Set `command` to `null` to disable a default.
 
 ```jsonc
 {
   "keybindings": [
-    { "key": "f", "command": ["cycle", "fullscreen"] },
     { "key": "m", "command": ["cycle", "mute"] },
     { "key": "MBTN_BACK", "command": ["sub-seek", -1] },
-    { "key": "MBTN_FORWARD", "command": ["sub-seek", 1] },
-    { "key": "Space", "command": null }, // disable default Space → pause
+    { "key": "Space", "command": null },
   ],
 }
 ```
 
-Mouse keybinding names are `MBTN_LEFT`, `MBTN_MID`, `MBTN_RIGHT`, `MBTN_BACK`, and `MBTN_FORWARD`.
+Mouse button names are `MBTN_LEFT`, `MBTN_MID`, `MBTN_RIGHT`, `MBTN_BACK`, and `MBTN_FORWARD`. See [keybindings](/configuration#keybindings) and [shortcuts configuration](/configuration#shortcuts-configuration) in the config reference.
 
-Both `shortcuts`, `keybindings`, and `subtitleSidebar` are [hot-reloadable](/configuration#hot-reload-behavior) - changes take effect without restarting SubMiner.
+## Automatic mpv bindings
+
+The overlay reads single-key bindings from the running mpv (`input.conf`, mpv defaults, and scripts). If SubMiner does not handle a key, it passes it to mpv. SubMiner shortcuts and `keybindings` entries win, including ones set to `null`. Keys are not forwarded while you type in a text field, use an overlay menu, or have a Yomitan popup open.
+
+Mouse buttons, keypad and media keys, and key sequences are not imported. Bindings imported this way do not appear in session help. If you add an mpv binding while SubMiner runs, refocus the overlay to pick it up.
diff --git a/docs-site/subtitle-annotations.md b/docs-site/subtitle-annotations.md
index c962dc5d..c8e3718e 100644
--- a/docs-site/subtitle-annotations.md
+++ b/docs-site/subtitle-annotations.md
@@ -1,190 +1,119 @@
-# Subtitle Annotations
+# Subtitle annotations
 
-SubMiner annotates subtitle tokens in real time as they appear in the overlay. Four annotation layers work together to surface useful context while you watch: **N+1 highlighting**, **character-name highlighting**, **frequency highlighting**, and **JLPT tagging**.
+SubMiner can color and underline words in the subtitle overlay: words you already know, the one new word in an N+1 line, common words, JLPT levels, and character names. Each layer is off by default and works on its own, so turn on only the ones you want.
 
-All four are opt-in and configured under `subtitleStyle`, `ankiConnect.knownWords`, and `ankiConnect.nPlusOne` in your config. They apply independently - you can enable any combination.
+Yomitan splits the subtitle into words, so your installed Yomitan dictionaries and their order decide where word boundaries fall. Grammar words such as particles (`は`), auxiliaries (`です`), and endings like `んです` stay hoverable but never get annotation colors.
 
-::: tip Tokenization
-SubMiner's primary tokenizer is Yomitan itself - subtitle text is tokenized based entirely on the dictionaries you have installed in Yomitan. Installing many large dictionaries can increase noise and slow down lookups, so be selective about which dictionaries you install and their priority order.
-:::
+Defaults for every key below are in the [configuration reference](/configuration).
 
-Before any of those layers render, SubMiner strips annotation metadata from tokens that are usually just subtitle glue or annotation noise. Standalone particles, auxiliaries, adnominals, common explanatory endings like `んです` / `のだ`, merged trailing quote-particle forms like `...って`, auxiliary-stem grammar tails like `そうだ` (MeCab POS3 `助動詞語幹`), repeated kana interjections, and similar non-lexical helper tokens remain hoverable in the subtitle text, but they render as plain tokens without known-word, N+1, frequency, JLPT, or name-match annotation styling.
+## Known words {#known-words}
 
-Kanji vocabulary that MeCab labels `名詞/非自立`, such as `日` or `以外`, remains content for every annotation layer. The `非自立` exclusion only suppresses kana grammar nouns such as `こと` and `もの`.
+Colors every word that already appears in your Anki decks, so you can see how much of a line you know.
 
-## N+1 Word Highlighting
+Needs: Anki running with AnkiConnect, and at least one deck in `ankiConnect.knownWords.decks`.
 
-N+1 highlighting identifies sentences where you know every word except one, making them ideal mining targets. When enabled, SubMiner builds a local cache of your known vocabulary from Anki and highlights tokens accordingly.
-
-**How it works:**
-
-1. SubMiner queries your configured Anki decks for expression/word fields such as `Expression` or `Word`.
-2. The results are cached locally (`known-words-cache.json`) and refreshed on a configurable interval.
-3. When a subtitle line appears, each token is checked against the cache.
-4. If exactly one unknown word remains in the sentence, it is highlighted with `subtitleStyle.nPlusOneColor` (default: `#c6a0f6`).
-5. Already-known tokens can optionally display in `subtitleStyle.knownWordColor` (default: `#a6da95`).
-
-**Key settings:**
-
-| Option                                    | Default      | Description                                              |
-| ----------------------------------------- | ------------ | -------------------------------------------------------- |
-| `ankiConnect.knownWords.highlightEnabled` | `false`      | Enable known-word cache lookups used by N+1 highlighting |
-| `ankiConnect.knownWords.refreshMinutes`   | `1440`       | Minutes between Anki cache refreshes                     |
-| `ankiConnect.knownWords.decks`            | `{}`         | Deck→fields map for known-word cache queries             |
-| `ankiConnect.knownWords.matchMode`        | `"headword"` | `"headword"` (dictionary form) or `"surface"` (raw text) |
-| `ankiConnect.nPlusOne.enabled`            | `false`      | Enable N+1 target highlighting                           |
-| `ankiConnect.nPlusOne.minSentenceWords`   | `3`          | Minimum tokens in a sentence for N+1 to trigger          |
-| `subtitleStyle.nPlusOneColor`             | `#c6a0f6`    | Color for the single unknown target word                 |
-| `subtitleStyle.knownWordColor`            | `#a6da95`    | Color for already-known tokens                           |
-
-Prefer expression/word fields for `ankiConnect.knownWords.decks`. Reading-only fields can mark unrelated homophones as known, so only include them when that tradeoff is intentional.
-
-::: tip
-Set `refreshMinutes` to `1440` (24 hours) for daily sync if your Anki collection is large.
-:::
-
-## Known-Word Maturity Highlighting
-
-Instead of one color for every known word, maturity highlighting tints each known token by the review state of its Anki cards (like asbplayer), giving an at-a-glance sense of how much of a line is solidly learned.
-
-**How it works:**
-
-1. During the known-word cache refresh, SubMiner classifies each note with Anki search filters (`prop:ivl`, `is:learn`) - no extra card data is downloaded.
-2. Each note gets the tier of its **most mature** card: `mature` (in review, interval ≥ threshold), `young` (in review, interval below the threshold), `learning` (in the learning or relearning queue), or `new` (never studied). The buckets are disjoint, matching Anki's own card counts: a lapsed card in relearning counts as `learning`, not `young`, even though its interval is ≥ 1 day. A note with a mature card plus a relearning card still shows `mature`.
-3. A word matched by several notes takes the most mature tier among them, with the same reading-aware matching as regular known-word highlighting.
-4. Known tokens render in the tier color instead of `subtitleStyle.knownWordColor`; if tier data is missing for a match, the token falls back to the single known-word color.
-
-**Key settings:**
-
-| Option                                           | Default   | Description                                                           |
-| ------------------------------------------------ | --------- | --------------------------------------------------------------------- |
-| `ankiConnect.knownWords.maturityEnabled`         | `false`   | Color known words by card maturity (requires known-word highlighting) |
-| `ankiConnect.knownWords.matureThresholdDays`     | `21`      | Card interval in days at which a word counts as mature                |
-| `subtitleStyle.knownWordMaturityColors.new`      | `#ee99a0` | Tier color for never-reviewed cards                                   |
-| `subtitleStyle.knownWordMaturityColors.learning` | `#b7bdf8` | Tier color for cards in the learning/relearning queue                 |
-| `subtitleStyle.knownWordMaturityColors.young`    | `#91d7e3` | Tier color for young review cards                                     |
-| `subtitleStyle.knownWordMaturityColors.mature`   | `#a6da95` | Tier color for mature cards                                           |
-
-Changing `maturityEnabled` or the threshold triggers a full known-word cache refresh so tiers are refetched, as does upgrading to a build that revises the tier rules.
-
-How often the `learning` color appears depends on your deck preset: with no relearning steps configured, a lapsed card returns straight to review and shows `young` instead.
-
-While maturity highlighting is on, the session help color legend replaces its single "Known words" swatch with one row per tier (new, learning, young, mature).
-
-**Checking the colors you actually see:**
-
-Tiers are only as fresh as the last known-word cache refresh (`ankiConnect.knownWords.refreshMinutes`), so a card that crosses the mature threshold mid-day keeps its old color until the next refresh. To check a whole episode offline, run the verifier against its subtitle file:
-
-```sh
-bun run verify-known-word-highlights:electron -- --input /path/to/episode.ja.srt --audit
+```jsonc
+{
+  "ankiConnect": {
+    "knownWords": {
+      "highlightEnabled": true,
+      "decks": { "Kaishi 1.5k": ["Word"] },
+    },
+  },
+}
 ```
 
-It tokenizes every cue through the real Yomitan/MeCab pipeline with your live known-word cache, prints each line in your configured tier colors, and summarizes the tier counts. `--audit` re-derives each highlighted tier from live Anki card data (`notesInfo` + `cardsInfo` intervals) and lists any token whose color disagrees, with the note ids and intervals behind it. Electron locks the Yomitan profile, so quit SubMiner first or pass `--profile-copy` to run against a scratch copy. Other useful flags: `--refresh` (refresh the cache first), `--limit <n>`, `--quiet`, `--json`.
+Map each deck to its expression or word field. SubMiner also reads the note's reading field when it has one, so a known word only matches in the reading its card teaches.
 
-## Character-Name Highlighting
+| Key                                               | What it does                                                        |
+| ------------------------------------------------- | ------------------------------------------------------------------- |
+| `ankiConnect.knownWords.highlightEnabled`         | Turn known-word coloring on                                         |
+| `ankiConnect.knownWords.decks`                    | Deck name to list of fields to read                                 |
+| `ankiConnect.knownWords.matchMode`                | `headword` matches the dictionary form, `surface` the text as shown |
+| `ankiConnect.knownWords.refreshMinutes`           | How often the known-word list is re-read from Anki                  |
+| `ankiConnect.knownWords.addMinedWordsImmediately` | Count a word as known as soon as you mine it                        |
+| `subtitleStyle.knownWordColor`                    | Color for known words                                               |
 
-Character-name matches are built from the active merged SubMiner character dictionary, which auto-syncs character data from AniList for your recently-watched titles. When the current AniList media ID is known, SubMiner ignores loaded entries from other titles for subtitle name matching and inline portraits. Matching names are highlighted in subtitles and become available for hover-driven Yomitan character profiles - portraits, roles, voice actors, and biographical detail.
+### Known-word maturity highlighting
 
-**How it works:**
+Colors known words by how well you know them instead of using one color. Each word gets the tier of its most mature card:
 
-1. Subtitles are tokenized, then candidate name tokens are matched against the character dictionary via Yomitan's scanning pipeline.
-2. Matching tokens receive a dedicated style distinct from N+1 and frequency layers.
-3. This layer can be independently toggled with `subtitleStyle.nameMatchEnabled`.
-4. When `subtitleStyle.nameMatchImagesEnabled` is also enabled, SubMiner shows the cached AniList portrait beside matched names.
+- `new`: never studied
+- `learning`: in the learning or relearning queue
+- `young`: in review, interval below the threshold
+- `mature`: in review, interval at or above `ankiConnect.knownWords.matureThresholdDays`
 
-**Key settings:**
+Turn it on with `ankiConnect.knownWords.maturityEnabled` (known-word highlighting must also be on). Set the colors under `subtitleStyle.knownWordMaturityColors` (`new`, `learning`, `young`, `mature`).
 
-| Option                                 | Default   | Description                                      |
-| -------------------------------------- | --------- | ------------------------------------------------ |
-| `subtitleStyle.nameMatchEnabled`       | `false`   | Enable character-name token highlighting         |
-| `subtitleStyle.nameMatchImagesEnabled` | `false`   | Show small AniList portraits next to name tokens |
-| `subtitleStyle.nameMatchColor`         | `#f5bde6` | Color used for character-name matches            |
+Tiers update when the known-word list refreshes, so a card that turns mature today keeps its old color until the next refresh. If your deck has no relearning steps, lapsed cards go straight back to review and show as `young`.
 
-For full details on dictionary generation, name variant expansion, auto-sync lifecycle, and configuration, see the dedicated [Character Dictionary](/character-dictionary) page.
+## N+1 word highlighting
 
-## Frequency Highlighting
+An N+1 line has exactly one word you don't know. It is the easiest kind of sentence to mine, because the rest of the line gives you context. SubMiner colors that one unknown word.
 
-Frequency highlighting colors tokens based on how common they are, using dictionary frequency rank data. This helps you spot high-value vocabulary at a glance. For each token, ranks from the installed Yomitan frequency dictionaries are consulted in priority order: the highest-priority dictionary that has the term wins, lower-priority dictionaries fill in terms it lacks, and occurrence-based dictionaries are skipped.
+Needs: the same Anki setup as [known words](#known-words) (`ankiConnect.knownWords.decks`). Known-word coloring itself can stay off.
 
-**Modes:**
+| Key                                     | What it does                            |
+| --------------------------------------- | --------------------------------------- |
+| `ankiConnect.nPlusOne.enabled`          | Turn N+1 highlighting on                |
+| `ankiConnect.nPlusOne.minSentenceWords` | Skip lines shorter than this many words |
+| `subtitleStyle.nPlusOneColor`           | Color for the unknown word              |
 
-- **Single** - all highlighted tokens share one color (`singleColor`).
-- **Banded** - tokens are assigned to five color bands from most common to least common within the `topX` window.
+## Frequency highlighting
 
-SubMiner looks up each token's `frequencyRank` from `term_meta_bank_*.json` files. Only tokens with a positive rank at or below `topX` are highlighted.
+Colors words by how common they are, so a rare word in an easy line stands out.
 
-**Key settings:**
+Needs: at least one frequency dictionary installed in Yomitan. When several are installed, SubMiner uses them in your Yomitan priority order. Occurrence-count dictionaries are skipped. You can also point `sourcePath` at a folder of Yomitan-format frequency files as a fallback.
 
-| Option                                           | Default      | Description                                                      |
-| ------------------------------------------------ | ------------ | ---------------------------------------------------------------- |
-| `subtitleStyle.frequencyDictionary.enabled`      | `false`      | Enable frequency highlighting                                    |
-| `subtitleStyle.frequencyDictionary.topX`         | `10000`      | Max frequency rank to highlight                                  |
-| `subtitleStyle.frequencyDictionary.mode`         | `"single"`   | `"single"` or `"banded"`                                         |
-| `subtitleStyle.frequencyDictionary.matchMode`    | `"headword"` | `"headword"` or `"surface"`                                      |
-| `subtitleStyle.frequencyDictionary.singleColor`  | `#f5a97f`    | Color for single mode                                            |
-| `subtitleStyle.frequencyDictionary.bandedColors` | 5 colors[^1] | Array of five hex colors for banded mode                         |
-| `subtitleStyle.frequencyDictionary.sourcePath`   | `""`         | Custom path to frequency dictionary root (empty = auto-discover) |
+| Key                                              | What it does                                                           |
+| ------------------------------------------------ | ---------------------------------------------------------------------- |
+| `subtitleStyle.frequencyDictionary.enabled`      | Turn frequency highlighting on                                         |
+| `subtitleStyle.frequencyDictionary.topX`         | Only color words whose rank is this number or lower (1 is most common) |
+| `subtitleStyle.frequencyDictionary.mode`         | `single` uses one color, `banded` splits the range into five colors    |
+| `subtitleStyle.frequencyDictionary.singleColor`  | Color for `single` mode                                                |
+| `subtitleStyle.frequencyDictionary.bandedColors` | Five colors for `banded` mode, most common first                       |
+| `subtitleStyle.frequencyDictionary.matchMode`    | `headword` or `surface`, as for known words                            |
+| `subtitleStyle.frequencyDictionary.sourcePath`   | Optional folder of frequency files                                     |
 
-[^1]: Default banded palette (most common → least common): `#ed8796`, `#f5a97f`, `#f9e2af`, `#8bd5ca`, `#8aadf4`.
+## JLPT tagging
 
-When `sourcePath` is omitted, SubMiner searches default install/runtime locations for `frequency-dictionary` directories automatically.
+Underlines each word in a color for its JLPT level, N1 to N5. The JLPT word lists ship with SubMiner, so there is nothing to install.
 
-::: info
-Frequency highlighting skips tokens that look like non-lexical noise (kana reduplication, short kana endings like `っ`), even when dictionary ranks exist. For merged kana tokens, SubMiner keeps a rank when the dictionary headword reading covers the full token (for example, `かと言って` / `かといって`), while grammar wrapped around a shorter lemma remains unannotated.
-:::
+| Key                                   | What it does                   |
+| ------------------------------------- | ------------------------------ |
+| `subtitleStyle.enableJlpt`            | Turn JLPT underlines on        |
+| `subtitleStyle.jlptColors.N1` to `N5` | Underline color for each level |
 
-::: info
-Frequency, JLPT, and N+1 metadata are only shown for tokens that survive the subtitle-annotation noise filter. Standalone grammar tokens like `は`, `です`, and `この` are intentionally left unannotated even if a dictionary can assign them metadata.
-:::
+## Character names
 
-## JLPT Tagging
+Colors character names from the current show and lets you hover them for a portrait, role, and voice actor.
 
-JLPT tagging adds colored underlines to tokens based on their JLPT level (N1–N5), giving you an at-a-glance sense of difficulty distribution in each subtitle line.
+Needs: the [character dictionary](/character-dictionary), which SubMiner builds from AniList when you turn this on.
 
-**How it works:**
+| Key                                    | What it does                                    |
+| -------------------------------------- | ----------------------------------------------- |
+| `subtitleStyle.nameMatchEnabled`       | Build the character dictionary and color names  |
+| `subtitleStyle.nameMatchImagesEnabled` | Show a small portrait next to each matched name |
+| `subtitleStyle.nameMatchColor`         | Color for character names                       |
 
-SubMiner loads offline `term_meta_bank_*.json` files from `vendor/yomitan-jlpt-vocab` and matches each token's headword against the bank entries. Tokens with a recognized JLPT level receive a colored underline.
+## Toggling during playback
 
-**Default colors:**
+Open the runtime options palette (`Ctrl/Cmd+Shift+O`) to switch these without restarting:
 
-| Level | Color     | Preview |
-| ----- | --------- | ------- |
-| N1    | `#ed8796` | Red     |
-| N2    | `#f5a97f` | Peach   |
-| N3    | `#f9e2af` | Yellow  |
-| N4    | `#8bd5ca` | Teal    |
-| N5    | `#8aadf4` | Blue    |
+- known-word highlighting, maturity colors, and known-word match mode
+- N+1 highlighting
+- JLPT tagging
+- frequency highlighting
 
-All colors are customizable via the `subtitleStyle.jlptColors` object.
+Character names are toggled in the config file or the Settings window. Changes apply from the next subtitle line.
 
-**Key settings:**
+## When layers overlap
 
-| Option                             | Default   | Description                   |
-| ---------------------------------- | --------- | ----------------------------- |
-| `subtitleStyle.enableJlpt`         | `false`   | Enable JLPT underline styling |
-| `subtitleStyle.jlptColors.N1`–`N5` | see above | Per-level underline colors    |
+If one word matches several layers, the first match in this list sets its color:
 
-## Runtime Toggles
+1. Character name (also removes N+1, frequency, and JLPT marks)
+2. N+1 target
+3. Known word
+4. Frequency
 
-These annotation layers can be toggled at runtime via the runtime options palette (`Ctrl/Cmd+Shift+O`) without restarting:
-
-- `ankiConnect.knownWords.highlightEnabled` (`On` / `Off`)
-- `ankiConnect.knownWords.maturityEnabled` (`On` / `Off`)
-- `ankiConnect.knownWords.matchMode`
-- `ankiConnect.nPlusOne.enabled` (`On` / `Off`)
-- `subtitleStyle.enableJlpt` (`On` / `Off`)
-- `subtitleStyle.frequencyDictionary.enabled` (`On` / `Off`)
-
-(Character-name matching, `subtitleStyle.nameMatchEnabled`, is toggled through config or the Settings window, not the runtime palette.)
-
-Toggles only apply to new subtitle lines after the change - the currently displayed line is not re-tokenized in place.
-
-## Rendering Priority
-
-When multiple annotations apply to the same token, the visual priority is:
-
-1. **Character-name match** (highest) - dictionary-driven character-name token styling; it clears the token's N+1, frequency, and JLPT annotations
-2. **N+1 target** - the single unknown word in an N+1 sentence
-3. **Known-word color** - already-learned token tint (per-tier maturity colors when `maturityEnabled` is on)
-4. **Frequency highlight** - common-word coloring (not applied when a higher layer already matched)
-5. **JLPT underline** - level-based underline (stacks with N+1/known/frequency since it uses underline rather than text color, but not with a character-name match)
+JLPT is an underline, so it shows alongside any of these except a character name.
diff --git a/docs-site/subtitle-generation.md b/docs-site/subtitle-generation.md
new file mode 100644
index 00000000..0c2da357
--- /dev/null
+++ b/docs-site/subtitle-generation.md
@@ -0,0 +1,85 @@
+# Japanese subtitle generation
+
+When a video has no Japanese subtitles, SubMiner can transcribe its audio into a Japanese SRT with [whisper.cpp](https://github.com/ggml-org/whisper.cpp). Everything runs on your computer. You only need internet access to download a model.
+
+## Setup
+
+1. Install whisper.cpp's `whisper-cli` and FFmpeg (including `ffprobe`). SubMiner downloads models but not these programs.
+2. Make sure they are on your `PATH`, or set their paths under **Settings > Integrations > Japanese Subtitle Generation** (`whisperPath`, `ffmpegPath`, `ffprobePath`).
+3. Pick a model. Either choose one in the generation modal and click **Download model**, or set `subtitleGeneration.modelPath` to a multilingual whisper.cpp GGML `.bin` file you already have. English-only models and Python Whisper checkpoints do not work.
+
+Downloaded models go to `models/whisper/` next to your SubMiner config file. A configured `modelPath` always wins over the modal's choice.
+
+The modal's **Local tools** section lists anything missing. After you install a tool or change a path, click **Check again**.
+
+## Generating from the overlay
+
+1. Open a local video in mpv and select its Japanese audio track.
+2. Press `Ctrl+Shift+G`. If the subtitle sidebar is empty, its **Generate Japanese subtitles** button opens the same modal.
+3. Pick a model and download it if needed.
+4. Optionally check **Focus on spoken dialogue** (see below).
+5. Click **Generate subtitles**.
+
+The modal shows progress. **Cancel** stops the job. Closing the modal lets the job keep running, and reopening it shows the progress.
+
+SubMiner saves `<video>.ja.generated.srt` next to the video and adds a number if that name is taken. If the same file is still playing, it loads the subtitles and resets the subtitle delay.
+
+Change the shortcut with `shortcuts.openSubtitleGeneration`.
+
+## Generating from the launcher
+
+```bash
+subminer generate-subs                                  # current mpv file and audio track
+subminer generate-subs episode.mkv --download-model
+subminer generate-subs episode.mkv --model-path /path/to/ggml-small.bin
+```
+
+| Flag                     | What it does                                                  |
+| ------------------------ | ------------------------------------------------------------- |
+| `--model <name>`         | Use this managed model, such as `small` or `large-v3-turbo`   |
+| `--download-model`       | Download the managed model if it is missing                   |
+| `--model-path <path>`    | Use an existing model file                                    |
+| `--audio-stream <index>` | Pick an audio stream by its absolute FFmpeg index             |
+| `--output <path>`        | Write to this SRT path. Existing files are never overwritten. |
+
+With a file argument, SubMiner uses the audio stream tagged Japanese, or the first stream. `Ctrl+C` cancels.
+
+## Choosing a model
+
+The modal recommends **large-v3-turbo** if it finds an NVIDIA GPU (`nvidia-smi`) and your `whisper-cli` can use CUDA. Otherwise it recommends **small**. AMD, Vulkan, and Apple GPUs do not trigger the turbo recommendation. The recommendation does not change your settings.
+
+| Model                  | Tradeoff                                        |
+| ---------------------- | ----------------------------------------------- |
+| tiny, base             | Fast and small, more recognition errors         |
+| small                  | Balanced quality and CPU time                   |
+| medium, large-v1/v2/v3 | More accurate, needs more memory and time       |
+| large-v3-turbo         | Faster than large-v3 with a small accuracy loss |
+
+Quantized variants (`-q5_0`, `-q5_1`, `-q8_0`) use less disk and memory, with some accuracy loss. Your pick in the modal lasts for the session. Set `subtitleGeneration.managedModel` to change the default.
+
+## Prioritizing spoken dialogue
+
+**Focus on spoken dialogue** uses a speech detection (VAD) model to drop silent stretches before transcription. Long passages are split near detected speech, which reduces subtitles that appear before the line is spoken.
+
+It needs two extra pieces:
+
+- The Silero VAD model. Click **Download speech detection model** in the modal, or set `vadModelPath` to your own [Silero GGML model](https://huggingface.co/ggml-org/whisper-vad/tree/main).
+- whisper.cpp's [speech segment detector](https://github.com/ggml-org/whisper.cpp/tree/master/examples/vad-speech-segments), found as `whisper-vad-speech-segments` or `vad-speech-segments` on `PATH`. Set `vadPath` for any other location.
+
+The checkbox lasts for the session. Setting `vadModelPath` turns it on by default.
+
+Dialogue mode keeps music and background sound that might contain speech, so songs can still produce subtitles. It can also take longer than a plain run, because each passage is transcribed separately.
+
+## Using loaded subtitles as timing references
+
+If the video playing in mpv already has a dialogue subtitle track loaded, SubMiner uses its cue times to decide where to split long audio. This works with or without dialogue mode. Whisper still writes the Japanese text and final timestamps. The launcher uses a reference only when its input is the file open in mpv.
+
+SubMiner prefers English tracks and tracks labeled full or dialogue. It skips forced, image-based, generated, and signs or songs tracks, based on their titles and file names. An unlabeled signs-only file can slip through.
+
+The reference must be timed correctly for the video. SubMiner does not fix a mistimed reference.
+
+## Limitations
+
+- Only local files and their internal audio tracks are supported. Not URLs, and not a separate audio file loaded in mpv. Pass a separate local audio file to the launcher instead.
+- Whisper can miss, repeat, or invent lines, and its timing is approximate, especially over music or overlapping speech. Check the text and audio when you mine.
+- SubMiner does not translate subtitles.
diff --git a/docs-site/subtitle-sidebar.md b/docs-site/subtitle-sidebar.md
index 79d669e8..647b9962 100644
--- a/docs-site/subtitle-sidebar.md
+++ b/docs-site/subtitle-sidebar.md
@@ -1,86 +1,70 @@
-# Subtitle Sidebar
+# Subtitle sidebar
 
-The subtitle sidebar displays the full parsed cue list for the active subtitle file as a scrollable panel alongside mpv. It lets you review past and upcoming lines, click any cue to seek directly to that moment, and follow along without depending on the transient overlay subtitles.
+The subtitle sidebar lists every line of the current subtitle file in a scrollable panel next to mpv. Use it to reread lines you missed, look ahead, jump to any line, or copy a stretch of dialogue.
 
-The sidebar is enabled by default. Set `subtitleSidebar.enabled` to `false` if you want to turn it off.
+## Using the sidebar
 
-## How It Works
+Press `\` to open or close it. The sidebar is on by default. Set `subtitleSidebar.enabled` to `false` to turn it off, or `subtitleSidebar.autoOpen` to `true` to open it at startup.
 
-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:
+- Click a line to seek to it. With a line focused from the keyboard, `Enter` seeks to it.
+- The current line is highlighted and kept in view as playback moves (`autoScroll`).
+- Hovering the list pauses playback (`pauseVideoOnHover`).
+- Switching media or subtitle track updates the list.
 
-- The active cue is highlighted and kept in view as playback advances (when `autoScroll` is `true`).
-- Clicking any cue seeks mpv to that timestamp.
-- The sidebar stays synchronized with the overlay - media transitions and subtitle source changes update both simultaneously.
+The sidebar needs a subtitle file SubMiner can parse. Tracks that mpv renders itself, such as embedded ASS tracks, leave it empty. With no lines loaded, the sidebar shows a **Generate Japanese subtitles** button that opens [subtitle generation](/subtitle-generation). You can also open generation any time with `Ctrl+Shift+G`.
 
-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.
+For karaoke and animated ASS subtitles, SubMiner merges the per-frame effect lines into one clean line per cue.
 
-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.
+## Copying dialogue {#selecting-and-copying-dialogue}
 
-## Layout Modes
+1. Drag across the text to select it. The selection can span several lines, and you can scroll to extend it.
+2. Press `Ctrl/Cmd+C` or click **Copy**.
 
-Two layout modes are available via `subtitleSidebar.layout`:
+SubMiner copies the text in subtitle order, without timestamps, with a blank line between cues. Dragging does not seek, and auto-scroll pauses while you have a selection. Press `Escape` to clear it. Changing media or subtitle track, or closing the sidebar, also clears it.
 
-**`overlay`** (default) - The sidebar floats over mpv as a panel. It does not affect the player window size or position.
+## Layout
 
-**`embedded`** - Reserves space on the right side of the player and shifts the video area to mimic a split-pane layout. Useful if you want the cue list visible without it covering the video. If you see unexpected positioning in your environment, switch back to `overlay` to isolate the issue.
+`subtitleSidebar.layout` has two modes:
+
+- `overlay`: the sidebar floats over mpv and does not change the player window.
+- `embedded`: reserves space on the right of the player and moves the video over, so the list doesn't cover it. Placement depends on your compositor. If the geometry comes out wrong, switch back to `overlay`.
 
 ## Configuration
 
-Enable and configure the sidebar under `subtitleSidebar` in your config file:
+All keys live under `subtitleSidebar`. Defaults are in the [configuration reference](/configuration).
 
-```json
+| Key                 | What it does                                                    |
+| ------------------- | --------------------------------------------------------------- |
+| `enabled`           | Turn the sidebar on or off                                      |
+| `autoOpen`          | Open the sidebar when the overlay starts                        |
+| `layout`            | `overlay` or `embedded`                                         |
+| `toggleKey`         | Toggle key, as a `KeyboardEvent.code` value such as `Backslash` |
+| `pauseVideoOnHover` | Pause playback while the pointer is over the list               |
+| `autoScroll`        | Keep the current line in view                                   |
+| `css`               | Styling, see below                                              |
+
+`css` takes CSS properties (`font-family`, `font-size`, `color`, `background-color`, `opacity`) and these custom properties:
+
+| Property                                     | Styles                         |
+| -------------------------------------------- | ------------------------------ |
+| `--subtitle-sidebar-max-width`               | Maximum sidebar width          |
+| `--subtitle-sidebar-timestamp-color`         | Timestamp text                 |
+| `--subtitle-sidebar-active-line-color`       | Current line text              |
+| `--subtitle-sidebar-active-background-color` | Current line background        |
+| `--subtitle-sidebar-hover-background-color`  | Background of the hovered line |
+
+```jsonc
 {
   "subtitleSidebar": {
-    "enabled": true,
-    "autoOpen": false,
-    "layout": "overlay",
-    "toggleKey": "Backslash",
-    "pauseVideoOnHover": true,
-    "autoScroll": true,
+    "layout": "embedded",
     "css": {
-      "font-family": "Hiragino Sans, M PLUS 1, Source Han Sans JP, Noto Sans CJK JP",
-      "color": "#cad3f5",
-      "background-color": "rgba(73, 77, 100, 0.9)",
-      "font-size": "16px",
-      "opacity": "0.95",
-      "--subtitle-sidebar-max-width": "420px",
-      "--subtitle-sidebar-timestamp-color": "#a5adcb",
-      "--subtitle-sidebar-active-line-color": "#f5bde6",
-      "--subtitle-sidebar-active-background-color": "rgba(138, 173, 244, 0.22)",
-      "--subtitle-sidebar-hover-background-color": "rgba(54, 58, 79, 0.84)"
-    }
-  }
+      "font-size": "18px",
+      "--subtitle-sidebar-max-width": "480px",
+    },
+  },
 }
 ```
 
-Styling lives under the `css` object, using CSS property names and CSS custom properties (the same pattern as `subtitleStyle.css`).
+Your `css` object replaces the default one as a whole. To keep a default value, copy it from the configuration reference into your object.
 
-| Option              | Type    | Default       | Description                                                                |
-| ------------------- | ------- | ------------- | -------------------------------------------------------------------------- |
-| `enabled`           | boolean | `true`        | Enable subtitle sidebar support                                            |
-| `autoOpen`          | boolean | `false`       | Open the sidebar automatically on overlay startup                          |
-| `layout`            | string  | `"overlay"`   | `"overlay"` floats over mpv; `"embedded"` reserves right-side player space |
-| `toggleKey`         | string  | `"Backslash"` | `KeyboardEvent.code` for the toggle shortcut                               |
-| `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 |
-
-## Keyboard Shortcut
-
-| 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.
+See [keyboard shortcuts](/shortcuts) for all overlay keys.
diff --git a/docs-site/troubleshooting.md b/docs-site/troubleshooting.md
index e131bf96..87ca8565 100644
--- a/docs-site/troubleshooting.md
+++ b/docs-site/troubleshooting.md
@@ -1,367 +1,203 @@
 # Troubleshooting
 
-Common issues and how to resolve them. Most problems fall into one of a few buckets - the overlay shows but subtitles don't (see [MPV Connection](#mpv-connection)), cards aren't being created or come out empty (see [AnkiConnect](#ankiconnect)), or word lookups don't appear (see [Yomitan](#yomitan)). If an error message popped up on screen, search this page for the exact text - most headings below are quoted error strings.
+Find your symptom below. If you saw an error message, search this page for its text.
 
-## MPV Connection
+## Diagnose first
 
-**Overlay starts but shows no subtitles**
-
-SubMiner connects to mpv via a Unix socket (or named pipe on Windows). If the socket does not exist or the path does not match, the overlay will appear but subtitles will never arrive.
-
-- Ensure mpv is running with `--input-ipc-server=/tmp/subminer-socket`.
-- If you use a custom socket path, set it in both your mpv config and SubMiner config (`mpv.socketPath`).
-- The `subminer` wrapper script sets the socket automatically when it launches mpv. If you launch mpv yourself, the `--input-ipc-server` flag is required.
-
-SubMiner retries the connection automatically with increasing delays (200 ms, 500 ms, 1 s, 2 s on first connect; 1 s, 2 s, 5 s, 10 s on reconnect). If mpv exits and restarts, the overlay reconnects without needing a restart.
-
-If the overlay never appears at all, see [Playback Startup Flow](./architecture#playback-startup-flow) for how a managed launch starts mpv and brings up the overlay.
-
-**"Failed to parse MPV message"**
-
-Logged when a malformed JSON line arrives from the mpv socket. Usually harmless - SubMiner skips the bad line and continues. If it happens constantly, check that nothing else is writing to the same socket path.
-
-## Updates
-
-**"Update check failed"**
-
-Manual update checks show this when GitHub Releases or updater metadata cannot be reached. Check your network connection, then try again from the tray menu or:
+Run the launcher's dependency check:
 
 ```bash
-subminer -u
+subminer doctor
 ```
 
-Automatic checks log failures quietly so playback is not interrupted.
+It reports the app binary, `mpv`, `yt-dlp`, `ffmpeg`, `fzf`, `rofi`, your config file, and the mpv socket path. It exits non-zero when the app binary or `mpv` is missing.
 
-**"SubMiner is up to date" but a prerelease exists**
+Logs are written to daily files:
 
-SubMiner uses the configured release channel for update checks. Set `updates.channel` to `"prerelease"` in `config.jsonc` when you want update checks to include beta and RC releases.
+| Platform      | Log directory              |
+| ------------- | -------------------------- |
+| Linux / macOS | `~/.config/SubMiner/logs/` |
+| Windows       | `%APPDATA%\SubMiner\logs\` |
 
-**Launcher update shows a sudo command**
+Files are named `app-<date>.log`, `launcher-<date>.log`, and `mpv-<date>.log`. The mpv log is off by default. Turn log files on or off and set retention under [`logging`](/configuration#logging).
 
-The detected launcher is installed in a protected path such as `/usr/local/bin/subminer` or `/usr/bin/subminer`. SubMiner does not elevate itself. Run the command shown in the popup to replace the launcher after checksum verification.
+For more detail, raise the log level for one run:
 
-**OSD update notification did not appear**
+```bash
+subminer --log-level debug video.mkv
+SubMiner.AppImage --start --log-level debug
+```
 
-`updates.notificationType: "osd"` uses the legacy mpv OSD path. If mpv is disconnected, SubMiner logs the update and does not force-start the overlay. Use `"system"` for OS notifications, `"both"` for overlay + OS notifications, or `"osd-system"` in `config.jsonc` if you want the legacy OSD + OS combination.
+The default level is `warn`. `--dev` and `--debug` switch the app into dev mode but do not change log verbosity. To inspect the overlay itself, focus it and press `y` then `d` to open DevTools.
 
-## AnkiConnect
+## Overlay starts but shows no subtitles
 
-**"AnkiConnect: unable to connect"**
+SubMiner reads subtitles from mpv over an IPC socket (a named pipe on Windows). If the paths do not match, the overlay appears but stays empty.
 
-First confirm you've completed the [Anki Integration prerequisites](/anki-integration#prerequisites) - Anki must be running with the AnkiConnect add-on installed.
+- The `subminer` launcher sets the socket for you. If you start mpv yourself, pass `--input-ipc-server=/tmp/subminer-socket`.
+- If you changed `mpv.socketPath`, use the same path in your mpv config.
 
-SubMiner connects to the active Anki endpoint:
+SubMiner reconnects on its own if mpv restarts.
 
-- `ankiConnect.url` (direct mode, default `http://127.0.0.1:8765`)
-- `http://<ankiConnect.proxy.host>:<ankiConnect.proxy.port>` (proxy mode)
+## Overlay does not appear
 
-This error means the active endpoint is unavailable, or (in proxy mode) the proxy cannot reach `ankiConnect.proxy.upstreamUrl`.
+- Confirm SubMiner is running (`SubMiner.AppImage --start`, or check for the process).
+- Linux: Hyprland and Sway work natively. Any other compositor needs mpv and SubMiner under X11 or Xwayland, with `xdotool`, `xprop`, and `xwininfo` installed. See [KDE Plasma and other Wayland compositors](#kde-plasma-and-other-wayland-compositors).
+- macOS: grant Accessibility permission in System Settings > Privacy & Security > Accessibility.
 
-- If you changed the AnkiConnect port, update `ankiConnect.url` (or `ankiConnect.proxy.upstreamUrl` if using proxy mode).
-- If using external Yomitan/browser clients, confirm they point to your SubMiner proxy URL.
+## Overlay is on the wrong monitor or position
 
-SubMiner retries with exponential backoff (up to 5 s) and suppresses repeated error logs after 5 consecutive failures. When Anki comes back, you will see "AnkiConnect connection restored".
+SubMiner follows the mpv window. Tracking needs `hyprctl` (Hyprland), `swaymsg` (Sway), or `xdotool` and `xwininfo` (X11) on `PATH`.
 
-**Cards are created but fields are empty**
+If the position is only slightly off, right-click and drag the subtitle text to adjust the offset.
 
-Field names in your config must name a field that exists on your Anki note type. Matching is case-insensitive (`sentenceaudio` finds `SentenceAudio`), but the spelling must otherwise match, and unknown fields are skipped silently. Check `ankiConnect.fields` - for example, if your note type uses `SentenceAudio` but your config says `Audio`, the field will not be populated.
+## Clicks pass through the overlay
 
-See [Anki Integration](/anki-integration) for the full field mapping reference.
+- The overlay only takes input while the cursor is over subtitle text. Hover the text directly.
+- Toggle the overlay off and on with `Alt+Shift+O`.
+- Linux: if clicks keep failing, toggle the overlay off, click the mpv window, then toggle it back on.
 
-**"Update failed" OSD message**
+## Hovering a word shows no popup
 
-Shown when SubMiner tries to update a card that no longer exists, or when AnkiConnect rejects the update. Common causes:
+If you have not set up dictionaries yet, start with [Yomitan setup](/usage#yomitan-setup).
 
-- The card was deleted in Anki between creation and enrichment update.
-- The note type changed and a mapped field no longer exists.
+- Open Yomitan settings (`Alt+Shift+Y` or `SubMiner.AppImage --yomitan`) and confirm at least one dictionary is imported and enabled.
+- If `yomitan.externalProfilePath` is set, manage dictionaries in that external profile. SubMiner opens it read-only and has no settings window of its own in that mode.
+- Check the log for "Loaded Yomitan extension".
 
-## Overlay
+Word boundaries come from Yomitan's parser. Some splits will be wrong, since Japanese has no spaces.
 
-**Overlay does not appear**
+## "Electron downgrade blocked" or "Unsupported Electron runtime"
 
-- Confirm SubMiner is running: `SubMiner.AppImage --start` or check for the process.
-- On Linux, the overlay requires a supported window backend. Hyprland and Sway have native Wayland support; all other compositors require both mpv and SubMiner to run under X11 or Xwayland (`xdotool`, `xprop`, and `xwininfo` must be installed).
-- On macOS, grant Accessibility permission to SubMiner in System Settings > Privacy & Security > Accessibility.
+SubMiner refuses to load Yomitan storage when the current Electron major does not match the app build, or when the profile was previously opened by a newer Electron version. Launch the packaged app or use the repository's `bun run dev` command. Do not delete the runtime safety record to force an older Electron version to open the profile.
 
-**Overlay appears but clicks pass through / cannot interact**
+## "Yomitan reported zero dictionaries after previously reporting ..."
 
-- Make sure you are hovering over subtitle text - the overlay only becomes interactive when the cursor is over a subtitle.
-- On macOS/Windows: toggle the overlay off and back on (`Alt+Shift+O`) to re-enable pointer events.
-- On Linux: mouse event handling is unreliable in some Electron/compositor combinations. If clicks consistently fail, toggle the overlay off, click the underlying mpv window, then toggle it back on.
+SubMiner detected that a previously non-empty Yomitan profile suddenly appears empty. Automatic character-dictionary changes are blocked so they cannot overwrite the suspicious state. Close SubMiner, preserve the profile directory, and restore a known-good backup before importing or deleting dictionaries.
 
-**Overlay briefly freezes after a modal/runtime error**
+## "Yomitan extension not found in any search path"
 
-- Renderer errors now trigger an automatic recovery path. You should see a short toast ("Renderer error recovered. Overlay is still running.").
-- Recovery closes any open modal and restores click-through/shortcuts automatically without interrupting mpv playback.
-- If errors keep recurring, toggle the overlay's DevTools using overlay chord `y` then `d` (`F12` also works in dev builds) and inspect the `renderer overlay recovery` error payload for stack trace + modal/subtitle context.
+The bundled Yomitan is missing. Re-download the AppImage, or place an unpacked Yomitan extension in `~/.config/SubMiner/yomitan`. Source builds must run `bun run build` first to produce `build/yomitan`.
 
-**Overlay is on the wrong monitor or position**
+## "MeCab not found on system"
 
-SubMiner positions the overlay by tracking the mpv window. If tracking fails:
+This is informational. Tokenization uses Yomitan, not MeCab. Install MeCab only if you want to silence the message:
 
-- Hyprland: Ensure `hyprctl` is available.
-- Sway: Ensure `swaymsg` is available.
-- X11: Ensure `xdotool` and `xwininfo` are installed.
+- Arch: `sudo pacman -S mecab mecab-ipadic`
+- Ubuntu/Debian: `sudo apt install mecab libmecab-dev mecab-ipadic-utf8`
+- macOS: `brew install mecab mecab-ipadic`
 
-If the overlay position is slightly off, right-click and drag on subtitle text to fine-tune the overlay subtitle offset.
+## "AnkiConnect: unable to connect"
 
-## Yomitan
+Anki must be running with the AnkiConnect add-on. See [Anki integration prerequisites](/anki-integration#prerequisites).
 
-If you haven't set up dictionaries yet, see [Yomitan setup](/usage#yomitan-setup) first.
+- Direct mode: check that `ankiConnect.url` matches the AnkiConnect port.
+- Proxy mode: check `ankiConnect.proxy.upstreamUrl`, and point external Yomitan or browser clients at the SubMiner proxy.
 
-**"Electron downgrade blocked" or "Unsupported Electron runtime"**
+SubMiner keeps retrying and logs "AnkiConnect connection restored" once Anki is back.
 
-SubMiner refuses to load Yomitan storage when the current Electron major does not match the app build, or when the profile was previously opened by a newer Electron version. Launch the packaged app or use the repository's `bun run dev` command. Do not delete the runtime safety record merely to force an older Electron version to open the profile.
+## Cards are created but fields are empty
 
-**"Yomitan reported zero dictionaries after previously reporting ..."**
+Each name in `ankiConnect.fields` must match a field on your note type. Matching is case-insensitive, but otherwise the spelling must match. Unknown fields are skipped without an error. For example, config `Audio` does not fill a note field named `SentenceAudio`. See [Anki integration](/anki-integration).
 
-SubMiner detected that a previously non-empty Yomitan profile suddenly appears empty. Automatic character-dictionary changes are blocked so they cannot normalize or overwrite the suspicious state. Close SubMiner, preserve the profile directory, and restore a known-good backup before importing or deleting dictionaries.
+## "Update failed" when mining
 
-**"Yomitan extension not found in any search path"**
+The card was deleted in Anki before SubMiner finished enriching it, or the note type changed and a mapped field no longer exists.
 
-SubMiner bundles Yomitan and searches for it in these locations (in order):
+## "Subtitle timing not found; copy again while playing"
 
-1. `build/yomitan` (local/source build output)
-2. `<resources>/yomitan` (Electron resources path)
-3. `/usr/share/SubMiner/yomitan`
-4. `~/.config/SubMiner/yomitan` (user-data fallback on Linux)
+SubMiner has no timing for the current line yet. This happens when paused before any subtitle arrived, after switching subtitle tracks, or while an external subtitle file is still loading. Resume playback, wait for the next line, and mine again.
 
-SubMiner does not load the source tree directly from `vendor/subminer-yomitan`; source builds must produce `build/yomitan` first.
+## "FFmpeg not found"
 
-If you installed from the AppImage and see this error, the package may be incomplete. Re-download the AppImage or place the unpacked Yomitan extension manually in `~/.config/SubMiner/yomitan`.
+Audio clips and screenshots need FFmpeg. Without it, cards are still created with empty media fields.
 
-**Yomitan lookup popup does not appear when hovering words or triggering lookup**
+- Arch: `sudo pacman -S ffmpeg`
+- Ubuntu/Debian: `sudo apt install ffmpeg`
+- macOS: `brew install ffmpeg`
 
-- Verify Yomitan loaded successfully - check the terminal output for "Loaded Yomitan extension".
-- Yomitan requires dictionaries to be installed. Open Yomitan settings (`Alt+Shift+Y` or `SubMiner.AppImage --yomitan`) and confirm at least one dictionary is imported.
-- If `yomitan.externalProfilePath` is set, import/check dictionaries in the external app/profile instead. SubMiner treats that profile as read-only and does not open its own Yomitan settings window.
-- If the overlay shows subtitles but hover lookup never resolves on tokens, the tokenizer may have failed. See the MeCab section below.
+## Audio or screenshot generation is slow or times out
 
-## MeCab / Tokenization
+- Use a local copy if the video is on a slow network mount.
+- Set `ankiConnect.media.imageType` to `"static"`. Animated AVIF is the slowest path.
+- Lower `ankiConnect.media.imageQuality` or `ankiConnect.media.maxMediaDuration`.
 
-**"MeCab not found on system"**
+## Subtitle sync (subsync)
 
-This is informational, not an error. SubMiner tokenization is driven by Yomitan's internal parser. MeCab availability checks may still run for auxiliary token metadata, but MeCab is not used as a tokenization fallback path.
+Subtitle sync needs at least one of alass or ffsubsync. Neither ships with SubMiner.
 
-To install MeCab:
+**"Configured alass executable not found"**: install it (`paru -S alass` or `cargo install alass-cli`), or set `subsync.alass_path`.
 
-- **Arch Linux**: `sudo pacman -S mecab mecab-ipadic`
-- **Ubuntu/Debian**: `sudo apt install mecab libmecab-dev mecab-ipadic-utf8`
-- **macOS**: `brew install mecab mecab-ipadic`
+**"Configured ffsubsync executable not found"**: install it (`paru -S python-ffsubsync` or `pip install ffsubsync`), or set `subsync.ffsubsync_path`.
 
-**Words are not segmented correctly**
+**"alass synchronization failed" / "ffsubsync synchronization failed"**:
 
-Japanese word boundaries depend on Yomitan parser output. If segmentation seems wrong:
+- alass needs a reference: a second subtitle track or the local video file. It cannot use the track being retimed.
+- `ffmpeg` must be installed to extract internal subtitle tracks.
+- ffsubsync only works on local files, not streams.
+- Run the tool by hand to see its full error output.
 
-- Verify Yomitan dictionaries are installed and active.
-- Note that CJK characters without spaces are segmented using parser heuristics, which is not always perfect.
+## "xz binary not found"
 
-## Character Dictionary
+TsukiHime subtitles are xz-compressed. Install `xz`:
 
-Character names from AniList are matched and highlighted in subtitles via the bundled Yomitan. See [Character Dictionary](/character-dictionary) for setup and the full troubleshooting list - the most common issues:
+- Arch: `sudo pacman -S xz`
+- Ubuntu/Debian: `sudo apt install xz-utils`
+- Fedora: `sudo dnf install xz`
+- macOS: `brew install xz`
+- Windows: `scoop install main/xz`, or download XZ Utils from [tukaani.org/xz](https://tukaani.org/xz/) and add the folder with `xz.exe` to `PATH`. Restart SubMiner afterwards.
 
-- **Names not highlighting:** Confirm `subtitleStyle.nameMatchEnabled` is `true`, and that the current media resolved to an AniList entry (SubMiner needs a media ID to fetch characters). No AniList account or token is required - character data uses public GraphQL queries.
-- **Inline portraits missing:** Confirm `subtitleStyle.nameMatchImagesEnabled` is `true`. Portraits also require AniList to return an image and the download to succeed during snapshot generation.
-- **Wrong characters showing:** Open the in-app manager (`Ctrl/Cmd+D`) and use **Override** to pin the correct AniList match for the series.
-- **Feature unavailable:** If `yomitan.externalProfilePath` is set, SubMiner runs in read-only external-profile mode and its character-dictionary features are disabled.
-
-## Media Generation
-
-**"FFmpeg not found"**
-
-SubMiner uses FFmpeg to extract audio clips and generate screenshots. Install it:
-
-- **Arch Linux**: `sudo pacman -S ffmpeg`
-- **Ubuntu/Debian**: `sudo apt install ffmpeg`
-- **macOS**: `brew install ffmpeg`
-
-Without FFmpeg, card creation still works but audio and image fields will be empty.
-
-**Audio or screenshot generation hangs**
-
-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.
-- Checking that `ankiConnect.media.maxMediaDuration` is not set too high.
-
-## Shortcuts
-
-**"Failed to register global shortcut"**
-
-This warning refers to the OS-registered shortcut `Alt+Shift+Y` (Yomitan settings), which is fixed and may conflict with other applications or desktop environment keybindings.
-
-- Check your DE/WM keybinding settings for conflicts and free up `Alt+Shift+Y` there.
-- `Alt+Shift+O` (`shortcuts.toggleVisibleOverlayGlobal`) is not OS-registered - it is handled by the overlay window and the mpv plugin, so it does not trigger this warning and only needs those windows focused.
-- On Wayland, global shortcut registration has limitations depending on the compositor. Only Hyprland and Sway are supported natively - see the [Hyprland](#hyprland) section below for shortcut passthrough rules. Other Wayland compositors require X11/Xwayland.
-
-**Overlay keybindings not working**
-
-Overlay-local shortcuts (Space, arrow keys, etc.) only work when the overlay window has focus. Click on the overlay or use `Alt+Shift+O` (with the overlay or mpv focused) to toggle it and give it focus.
-
-## Subtitle Timing
-
-**"Subtitle timing not found; copy again while playing"**
-
-This OSD message appears when you try to mine a sentence but SubMiner has no timing data for the current subtitle. Causes:
-
-- The video is paused and no subtitle has been received yet.
-- The subtitle track changed and timing data was cleared.
-- You are using an external subtitle file that mpv has not fully loaded.
-
-Resume playback and wait for the next subtitle to appear, then try mining again.
-
-## Subtitle Sync (Subsync)
-
-Both **alass** and **ffsubsync** are optional external dependencies. Subtitle syncing requires at least one of them to be installed.
-
-**"Configured alass executable not found"**
-
-Install alass or configure the path:
-
-- **Arch Linux (AUR)**: `paru -S alass`
-- **Cargo**: `cargo install alass-cli`
-- Set the path: `subsync.alass_path` in your config.
-
-**"Configured ffsubsync executable not found"**
-
-Install ffsubsync or configure the path:
-
-- **Arch Linux (AUR)**: `paru -S python-ffsubsync`
-- **pip**: `pip install ffsubsync`
-- Must be on `PATH` or configured via `subsync.ffsubsync_path` in your config.
-
-**"alass synchronization failed" / "ffsubsync synchronization failed"**
-
-If subtitle sync fails (the error message is prefixed with the engine name):
-
-- 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).
-
-## TsukiHime
-
-**"xz binary not found"**
-
-TsukiHime serves extracted subtitles xz-compressed, so SubMiner shells out to `xz` to decompress them. Install it:
-
-- **Arch Linux**: `sudo pacman -S xz`
-- **Ubuntu/Debian**: `sudo apt install xz-utils`
-- **Fedora**: `sudo dnf install xz`
-- **macOS**: `brew install xz`
-- **Windows**: neither winget nor Chocolatey packages `xz`. Use `scoop install main/xz`, or download XZ Utils from [tukaani.org/xz](https://tukaani.org/xz/) and add the folder containing `xz.exe` to your `PATH`. Restart SubMiner afterwards.
-
-Most Linux distributions ship it already. See [TsukiHime Integration](/tsukihime-integration#troubleshooting) for the other TsukiHime error messages.
+Other TsukiHime errors are covered in [TsukiHime integration](/tsukihime-integration#troubleshooting).
 
 ## Jimaku
 
-**"Jimaku request failed" or HTTP 429**
+**"Jimaku request failed" or HTTP 429**: you hit the Jimaku rate limit. Wait for the time shown in the message. Setting `jimaku.apiKey` or `jimaku.apiKeyCommand` gives you a higher limit.
 
-The Jimaku API has rate limits. If you see 429 errors, wait for the retry duration shown in the OSD message and try again. If you have a Jimaku API key, set it in `jimaku.apiKey` or `jimaku.apiKeyCommand` to get higher rate limits.
+## Character names are not highlighted
 
-## Logging and App Mode
+See [Character dictionary](/character-dictionary) for the full list. The common causes:
 
-- Default log output is `warn`.
-- Use `--log-level` for more/less output.
-- Use `--dev`/`--debug` only to force app/dev mode (for example to get dev behavior from the overlay/app); they do not change log verbosity.
-- You can combine both, for example `SubMiner.AppImage --start --dev --log-level debug`, when you need maximum diagnostics.
+- `subtitleStyle.nameMatchEnabled` is off, or the media did not resolve to an AniList entry.
+- Portraits need `subtitleStyle.nameMatchImagesEnabled`.
+- Wrong characters: open the manager (`Ctrl/Cmd+D`) and use **Override** to pick the right AniList entry.
+- The feature is disabled when `yomitan.externalProfilePath` is set.
 
-## Performance and Resource Impact
+## "Failed to register global shortcut"
 
-### At a glance
+Another app or your desktop already uses `Alt+Shift+Y` (Yomitan settings). Free it in your desktop or window manager settings. On Hyprland, add a `pass` rule (see [Hyprland](#hyprland)).
 
-- Baseline: `SubMiner --start` is usually lightweight for normal playback.
-- Common spikes come from:
-  - first subtitle parse/tokenization bursts
-  - media generation (`ffmpeg` audio/image and AVIF paths)
-  - media sync and subtitle tooling (`alass`, `ffsubsync`)
-  - `ankiConnect` enrichment (plus polling overhead when proxy mode is disabled)
+## Overlay shortcuts do nothing
 
-### If playback feels sluggish
+Overlay shortcuts only work while the overlay has focus. Click the overlay, or press `Alt+Shift+O` with mpv or the overlay focused.
 
-1. Reduce overlay workload:
+## Update checks
 
-- set secondary subtitles hidden:
-  - `secondarySub.defaultMode: "hidden"`
-- disable optional enrichment:
-  - `subtitleStyle.enableJlpt: false`
-  - `subtitleStyle.frequencyDictionary.enabled: false`
+**"Update check failed"**: GitHub could not be reached. Check your connection and retry from the tray menu or with `subminer -u`.
 
-2. Reduce rendering pressure:
+**No prerelease offered**: set `updates.channel` to `"prerelease"` to include beta and RC builds.
 
-- lower `subtitleStyle.css["font-size"]`
-- keep overlay complexity minimal during heavy CPU periods
+**Launcher update shows a sudo command**: the launcher lives in a protected path such as `/usr/local/bin`. Run the command shown to replace it.
 
-3. Reduce media overhead:
+## Playback feels sluggish
 
-- keep `ankiConnect.media.imageType` set to `static` (avoid animated AVIF unless needed)
-- lower `ankiConnect.media.imageQuality`
-- reduce `ankiConnect.media.maxMediaDuration`
+Idle playback is cheap. Load comes from the first tokenization burst, media generation, subtitle sync, and Anki enrichment. To cut it:
 
-4. Lower integration cost:
+- `ankiConnect.media.imageType: "static"`, plus lower `imageQuality` and `maxMediaDuration`.
+- `subtitleStyle.enableJlpt: false` and `subtitleStyle.frequencyDictionary.enabled: false`.
+- `secondarySub.defaultMode: "hidden"`.
+- `immersionTracking.enabled: false` to stop stats logging.
 
-- disable AI translation when not needed (`ankiConnect.ai.enabled: false`)
-- if needed, run immersion telemetry with lower duration expectations (`immersionTracking.enabled: false` for constrained sessions)
-- favor the default lightweight YouTube subtitle startup settings on low-resource systems
+Also check that only one SubMiner instance is running, and whether `ffmpeg`, `yt-dlp`, or a sync tool is the process using CPU.
 
-### Practical low-impact profile
+## Linux
 
-```json
-{
-  "subtitleStyle": {
-    "css": {
-      "font-size": "30px"
-    },
-    "enableJlpt": false,
-    "frequencyDictionary": {
-      "enabled": false
-    }
-  },
-  "secondarySub": {
-    "defaultMode": "hidden"
-  },
-  "ankiConnect": {
-    "media": {
-      "imageType": "static",
-      "imageQuality": 80,
-      "maxMediaDuration": 12
-    },
-    "ai": {
-      "enabled": false
-    }
-  },
-  "immersionTracking": {
-    "enabled": false
-  }
-}
-```
+### Tray icon missing
 
-### If usage is still high
-
-- Confirm only one SubMiner instance is running.
-- Check whether bottlenecks are `ffmpeg`, `yt-dlp`, or sync tooling in system monitor.
-- Keep the default `warn` level for normal use; raise to `info` or `debug` only for targeted diagnosis.
-- Reproduce once with `SubMiner.AppImage --start --log-level debug` and open DevTools (`y` then `d`) if freezes recur.
-
-## Platform-Specific
-
-### Linux
-
-- **Wayland (Hyprland/Sway only)**: Native Wayland support is limited to Hyprland and Sway. Window tracking uses compositor-specific commands (`hyprctl` / `swaymsg`). If these are not on `PATH`, tracking will fail silently. Other Wayland compositors (KDE Plasma, GNOME, …) are not supported natively - both mpv and SubMiner must run under X11 or Xwayland instead. On those sessions SubMiner forces XWayland automatically for itself and for every mpv it launches (see [KDE Plasma & other Wayland compositors](#kde-plasma-other-wayland-compositors)).
-- **X11 / Xwayland**: Requires `xdotool`, `xprop`, and `xwininfo`. If missing, the overlay cannot track the mpv window position. This is the required backend for any Wayland compositor other than Hyprland or Sway - both mpv and SubMiner must be running under X11/Xwayland for window tracking _and_ for the overlay to stay above mpv (Wayland forbids clients from controlling window stacking). SubMiner uses a managed X11 overlay while mpv is windowed, switches to an override-redirect X11 overlay while tracked mpv is fullscreen, and hides/releases that overlay when another X11/Xwayland app takes focus. The visible overlay stays hidden until SubMiner has tracked mpv geometry, so startup should not create a display-sized fallback overlay while tokenization warms up.
-- **Tray icon missing**: SubMiner creates an Electron tray icon in `--background` mode, but Linux trays require a StatusNotifier/AppIndicator host. Hyprland does not provide one by itself; enable a tray in Waybar, Hyprpanel, or another panel. If Electron cannot register the tray, SubMiner logs a warning that mentions the missing tray host.
-- **Mouse passthrough**: On Linux X11/Xwayland, SubMiner uses `xdotool` to poll the cursor and only enables overlay input while the cursor is over subtitle or popup regions. Outside those regions, pointer input passes through to mpv. Native Wayland compositors other than Hyprland/Sway cannot provide the stacking control SubMiner needs.
+Linux trays need a StatusNotifier/AppIndicator host. Hyprland has none by default. Enable a tray in Waybar, Hyprpanel, or another panel.
 
 ### Hyprland
 
-SubMiner's overlay is a transparent, frameless Electron window that must be kept above mpv. SubMiner tries to apply the floating, borderless, no-shadow, and no-blur properties itself each time it places the overlay. It detects Hyprland's active config provider and uses Lua `hl.dsp.window.*` dispatchers for recent Hyprland Lua configs, or the legacy dispatcher syntax for older hyprlang configs. On many configurations that is enough, but if your Hyprland version doesn't honor those runtime dispatches - or a broad rule in your config forces opacity/blur on every window - add explicit window rules so the overlay is exempt. You also need `pass` bindings to forward global shortcuts to SubMiner (see below).
-
-**Overlay is not transparent or has a visible border**
-
-Add a window rule matching SubMiner's window class. Recent Hyprland uses the Lua config format:
+SubMiner applies float, no-border, and no-blur properties to its window itself. If the overlay still has a border or an opaque background, a global opacity or blur rule is usually overriding it. Add a rule for the `SubMiner` class. Lua config:
 
 ```lua
 hl.window_rule({
@@ -378,7 +214,7 @@ hl.window_rule({
 })
 ```
 
-On older Hyprland releases that still use the hyprlang config (`hyprland.conf`), use the equivalent `windowrule` lines:
+Older `hyprland.conf` configs:
 
 ```ini
 windowrule = float on, match:class SubMiner
@@ -388,78 +224,32 @@ windowrule = no_shadow on, match:class SubMiner
 windowrule = no_blur on, match:class SubMiner
 ```
 
-If you still see a solid background or visual artifacts instead of the mpv video underneath, the culprit is almost always a global opacity/blur rule applying to the overlay - the `opaque`/`opacity` and `no_blur` fields above override it.
-
-**Global shortcuts not working**
-
-On Hyprland, Electron cannot register global shortcuts on its own. You must explicitly pass keybindings to SubMiner using `pass` rules:
+Hyprland swallows global shortcuts unless you pass them through. Add a `pass` bind for each one, and update it if you remap the key:
 
 ```ini
 bind = ALT SHIFT, O, pass, class:^(SubMiner)$
 bind = ALT SHIFT, Y, pass, class:^(SubMiner)$
 ```
 
-Add a `pass` rule for each global shortcut you configure. The defaults are `Alt+Shift+O` (toggle overlay) and `Alt+Shift+Y` (Yomitan settings). If you remap `shortcuts.toggleVisibleOverlayGlobal` to a different key, update the `pass` rule to match.
+If the overlay stays behind fullscreen mpv, check that the mpv socket is connected and that `hyprctl -j clients` works from the environment that launched SubMiner.
 
-Without these rules, Hyprland intercepts the keypresses before they reach SubMiner, and the shortcuts silently do nothing.
+See the Hyprland wiki on [global keybinds](https://wiki.hypr.land/Configuring/Binds/#global-keybinds) and [window rules](https://wiki.hypr.land/Configuring/Window-Rules/).
 
-**Overlay stays behind mpv after fullscreen**
+### KDE Plasma and other Wayland compositors
 
-SubMiner watches mpv's `fullscreen` property and refreshes the overlay geometry when it changes. If the overlay still does not move or rise above fullscreen mpv, confirm that the mpv IPC socket is connected and that `hyprctl -j clients` and `hyprctl -j monitors` work from the same environment that launched SubMiner.
+Outside Hyprland and Sway, Wayland does not let the overlay stay on top of mpv, so both must run under Xwayland. SubMiner does this automatically for itself and for every mpv it launches (launcher, tray, Jellyfin, YouTube). Install `xdotool`, `xprop`, and `xwininfo`.
 
-For more details, see the Hyprland docs on [global keybinds](https://wiki.hypr.land/Configuring/Binds/#global-keybinds) and [window rules](https://wiki.hypr.land/Configuring/Window-Rules/).
+**Overlay sits behind mpv, and hover or Yomitan stops working**: mpv started as a native Wayland window. This happens when you launch mpv yourself. Launch through SubMiner, or force Xwayland in your own command:
 
-### KDE Plasma & other Wayland compositors
+```bash
+mpv --gpu-context=x11vk,x11egl,x11 video.mkv
+```
 
-On any Wayland session that is not Hyprland or Sway (KDE Plasma, GNOME, and others), the overlay can only stay above mpv when both processes run under **XWayland** - the Wayland protocol forbids clients from controlling window stacking, so the overlay's "always on top" becomes a no-op on a native Wayland surface.
+`WAYLAND_DISPLAY= mpv video.mkv` also works, as does `gpu-context=x11vk` (or `x11egl`) in `mpv.conf`. To check, `xdotool search --class mpv` should print a window id.
 
-SubMiner handles this automatically:
+**Overlay stays above an unrelated app**: SubMiner can only see X11/Xwayland windows in this mode. Run that app under Xwayland too.
 
-- 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.
-- During startup and fullscreen transitions, SubMiner waits for tracked mpv geometry before showing the visible overlay and skips the fullscreen restack hide/show path after mpv leaves fullscreen. That avoids a temporary full-screen overlay or black window while the subtitle tokenizer and Yomitan warmups finish.
-- If the subtitle sidebar is open during a windowed/fullscreen transition, SubMiner restores it on the replacement overlay window. Subtitle hit regions are also refreshed as soon as the first measured subtitle line is reported, so hover and Yomitan lookup should work on the first visible line.
+## macOS
 
-Requirements: `xdotool`, `xprop`, and `xwininfo` must be installed. SubMiner uses root `_NET_ACTIVE_WINDOW` from `xprop` for focus detection and falls back to `xdotool getactivewindow` when that signal is unavailable.
-
-**Overlay sits behind mpv / pause-on-hover and Yomitan stop working**
-
-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=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).
-
-**Overlay stays above an unrelated foreground app**
-
-SubMiner can only detect focus for X11/Xwayland windows in this mode. If a native Wayland app covers mpv but the overlay stays visible, run that app under Xwayland too or use Hyprland/Sway native support. Generic X11 cannot observe native Wayland foreground windows.
-
-### macOS
-
-- **Accessibility permission**: Required for window tracking. Grant it in System Settings > Privacy & Security > Accessibility.
-- **Gatekeeper**: If macOS blocks SubMiner, right-click the app and select "Open" to bypass the warning, or remove the quarantine attribute: `xattr -d com.apple.quarantine /path/to/SubMiner.app`
-
-## See Also
-
-Feature-specific issues are covered in each feature's own page:
-
-- [Anki Integration](/anki-integration) - card creation, field mapping, and AnkiConnect setup
-- [AniList Integration](/anilist-integration) - watch-progress sync and authentication
-- [Character Dictionary](/character-dictionary) - AniList character name matching and inline portraits
-- [Jellyfin Integration](/jellyfin-integration) - remote playback and library connection
-- [Jimaku Integration](/jimaku-integration) - subtitle fetching and API rate limits
-- [TsukiHime Integration](/tsukihime-integration) - multi-language subtitle download and `xz` decompression
-- [YouTube Integration](/youtube-integration) - subtitle generation and playback
-- [Immersion Tracking](/immersion-tracking) - telemetry, session logging, and the stats dashboard
-- [Launcher Script](/launcher-script) - `subminer` commands, pickers, watch history, and cross-machine sync
-- [MPV Plugin](/mpv-plugin) - in-player chords, script-opts, and binary auto-detection
-- [WebSocket / Texthooker API](/websocket-texthooker-api) - external texthooker clients
-- [Subtitle Annotations](/subtitle-annotations) - N+1, frequency, JLPT, and name-match layers
-- [Subtitle Sidebar](/subtitle-sidebar) - sidebar navigation and behavior
-- [Configuration Reference](/configuration) - full config options
-- [Shortcuts](/shortcuts) - keybinding reference
+- Accessibility permission is required for window tracking: System Settings > Privacy & Security > Accessibility.
+- If Gatekeeper blocks the app, right-click it and choose Open, or run `xattr -d com.apple.quarantine /path/to/SubMiner.app`.
diff --git a/docs-site/tsukihime-integration.md b/docs-site/tsukihime-integration.md
index 27455e21..7477ac71 100644
--- a/docs-site/tsukihime-integration.md
+++ b/docs-site/tsukihime-integration.md
@@ -1,81 +1,48 @@
-# TsukiHime Integration
+# TsukiHime integration
 
-[TsukiHime](https://tsukihime.org) tracks anime torrent releases and extracts every attachment - including embedded subtitle tracks - from the release files, hosting them for direct download. SubMiner integrates with the TsukiHime API so you can pull English subtitles for the currently playing episode straight from the overlay, no torrent client involved. Downloaded subtitles are decompressed, saved next to the video, and loaded into mpv immediately.
+[TsukiHime](https://tsukihime.org) extracts the subtitle tracks from anime torrent releases and hosts them for download. SubMiner searches it from the overlay, so you can grab Japanese or secondary-language subtitles for the current episode without a torrent client. Most releases carry only English subtitles, so [Jimaku](/jimaku-integration) is usually the better source for Japanese.
 
-This is the multi-language companion to the [Jimaku integration](/jimaku-integration). Releases that ship multiple languages (e.g. Netflix `[MultiSub]` rips) expose them all; the modal's tabs pick which ones you see, and each download is saved with its own language suffix.
+## Setup
 
-::: tip Successor to Animetosho
-TsukiHime replaces [Animetosho](https://animetosho.org), which stops processing new releases in May 2026. TsukiHime imported the Animetosho index and mirrors its attachment storage, so older releases stay reachable alongside new ones.
-:::
+TsukiHime needs no account or API key. SubMiner needs the `xz` binary on your `PATH` to unpack downloads. Most Linux distributions ship it (package `xz` or `xz-utils`).
 
-::: tip No API key required
-Unlike Jimaku, TsukiHime needs no account or API key. The only requirement is the `xz` binary on your `PATH` - TsukiHime serves extracted subtitles xz-compressed, and SubMiner shells out to `xz` to decompress them. Most Linux distributions ship it by default (package `xz` or `xz-utils`).
-:::
+## Usage
 
-## How It Works
+1. Press `Ctrl+Shift+T` during playback.
+2. SubMiner fills in the title and episode from the file name and searches right away when it finds both. Otherwise, fix the fields and press `Enter`.
+3. Pick a tab. The first tab shows your secondary language (`secondarySub.secondarySubLanguages`, or English if unset). The second tab shows Japanese. Each tab lists only releases that carry that language.
+4. Select a release, then a subtitle track.
 
-The integration runs through an in-overlay modal opened with `Ctrl+Shift+T` by default. The modal has two tabs that filter the subtitle tracks of the selected release by role: the first follows `secondarySub.secondarySubLanguages` (English when unset), and the second is always **Japanese**, the currently supported primary subtitle language. Tracks with no language tag stay visible on the secondary tab.
+The track is saved next to the video with a language suffix, such as `<video>.ja.ass` or `<video>.en.ass` (a temp directory is used for streams). A Japanese track becomes mpv's primary subtitle. A track from the secondary tab loads as the secondary subtitle and leaves the primary alone.
 
-When you open the modal, SubMiner parses the current video filename to extract a title and episode number (same parser as Jimaku - `S01E03`, `1x03`, `E03`, and dash-separated numbers all work). If the filename yields a high-confidence match, SubMiner auto-searches immediately.
+Pick the release that matches your video file, same group and same version, and the timing will line up. With any other release, fix the offset with subtitle sync (`Ctrl+Alt+S`).
 
-From there:
+| Key              | Action                                 |
+| ---------------- | -------------------------------------- |
+| `Enter`          | Search, or select the highlighted item |
+| `Up` / `Down`    | Move through releases or tracks        |
+| `Left` / `Right` | Switch tabs                            |
+| `Escape`         | Close                                  |
 
-1. **Search** - SubMiner queries TsukiHime with `<title> <episode>`. Results appear as a list of releases (e.g. `[SubsPlease] ... - 28 (1080p)`), each showing size, file count, and the subtitle languages the release carries.
-2. **Browse releases** - Select a release to list the text subtitle tracks extracted from its files. English tracks sort first; image-based tracks (PGS/VobSub) are filtered out.
-3. **Download** - Selecting a track downloads the xz-compressed subtitle from TsukiHime's storage, decompresses it, saves it next to the video (or a temp directory for remote/streamed media), and loads it into mpv. Japanese tracks are selected as mpv's **primary** subtitle. Tracks from the configured secondary tab are assigned to mpv's **secondary** subtitle slot without replacing the primary. The filename carries the track's language - `<video basename>.en.<ext>` for English, `.ja` for Japanese, and so on - so mpv and media servers detect the language correctly.
+You can also open the modal with `subminer app --open-tsukihime`, bind a key to `["__tsukihime-open"]` in `keybindings`, or change the shortcut with `shortcuts.openTsukihime`.
 
-Because releases on TsukiHime are the same files circulating as torrents, picking the release that matches your local file (same group, same version) gives you subtitles with exact timing - no resync needed. If your file is a raw or from a different group, pick any release of the same episode and adjust timing with the [subtitle sync tools](/troubleshooting#subtitle-sync-subsync) (`Ctrl+Alt+S`) if necessary.
+## Options
 
-### Modal Keyboard Shortcuts
+| Key                          | What it does                                           |
+| ---------------------------- | ------------------------------------------------------ |
+| `tsukihime.maxSearchResults` | Maximum releases per search. The API caps this at 100. |
+| `tsukihime.apiBaseUrl`       | API address. Change only for a mirror.                 |
 
-| Key                          | Action                          |
-| ---------------------------- | ------------------------------- |
-| `Enter` (in text field)      | Search                          |
-| `Enter` (in list)            | Select release / download track |
-| `Arrow Up` / `Arrow Down`    | Navigate releases or tracks     |
-| `Arrow Left` / `Arrow Right` | Switch English / Japanese tab   |
-| `Escape`                     | Close modal                     |
-
-## Configuration
-
-The integration works out of the box. An optional `tsukihime` section in `config.jsonc` tunes it:
-
-```jsonc
-{
-  "tsukihime": {
-    "apiBaseUrl": "https://api.tsukihime.org/v1",
-    "maxSearchResults": 10,
-  },
-}
-```
-
-| Option                       | Type     | Default                          | Description                                                                |
-| ---------------------------- | -------- | -------------------------------- | -------------------------------------------------------------------------- |
-| `tsukihime.apiBaseUrl`       | `string` | `"https://api.tsukihime.org/v1"` | Base URL of the TsukiHime API. Only change this if using a mirror.         |
-| `tsukihime.maxSearchResults` | `number` | `10`                             | Maximum number of releases returned per search (the API caps this at 100). |
-
-The keyboard shortcut is configured separately under `shortcuts`:
-
-```jsonc
-{
-  "shortcuts": {
-    "openTsukihime": "Ctrl+Shift+T", // default; set to null to disable
-  },
-}
-```
-
-Existing Animetosho configuration remains compatible. SubMiner treats the old `animetosho` section and `shortcuts.openAnimetosho` setting as deprecated aliases. When old and current names are both present, `tsukihime` and `shortcuts.openTsukihime` take precedence.
-
-## Other Ways to Open It
-
-- CLI: `subminer --open-tsukihime`
-- Keybinding command: bind any key to `["__tsukihime-open"]` in the `keybindings` array
-
-The previous `--open-animetosho` flag and `__animetosho-open` keybinding command remain accepted as deprecated aliases.
+See [Configuration](/configuration#tsukihime) for defaults.
 
 ## Troubleshooting
 
-- **"xz binary not found"** - install `xz`/`xz-utils` with your package manager.
-- **"Batch releases are not supported"** - TsukiHime only exposes extracted attachments for single-file torrents. Pick the single-episode release for your episode instead of a season batch.
-- **"No text subtitle tracks in this release"** - the release only carries image-based subtitles (PGS/VobSub) or none at all; try a different release (fansub and SubsPlease-style releases almost always carry ASS tracks).
-- **Timing is off** - the subtitle came from a different release than your video file. Use the subtitle sync modal (`Ctrl+Alt+S`) or pick the release matching your file exactly.
+**"xz binary not found."** Install `xz` or `xz-utils` with your package manager.
+
+**"No releases with Japanese subtitles."** None of the results carry a Japanese track. Try another search, or use Jimaku.
+
+**"Batch releases are not supported."** TsukiHime only has extracted tracks for single-file torrents. Pick the single-episode release.
+
+**"No text subtitle tracks in this release."** The release has only image-based subtitles (PGS or VobSub) or none. Try another release.
+
+**Timing is off.** The subtitle came from a different release than your video. Use subtitle sync (`Ctrl+Alt+S`) or pick the matching release.
diff --git a/docs-site/usage.md b/docs-site/usage.md
index e52d5f7b..51437003 100644
--- a/docs-site/usage.md
+++ b/docs-site/usage.md
@@ -1,388 +1,155 @@
 # Usage
 
-## Quick Start
+This page covers everyday use: starting playback, working with the overlay, and the commands you will reach for most. For every `subminer` subcommand and flag, see [Launcher script](/launcher-script).
 
-Play a video with SubMiner:
+## Play a video
 
 ```bash
 subminer video.mkv
 ```
 
-On **Windows**, use the **SubMiner mpv** shortcut created during first-run setup - double-click it, or drag a video file onto it.
+On Windows, double-click the **SubMiner mpv** shortcut or drag a video onto it.
 
-That's the simplest way to get started. The `subminer` launcher handles mpv, the IPC socket, and the overlay automatically.
+SubMiner starts mpv, connects to it, and opens the overlay. Subtitle lines appear as hoverable words. Hover a word to look it up, then mine it into Anki. [Mining workflow](/mining-workflow) covers lookup and card creation in detail.
 
-> [!IMPORTANT]
-> SubMiner requires the bundled Yomitan instance to have at least one dictionary imported for lookups to work.
-> See [Yomitan setup](#yomitan-setup) for details.
-
-::: tip Anki card enrichment
-If you want sentence, audio, and screenshot fields on your Anki cards, add this to your config:
-
-```jsonc
-{
-  "ankiConnect": {
-    "enabled": true,
-    "deck": "Mining",
-    "fields": {
-      "sentence": "Sentence",
-      "audio": "SentenceAudio",
-      "image": "Picture",
-    },
-  },
-}
-```
-
-Field names must match a field on your Anki note type. Matching is case-insensitive (an exact match wins, then a lowercase comparison), but the spelling must otherwise match. See [Anki Integration](/anki-integration) for the full reference.
-:::
-
-## How It Works
-
-When you launch SubMiner, it wires up mpv and the overlay for you:
-
-1. SubMiner starts the overlay app in the background
-2. mpv runs with an **IPC socket** at `/tmp/subminer-socket` - a small local channel two programs use to talk to each other, so the overlay can ask mpv what subtitle is on screen right now
-3. The overlay connects and subscribes to subtitle changes
-
-From there, subtitles render as interactive, hoverable word spans and you mine cards directly from the overlay. For the overlay anatomy and the full mining loop - word lookup, card creation, annotations - see [Mining Workflow](/mining-workflow).
-
-### Ways to Launch
-
-| Approach                            | Use when                                                                                                                               | How                                                                   |
-| ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
-| **`subminer` launcher**             | You want SubMiner to handle everything - launch mpv, set up the socket, start the overlay. **Recommended for most users.**             | `subminer video.mkv`                                                  |
-| **SubMiner mpv shortcut** (Windows) | The recommended Windows entry point. Created during first-run setup, launches mpv with SubMiner's defaults.                            | Double-click, drag a file onto it, or run `SubMiner.exe --launch-mpv` |
-| **mpv plugin** (all platforms)      | Bundled and injected at runtime. Provides `y` chord keybindings for controlling the overlay from within mpv. No manual install needed. | Automatic when using the launcher or shortcut                         |
-
-The mpv plugin is always available - it's bundled with SubMiner and injected at runtime. On Linux, normal `subminer` playback auto-installs the launcher-managed runtime plugin copy from the bundled app if that managed copy is missing, so no separate plugin install is needed for standard launcher usage. If you launch mpv yourself (without the launcher), pass `--input-ipc-server=/tmp/subminer-socket` in your mpv config for the overlay to connect.
-
-## Commands
-
-These are the commands you will actually use day to day. The full inventory of subcommands and flags lives in [Launcher Script](/launcher-script#subcommands).
-
-```bash
-subminer video.mkv                # Play a specific file
-subminer                          # Browse the current directory (fzf picker)
-subminer -R                       # Browse with the rofi picker instead
-subminer -d ~/Anime -r            # Browse a specific directory, recursively
-subminer -H                       # Browse watch history, then replay/next/previous
-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 app --setup              # Re-open first-run setup
-subminer -u                       # Check for updates
-```
-
-On **Windows** there is no `subminer` launcher. Use the **SubMiner mpv** shortcut for playback (see [Windows mpv Shortcut](#windows-mpv-shortcut)), and run `SubMiner.exe` directly for everything else.
-
-Two flags are worth knowing early:
-
-- `-a/--args` passes extra arguments straight to mpv, for example `subminer --args "--ao=alsa --volume=80" video.mkv`.
-- `--log-level debug` turns on verbose logging when something is not working.
-
-<details>
-<summary><b>Less common launcher commands</b></summary>
-
-```bash
-subminer --start video.mkv        # Explicit overlay start (when mpv.autoStartSubMiner is false)
-subminer -S video.mkv             # Also force the visible overlay on start
-subminer -T video.mkv             # Disable the texthooker server
-subminer -b x11 video.mkv         # Force a window backend
-subminer -p gpu-hq video.mkv      # Use a specific mpv profile
-subminer ytsearch:"jp news"       # Play the first YouTube search result
-subminer texthooker               # Texthooker-only mode (-o also opens the browser)
-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
-subminer config path              # Print the active config path
-subminer config show              # Print the active config contents
-subminer mpv socket               # Print the active mpv socket path
-subminer mpv status               # Exit 0 if the socket is ready, else exit 1
-subminer mpv idle                 # Launch a detached idle mpv with SubMiner defaults
-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>
-
-<details>
-<summary><b>Direct packaged-app flags (advanced)</b></summary>
-
-These call the app binary directly rather than going through the launcher. On Windows, replace `SubMiner.AppImage` with `SubMiner.exe`.
-
-```bash
-SubMiner.AppImage --background            # Start in background (tray + IPC wait, minimal logs)
-SubMiner.AppImage --start --texthooker    # Start overlay with texthooker
-SubMiner.AppImage --texthooker            # Texthooker only (no overlay window)
-SubMiner.AppImage --setup                 # Open first-run setup
-SubMiner.AppImage --stop                  # Stop overlay
-SubMiner.AppImage --start --toggle        # Start mpv IPC + toggle visibility
-SubMiner.AppImage --show-visible-overlay  # Force show the visible overlay
-SubMiner.AppImage --hide-visible-overlay  # Force hide the visible overlay
-SubMiner.AppImage --toggle-primary-subtitle-bar  # Toggle the primary subtitle bar
-SubMiner.AppImage --toggle-subtitle-sidebar      # Toggle the subtitle sidebar
-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 --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), 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>
-
-The tray menu includes `Export Logs`, which creates the same sanitized local-date log ZIP as `subminer logs -e` and shows the archive path when complete. Export sanitization masks common PII and secrets, including home-directory usernames, IP addresses, emails, auth/cookie headers, yt-dlp cookie arguments, URL credentials, token/key/password fields, and signed YouTube media URL query strings. The exported copy is sanitized; source log files remain unredacted on disk.
-
-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.
-- `--dev` and `--debug` use a separate `SubMiner-dev` profile. They do not read or modify dictionaries and configuration from the installed app unless `SUBMINER_USE_PRODUCTION_PROFILE=1` is explicitly 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.
-- On Linux, the app now defaults `safeStorage` to `gnome-libsecret` for encrypted token persistence.
-  Launcher pass-through commands also support `--password-store=<backend>` and forward it to the app when present.
-  Override with e.g. `--password-store=basic_text`.
-- Use both when needed, for example `SubMiner.AppImage --start --dev --log-level debug` (or `SubMiner.exe --start --dev --log-level debug` on Windows).
-- `--playback-feedback <text>` (also `--playback-feedback=<text>`) sends a non-empty text string through the playback-feedback route used for recording/playback prompts. For example: `SubMiner.AppImage --playback-feedback "your feedback"`.
-
-### Windows mpv Shortcut
-
-First-run setup creates the config file, then requires Yomitan dictionaries before it can finish.
-
-If you enabled the optional Windows shortcut during install, SubMiner creates a `SubMiner mpv` shortcut in the Start menu and/or on the desktop. On Windows, that shortcut is the recommended way to launch local files with SubMiner because it starts `mpv.exe` with the right defaults directly.
-After setup completes, the shortcut is the normal Windows playback entry point.
-
-You can use it three ways:
-
-- Double-click `SubMiner mpv` to open `mpv` with SubMiner's default socket/subtitle args.
-- Drag a video file onto `SubMiner mpv` to launch that file with the same defaults.
-- Run it directly from Command Prompt or PowerShell with `--launch-mpv`.
-
-```powershell
-& "C:\Program Files\SubMiner\SubMiner.exe" --launch-mpv
-& "C:\Program Files\SubMiner\SubMiner.exe" --launch-mpv "C:\Videos\episode 01.mkv"
-```
-
-This flow requires `mpv.exe` to be discoverable. Leave `mpv.executablePath` blank to auto-discover from `PATH`, or set it to the full `mpv.exe` path if mpv is installed elsewhere. `SUBMINER_MPV_PATH` is still honored as a fallback.
-
-### Launcher Subcommands
-
-The launcher groups related work under subcommands: `jellyfin` (aliased `jf`), `stats`, `sync`, `dictionary` (aliased `dict`), `texthooker`, `doctor`, `settings`, `config`, `mpv`, `logs`, and `app` (aliased `bin`) for passing arguments straight to the SubMiner binary.
-
-Every subcommand has its own help page, for example `subminer jellyfin -h`. See [Launcher Script - Subcommands](/launcher-script#subcommands) for the full table, and [Sync Between Machines](/launcher-script#sync-between-machines) for the SSH stats/history sync.
-
-A _texthooker_ is a web page that displays the current subtitle line as selectable text, so browser-based dictionary extensions and other tools can read along with playback.
-
-### First-Run Setup
-
-Setup popup appears on first launch, or when setup has not been completed.
-
-You can also open it manually:
-
-```bash
-subminer app --setup
-SubMiner.AppImage --setup
-```
-
-Setup flow:
-
-- config file: create the default config directory and prefer `config.jsonc`
-- legacy plugin cleanup: remove detected older global SubMiner mpv plugin files if present (the bundled plugin is injected at runtime automatically)
-- Yomitan shortcut: open bundled Yomitan settings directly from the setup window
-- dictionary check: ensure at least one bundled Yomitan dictionary is available, unless an external Yomitan profile is configured
-- Windows: optionally create or remove `SubMiner mpv` Start Menu/Desktop shortcuts (`SubMiner.exe --launch-mpv`)
-- Windows: optionally set `mpv.executablePath` if `mpv.exe` is not on `PATH`
-- refresh: re-check dictionary state without restarting
-- `Finish setup` stays disabled until the config and dictionary gates are satisfied
-- finish action writes setup completion state and suppresses future auto-open prompts
-
-AniList character dictionary auto-sync (optional):
-
-- Enable with `subtitleStyle.nameMatchEnabled=true` in config or **Name Match Enabled** in Settings.
-- SubMiner syncs the currently watched AniList media into a per-media snapshot, then rebuilds one merged `SubMiner Character Dictionary` from the most recently used snapshots.
-- Rotation limit defaults to 3 recent media snapshots in that merged dictionary (`maxLoaded`).
-
-Use subcommands for Jellyfin workflows (`subminer jellyfin ...`).
-Top-level launcher flags like `--jellyfin-*` are intentionally rejected.
-
-### MPV Profile Example (mpv.conf)
-
-`subminer` passes the following MPV options directly on launch by default:
-
-- `--input-ipc-server=/tmp/subminer-socket` (or your configured socket path)
-- `--alang=ja,jp,jpn,japanese,en,eng,english,enus,en-us`
-- `--slang=ja,jp,jpn,japanese,en,eng,english,enus,en-us`
-- `--sub-auto=fuzzy`
-- `--sub-file-paths=.;subs;subtitles`
-- `--sid=auto`
-- `--secondary-sid=auto`
-- `--sub-visibility=no` (the overlay renders subtitles instead of mpv)
-- `--secondary-sub-visibility=no`
-
-You can append additional MPV arguments with launcher `-a/--args`, for example `--args "--ao=alsa --volume=80"`.
-
-You can define a matching profile in `~/.config/mpv/mpv.conf` for consistency when launching `mpv` manually or from other tools. The Windows `SubMiner.exe --launch-mpv` shortcut path uses equivalent args directly, but skips the extra current-directory subtitle scan to avoid duplicate sidecar detection when you drag a video onto the shortcut; the optional profile remains useful for manual mpv launches. The `subminer` wrapper passes no mpv profile by default; set one with `subminer -p <profile> ...` or with `mpv.profile` in your config (for example `"profile": "subminer"` to use the `[subminer]` profile below):
-
-```ini
-[subminer]
-# IPC socket (must match SubMiner config)
-input-ipc-server=/tmp/subminer-socket
-
-# Prefer JP/EN audio + subtitle language variants
-alang=ja,jp,jpn,japanese,en,eng,english,enus,en-us
-slang=ja,jp,jpn,japanese,en,eng,english,enus,en-us
-
-# Auto-load external subtitles
-sub-auto=fuzzy
-sub-file-paths=.;subs;subtitles
-
-# Select primary + secondary subtitle tracks automatically
-sid=auto
-secondary-sid=auto
-secondary-sub-visibility=no
-```
+Run `subminer` with no file to pick one from the current directory instead. See [Picking files](#picking-files).
 
 ### Yomitan setup
 
-SubMiner includes a bundled Yomitan extension for overlay word lookup. This bundled extension is separate from any Yomitan browser extension you may have installed.
+Lookups need at least one dictionary in SubMiner's bundled Yomitan. First-run setup asks you to import one. To add more later, open Yomitan settings with `Alt+Shift+Y` or `subminer app --yomitan`.
 
-For SubMiner overlay lookups to work, open Yomitan settings (`subminer app --yomitan` or `SubMiner.AppImage --yomitan`) and import at least one dictionary in the bundled Yomitan instance.
+The bundled Yomitan is separate from any Yomitan in your browser. It has its own dictionaries and settings.
 
-If you also use Yomitan in a browser, configure that browser profile separately; it does not inherit dictionaries or settings from the bundled instance.
+## Picking files
 
-### YouTube Playback
+```bash
+subminer                    # fzf picker for the current directory
+subminer -d ~/Anime -r      # pick from a directory, searching subfolders
+subminer -R                 # rofi picker instead of fzf (Linux)
+subminer -H                 # watch history: replay, next, or previous episode
+```
 
-`subminer` accepts direct URLs (for example, YouTube links) and `ytsearch:` targets.
-For YouTube playback, SubMiner resolves subtitle selection during startup while mpv is paused: it auto-selects the default primary subtitle track plus a best-effort secondary track, then resumes when primary subtitles are ready.
+See [Launcher script](/launcher-script#video-picker) for picker and history details.
 
-Notes:
+## Overlay basics
 
-- Install `yt-dlp` so mpv can resolve YouTube streams and subtitle tracks reliably.
-- For YouTube URLs, startup no longer requires opening the picker first; SubMiner loads subtitles and keeps the overlay available for retries.
-- Press `Ctrl+Alt+C` during active YouTube playback to open the manual YouTube subtitle picker and retry track selection.
-- For YouTube URLs, `subminer` probes available YouTube subtitle tracks, reuses existing authoritative tracks when available, and downloads only missing sides.
-- Native mpv secondary subtitle rendering stays hidden so the overlay remains the visible secondary subtitle surface.
-- YouTube auto-selection always targets a Japanese primary track and an English secondary track (manual uploads preferred over auto-generated captions). `youtube.primarySubLanguages` (defaults to `["ja","jpn"]`) defines which loaded track counts as a satisfactory primary for the missing-subtitle notification and for managed local/playlist selection.
-- When multiple matching secondary tracks exist, SubMiner prefers a non-Signs/Songs track.
-- Configure defaults in `$XDG_CONFIG_HOME/SubMiner/config.jsonc` (or `~/.config/SubMiner/config.jsonc`) under `youtube` and `secondarySub`.
+| Key           | Action                                                                |
+| ------------- | --------------------------------------------------------------------- |
+| `Alt+Shift+O` | Show or hide the overlay (works while the overlay or mpv has focus)   |
+| `Alt+Shift+Y` | Open Yomitan settings (works from any window, not configurable)       |
+| `V`           | Cycle the subtitle bar through hidden, visible, and hover-only        |
+| `Ctrl+Alt+P`  | Open the playlist browser to queue, reorder, or jump between episodes |
+| `Ctrl/Cmd+/`  | Show every overlay and mpv keybinding for this session                |
 
-For local video files, SubMiner uses the same config-driven language priorities to auto-select the primary and secondary subtitle tracks from internal and external subtitle sources.
+Hovering subtitle text pauses mpv, and moving away resumes it. An open Yomitan popup also keeps playback paused. Turn these off with `subtitleStyle.autoPauseVideoOnHover` and `subtitleStyle.autoPauseVideoOnYomitanPopup`.
 
-## Live Config Reload
+You can drop files onto the overlay:
 
-While SubMiner is running, it watches your active config file and applies safe updates automatically.
+- A video replaces what is playing. Hold `Shift` to add it to the playlist instead.
+- A subtitle file loads as a new subtitle track.
 
-Live-updated settings include:
+The full list is in [Keyboard shortcuts](/shortcuts). The in-player `y` key chords are in [mpv plugin](/mpv-plugin).
 
-- `subtitleStyle`
-- `keybindings`
-- `shortcuts`
-- `secondarySub.defaultMode`
-- `subtitleSidebar`
-- `notifications`
-- `logging`
-- `jimaku`, `subsync`
-- `mpv.aniskipEnabled`, `mpv.aniskipButtonKey`
-- `stats.toggleKey`, `stats.markWatchedKey`
-- `youtube.primarySubLanguages`
-- most `ankiConnect.*` settings (including `ankiConnect.ai`)
+## YouTube playback
 
-Invalid config edits are rejected; SubMiner keeps the previous valid runtime config and shows an error notification.
-For restart-required sections, SubMiner shows a restart-needed notification.
+Pass a URL or a search. Install `yt-dlp` first.
 
-## Controller Support
+```bash
+subminer https://youtu.be/...
+subminer ytsearch:"jp news"     # play the first search result
+```
 
-SubMiner supports gamepad/controller input for couch-friendly usage via the Chrome Gamepad API. Controller input drives the overlay while keyboard-only mode is enabled.
+SubMiner picks subtitles during startup while mpv is paused. It selects a Japanese primary track and an English secondary track, downloads whatever is missing, and resumes once the primary subtitles are ready. If the choice is wrong, press `Ctrl+Alt+C` to open the YouTube subtitle picker and choose again.
 
-### Getting Started
+Language preferences live under `youtube` and `secondarySub` in the config. See [YouTube integration](/youtube-integration).
 
-1. Connect a controller before or after launching SubMiner.
-2. Set `controller.enabled` to `true` in your config.
-3. Press `Alt+C` in the overlay by default to pick the controller you want to save and remap any action inline.
-4. Enable keyboard-only mode - press `Y` on the controller (default binding) or use the overlay keybinding.
-5. Click the binding badge, edit pencil, or `Learn` on the overlay action you want, then press the matching button, trigger, or stick direction on the controller.
-6. Use the left stick to navigate subtitle tokens and scroll the popup; use the right stick vertically for popup page jumps.
-7. Press `A` to look up the selected word, `X` to mine a card, `B` to close the popup.
+## Common commands
 
-By default SubMiner uses the first connected controller after controller support is enabled. `Alt+C` opens the controller config modal, where you can save the preferred controller and remap bindings inline per controller. The reset button beside each edit pencil restores that binding to its built-in default for the selected controller. `Alt+Shift+C` opens the live debug modal with raw axes/button values for non-standard pads. Both modals stay closed while `controller.enabled` is false, and both shortcuts can be changed through `shortcuts.openControllerSelect` and `shortcuts.openControllerDebug`.
+```bash
+subminer stats                     # start the immersion stats dashboard
+subminer settings                  # open the settings window
+subminer doctor                    # check dependencies, config, and the mpv socket
+subminer generate-subs video.mkv   # make Japanese subtitles from the audio
+subminer logs -e                   # export a log ZIP for bug reports
+subminer app --setup               # reopen first-run setup
+subminer -u                        # update SubMiner
+```
 
-### Default Button Mapping
+Two flags help early on:
 
-| Button                  | Action                                  |
-| ----------------------- | --------------------------------------- |
-| `A` (South)             | Toggle lookup                           |
-| `B` (East)              | Close lookup                            |
-| `Y` (North)             | Toggle keyboard-only mode               |
-| `X` (West)              | Mine card                               |
-| `L1`                    | Play current Yomitan audio              |
-| `R1`                    | Next Yomitan audio track                |
-| `L3` (left stick press) | Toggle mpv pause                        |
-| `Select` / `Minus`      | Quit mpv                                |
-| `L2` / `R2`             | Unbound (available for custom bindings) |
+- `-a/--args` passes options to mpv, for example `subminer --args "--volume=80" video.mkv`.
+- `--log-level debug` turns on verbose logs when something is wrong.
 
-Note: the default quit binding uses gamepad button index 6. Pads that follow the W3C standard gamepad layout report L2 as index 6 (Select is index 8), so on those controllers the quit action may fire on L2 instead - use `Alt+C` learn mode to remap it for your pad.
+[Launcher script](/launcher-script) lists every command. Jellyfin, sync, and character dictionary commands are covered in [Jellyfin](/jellyfin-integration), [Sync between machines](/launcher-script#sync-between-machines), and [Character dictionary](/character-dictionary).
 
-### Analog Controls
+### Generate Japanese subtitles locally
 
-| Input                 | Action                                        |
-| --------------------- | --------------------------------------------- |
-| Left stick horizontal | Move token selection left/right               |
-| Left stick vertical   | Scroll Yomitan popup                          |
-| Right stick vertical  | Jump through Yomitan popup                    |
-| D-pad                 | Fallback for stick navigation when configured |
+`subminer generate-subs` transcribes audio with whisper.cpp and writes a Japanese SRT file. If that file is playing in mpv, it loads the new subtitles right away. Leave out the path to use the file mpv is playing.
 
-Learn mode ignores already-held inputs and waits for the next fresh button press or axis direction, which avoids accidental captures when you open the modal mid-input.
+```bash
+subminer generate-subs video.mkv --download-model   # download a model on first use
+subminer generate-subs video.mkv --model-path ~/models/ggml-medium.bin
+```
 
-All button and axis mappings are configurable under the `controller` config block. Learned remaps are saved under `controller.profiles` for the selected controller id. See [Configuration - Controller Support](/configuration#controller-support) for the full options.
+You need `whisper-cli`, `ffmpeg`, and `ffprobe`. Check the output before mining, since speech recognition makes mistakes over music and overlapping voices. See [Subtitle generation](/subtitle-generation) for models, timing references, and settings.
 
-## Keybindings
+## Windows mpv shortcut
 
-See [Keyboard Shortcuts](/shortcuts) for the full reference, including mining shortcuts, overlay controls, and customization.
+First-run setup can create a **SubMiner mpv** shortcut in the Start menu and on the desktop. It is the easiest way to play local files on Windows:
 
-**App-wide shortcuts:**
+- Double-click it to open mpv with SubMiner attached.
+- Drag a video onto it to play that file.
+- Run it from a terminal:
 
-| Keybind       | Action                 | Scope                                                                                              |
-| ------------- | ---------------------- | -------------------------------------------------------------------------------------------------- |
-| `Alt+Shift+O` | Toggle visible overlay | Works while the overlay or mpv has focus (configurable via `shortcuts.toggleVisibleOverlayGlobal`) |
-| `Alt+Shift+Y` | Open Yomitan settings  | OS-global - registered with the system, works from any window                                      |
+```powershell
+& "C:\Program Files\SubMiner\SubMiner.exe" --launch-mpv "C:\Videos\episode 01.mkv"
+```
 
-`Alt+Shift+Y` is fixed and not configurable. All other shortcuts can be changed under `shortcuts` in your config.
+mpv must be on `PATH`, or `mpv.executablePath` must point to `mpv.exe`. The `subminer` terminal command also works on Windows if you installed it during setup.
 
-Useful overlay-local default keybinding: `Ctrl+Alt+P` opens the playlist browser for the current video's parent directory and the live mpv queue so you can append, reorder, remove, or jump between episodes without leaving playback.
+## Tray menu
 
-Press `V` to cycle the primary SubMiner subtitle bar through hidden → visible → hover modes. The bundled mpv plugin also binds bare `v` to the same action (injected at runtime).
+The tray icon gives you:
 
-`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.
+- **Export Logs**: saves a log ZIP and shows its path. Usernames, IP addresses, emails, tokens, passwords, and cookies are masked in the exported copy. Your log files on disk stay unchanged.
+- **View Changelog**: release notes, including versions newer than yours. Use `J`/`K` to move between versions, `Enter` to expand one, and `Esc` to close.
+- **Sync Stats & History**: opens the [sync window](/launcher-script#sync-between-machines).
+- **Jellyfin Discovery**: turns cast discovery on or off for this session, once [Jellyfin](/jellyfin-integration) is set up.
 
-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.
+On Wayland, the tray icon only appears if your panel provides a StatusNotifier (AppIndicator) tray.
 
-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.
+## Controller support {#controller-support}
 
-### Drag-and-Drop
+You can drive the overlay with a gamepad.
 
-- Drop video files onto the overlay to replace current playback.
-- Hold `Shift` while dropping to append to the playlist instead.
-- Drop subtitle files onto the overlay to load them as a new subtitle track.
+1. Set `controller.enabled` to `true` in your config.
+2. Connect a controller. SubMiner uses the first one it sees.
+3. Press `Y` on the controller to turn on keyboard-only mode. The controller only works in this mode.
+4. Move between words with the left stick, press `A` to look one up, and `X` to mine it.
 
-Next: [Mining Workflow](/mining-workflow) - word lookup, card creation, and the full mining loop.
+Press `Alt+C` to choose a controller and remap buttons. Click an action's **Learn** button, then press the button you want. `Alt+Shift+C` shows raw input values for unusual pads.
+
+| Button                | Action                               |
+| --------------------- | ------------------------------------ |
+| `A` (South)           | Look up the selected word            |
+| `B` (East)            | Close the lookup                     |
+| `X` (West)            | Mine a card                          |
+| `Y` (North)           | Toggle keyboard-only mode            |
+| `L1`                  | Play the current Yomitan audio       |
+| `R1`                  | Next Yomitan audio source            |
+| `L3`                  | Pause or resume mpv                  |
+| `Select` / `Minus`    | Quit mpv                             |
+| Left stick            | Move between words, scroll the popup |
+| Right stick (up/down) | Jump through the popup               |
+
+On controllers that report the W3C standard layout, the default quit button lands on `L2` instead of `Select`. Remap it with `Alt+C`. All options are in [Configuration](/configuration#controller-support).
+
+## Development profiles
+
+`--dev` and `--debug` use a separate `SubMiner-dev` profile. They do not read or modify dictionaries and configuration from the installed app unless `SUBMINER_USE_PRODUCTION_PROFILE=1` is explicitly set. See [Development](/development#run-locally).
+
+## Changing settings while you watch
+
+SubMiner watches your config file and applies most changes without a restart, including subtitle style, keybindings, and most Anki settings. If a change needs a restart, SubMiner tells you. If the file has an error, it keeps the last working config and shows a notification. See [Configuration](/configuration).
+
+Next: [Mining workflow](/mining-workflow).
diff --git a/docs-site/websocket-texthooker-api.md b/docs-site/websocket-texthooker-api.md
index 9756bf3e..133e3bbc 100644
--- a/docs-site/websocket-texthooker-api.md
+++ b/docs-site/websocket-texthooker-api.md
@@ -1,72 +1,49 @@
-# WebSocket / Texthooker API & Integration
+# WebSocket and texthooker API
 
-**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.
+SubMiner streams the current subtitle over local WebSockets and serves a texthooker page, so browser tools and your own scripts can follow along. This page is the reference for building a client. If you only want subtitles in a browser tab for Yomitan, see [Texthooker page](#texthooker-integration-guide).
 
-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.
+| Surface               | Default                     | Purpose                                               |
+| --------------------- | --------------------------- | ----------------------------------------------------- |
+| `websocket`           | `ws://127.0.0.1:6677`       | Plain subtitle text                                   |
+| `annotationWebsocket` | `ws://127.0.0.1:6678`       | Subtitle text plus token metadata and rendered HTML   |
+| `texthooker`          | `http://127.0.0.1:5174`     | Bundled texthooker page, preconfigured for your setup |
+| mpv plugin            | `script-message subminer-*` | Start, stop, toggle, and status automation inside mpv |
 
-SubMiner exposes a small set of local integration surfaces for browser tools, automation helpers, and mpv-driven workflows:
+All servers bind to `127.0.0.1` only. There is no authentication.
 
-- **Subtitle WebSocket** at `ws://127.0.0.1:6677` by default for plain subtitle pushes.
-- **Annotation WebSocket** at `ws://127.0.0.1:6678` by default for token-aware clients.
-- **Texthooker HTTP UI** at `http://127.0.0.1:5174` by default for browser-based subtitle consumption.
-- **mpv plugin script messages** for in-player automation and extension.
+## Enable the services
 
-This page documents those integration points and shows how to build custom consumers around them.
-
-## 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 |
-
-## Enable and Configure the Services
-
-SubMiner's integration ports are configured in `config.jsonc`. All three services are **off by default** - the block below shows the values to set to turn them on.
+All three services are off by default. Turn on the ones you need in `config.jsonc`:
 
 ```jsonc
 {
   "websocket": {
     "enabled": "auto",
-    "port": 6677
+    "port": 6677,
   },
   "annotationWebsocket": {
     "enabled": true,
-    "port": 6678
+    "port": 6678,
   },
   "texthooker": {
     "launchAtStartup": true,
-    "openBrowser": false
-  }
+    "openBrowser": false,
+  },
 }
 ```
 
-### How startup behaves
+- `websocket.enabled`: `true` always starts the plain stream. `"auto"` starts it unless the external `mpv_websocket` plugin is installed at `~/.config/mpv/mpv_websocket`.
+- `annotationWebsocket.enabled`: starts the annotated stream. It is independent of `websocket`.
+- `texthooker.launchAtStartup`: starts the texthooker page with the app.
+- `texthooker.openBrowser`: opens the page in your browser when it starts.
 
-- `websocket.enabled` defaults to `false`. Set it to `"auto"` to start the basic subtitle websocket unless SubMiner detects the external `mpv_websocket` plugin, or `true` to always start it.
-- `annotationWebsocket.enabled` defaults to `false` and is independent from `websocket`. Set it to `true` to start the annotated stream.
-- `texthooker.launchAtStartup` defaults to `false`. Set it to `true` to start the local HTTP UI automatically.
-- `texthooker.openBrowser` controls whether SubMiner opens the texthooker page in your browser when it starts.
+See [Configuration](/configuration) for all related options.
 
-If you use the [mpv plugin](/mpv-plugin), it can also start a texthooker-only helper process. The launcher derives the plugin's texthooker setting from your SubMiner config (`texthooker.launchAtStartup`) and injects it at runtime - there is no plugin config file to edit.
+## Subtitle WebSocket
 
-## Developer API Documentation
+`ws://127.0.0.1:6677`. Use it when you only need the current line as text.
 
-### 1. Subtitle WebSocket
-
-Use the basic subtitle websocket when you only need the current subtitle line as plain text.
-
-- **Default URL:** `ws://127.0.0.1:6677`
-- **Transport:** local WebSocket server bound to `127.0.0.1`
-- **Direction:** server push only
-- **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. Annotation-only upgrades do not repeat the same line on this basic stream.
-
-#### Message shape
+The server pushes only; it ignores client messages. On connect it sends the latest subtitle if there is one, then a new message each time the subtitle changes. Reconnecting is up to the client.
 
 ```json
 {
@@ -77,28 +54,18 @@ When a client connects, SubMiner immediately sends the latest subtitle payload i
 }
 ```
 
-#### Field reference
+| Field      | Type   | Notes                                                              |
+| ---------- | ------ | ------------------------------------------------------------------ |
+| `version`  | number | Payload version, currently `1`                                     |
+| `text`     | string | Raw subtitle text                                                  |
+| `sentence` | string | HTML-escaped text with line breaks as `<br>`, no annotation markup |
+| `tokens`   | array  | Always empty on this stream                                        |
 
-| 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. |
+## Annotation WebSocket
 
-### 2. Annotation WebSocket
+`ws://127.0.0.1:6678`. The same token data the bundled texthooker uses. Prefer this stream for new clients. It keeps running when the plain stream is auto-disabled by `mpv_websocket`.
 
-Use the annotation websocket for custom clients that want the same structured token payload the bundled texthooker UI consumes.
-
-- **Default URL:** `ws://127.0.0.1:6678`
-- **Payload shape:** JSON payload with `text`, rendered `sentence` HTML, and token metadata
-- **Primary difference:** this stream is intended to stay on even when the basic websocket auto-disables because `mpv_websocket` is installed
-
-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
+When a line is not yet tokenized, the stream first sends it with an empty `tokens` array, then sends the annotated version when tokenization finishes. Treat each message as the complete current state and replace the previous one. The plain stream does not repeat the line for this upgrade.
 
 ```json
 {
@@ -127,79 +94,48 @@ On a tokenization cache miss, this stream first sends the cue as plain text with
 }
 ```
 
-Each annotation token may include:
+| Token field           | Type             | Notes                                                                          |
+| --------------------- | ---------------- | ------------------------------------------------------------------------------ |
+| `surface`             | string           | Display text                                                                   |
+| `reading`             | string           | Kana reading when available                                                    |
+| `headword`            | string           | Dictionary headword when available                                             |
+| `startPos` / `endPos` | number           | Character offsets in `text`                                                    |
+| `partOfSpeech`        | string           | SubMiner part-of-speech label                                                  |
+| `isMerged`            | boolean          | Token was merged from several parser tokens                                    |
+| `isKnown`             | boolean          | Word is known                                                                  |
+| `isNPlusOneTarget`    | boolean          | Token is the line's N+1 target                                                 |
+| `isNameMatch`         | boolean          | Token matched a character name                                                 |
+| `frequencyRank`       | number           | Frequency rank; omitted when unavailable or a name match                       |
+| `jlptLevel`           | string           | JLPT level; omitted when unavailable or a name match                           |
+| `className`           | string           | CSS class list for the token                                                   |
+| `frequencyRankLabel`  | string or `null` | Rank label, set only when the rank is within your frequency highlight settings |
+| `jlptLevelLabel`      | string or `null` | JLPT label for display                                                         |
 
-| 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 |
+### HTML markup
 
-### 3. HTML markup conventions
+`sentence` is HTML rendered by SubMiner. Each token is a `<span>` with these classes as they apply:
 
-The `sentence` field is pre-rendered HTML generated by SubMiner. Depending on token state, it can include classes such as:
-
-- `word`
-- `word-known`
-- `word-n-plus-one`
-- `word-name-match`
+- `word` on every token
+- one of `word-name-match`, `word-n-plus-one`, or `word-known`
 - `word-jlpt-n1` through `word-jlpt-n5`
-- `word-frequency-single`
-- `word-frequency-band-1` through `word-frequency-band-5`
+- `word-frequency-single`, or `word-frequency-band-1` through `word-frequency-band-5`, on words that are not known, N+1, or names
 
-SubMiner also adds tooltip-friendly data attributes when available:
+Spans also carry `data-reading`, `data-headword`, `data-frequency-rank`, and `data-jlpt-level` when available. For a fully custom UI, ignore `sentence` and render from `tokens`.
 
-- `data-reading`
-- `data-headword`
-- `data-frequency-rank`
-- `data-jlpt-level`
+## Texthooker page {#texthooker-integration-guide}
 
-If you need a fully custom UI, ignore `sentence` and render from `tokens` instead.
-
-## Texthooker Integration Guide
-
-### When to use the bundled texthooker page
-
-Use texthooker when you want a browser tab that:
-
-- updates live from current subtitles
-- works well with browser-based Yomitan setups
-- inherits SubMiner's coloring preferences and websocket URL automatically
-
-Start it with either:
+The bundled texthooker is a browser tab that updates live with the current subtitle, works with browser Yomitan, and uses SubMiner's colors. Start it with the app (`texthooker.launchAtStartup`) or from the launcher:
 
 ```bash
-subminer texthooker
-# or open the page immediately
-subminer texthooker -o
+subminer texthooker      # start the texthooker
+subminer texthooker -o   # start it and open the browser
 ```
 
-or by leaving `texthooker.launchAtStartup` enabled.
+SubMiner injects the page's settings into `window.localStorage` when it serves it: the WebSocket URL (`bannou-texthooker-websocketUrl`), the known, N+1, name, frequency, and JLPT coloring toggles, and CSS custom properties for the token colors. The page connects to the annotation stream if it is enabled, otherwise to the plain stream. With neither running, it has nothing to connect to.
 
-### What SubMiner injects into the page
+## Build a client
 
-When SubMiner serves the local texthooker UI, it injects bootstrap values into `window.localStorage`, including:
-
-- `bannou-texthooker-websocketUrl`
-- coloring toggles for known/N+1/name/frequency/JLPT styling
-- CSS custom properties for SubMiner's token colors
-
-That means the bundled page already knows which websocket to connect to and which color palette to use.
-
-### Build a custom websocket client
-
-Here is a minimal browser client for the annotation stream:
+A minimal browser client for the annotation stream:
 
 ```html
 <!doctype html>
@@ -221,7 +157,7 @@ Here is a minimal browser client for the annotation stream:
 </script>
 ```
 
-### Build a custom Node client
+A Node client:
 
 ```js
 import WebSocket from 'ws';
@@ -238,113 +174,15 @@ ws.on('message', (raw) => {
 });
 ```
 
-### Integration tips
+Tips:
 
-- Bind only to `127.0.0.1`; these services are local-only by design.
-- Handle empty `tokens` arrays gracefully because subtitle text can arrive before tokenization completes.
-- Reconnect on disconnect; SubMiner does not manage client reconnects for you.
-- Prefer `payload.text` for logging/automation and `payload.sentence` or `payload.tokens` for UI rendering.
+- Handle empty `tokens` arrays. Text can arrive before tokenization finishes.
+- Reconnect on disconnect yourself.
+- Use `text` for logging and automation, and `sentence` or `tokens` for display.
 
-## Plugin Development
+### Forward lines to a webhook
 
-SubMiner does **not** currently expose a general-purpose third-party plugin SDK inside the app itself. Today, the supported extension surfaces are:
-
-1. the local websocket streams
-2. the local texthooker UI
-3. the mpv Lua plugin's script-message API
-4. the launcher CLI
-
-### mpv script messages
-
-The mpv plugin accepts these script messages:
-
-```text
-script-message subminer-start
-script-message subminer-stop
-script-message subminer-toggle
-script-message subminer-menu
-script-message subminer-options
-script-message subminer-restart
-script-message subminer-status
-script-message subminer-autoplay-ready
-script-message subminer-stats-toggle
-script-message subminer-visible-overlay-shown
-script-message subminer-visible-overlay-hidden
-script-message subminer-managed-subtitles-loading
-script-message subminer-overlay-loading-ready
-script-message subminer-reload-session-bindings
-```
-
-The overlay/loading/session-binding messages are primarily sent by the SubMiner app to keep the plugin's state in sync. The AniSkip messages (`subminer-skip-intro`, `subminer-aniskip-refresh`) are handled by the SubMiner app over the mpv IPC socket while it is connected.
-
-The start command also accepts inline overrides:
-
-```text
-script-message subminer-start backend=hyprland socket=/custom/path texthooker=no log-level=debug
-```
-
-### Practical extension patterns
-
-#### Add another mpv script that coordinates with SubMiner
-
-Examples:
-
-- send `subminer-start` after your own media-selection script chooses a file
-- send `subminer-status` before running follow-up automation
-- send `subminer-aniskip-refresh` after you update title/episode metadata (handled by the SubMiner app)
-
-#### Build a launcher wrapper
-
-Examples:
-
-- open a media picker, then call `subminer /path/to/file.mkv`
-- launch browser-only subtitle tooling with `subminer texthooker -o`
-- disable the helper UI for a session with `subminer --no-texthooker video.mkv`
-
-#### Build an overlay-adjacent client
-
-Examples:
-
-- browser widget showing current subtitle + token breakdown
-- local vocabulary capture helper that writes interesting lines to a file
-- bridge service that forwards websocket events into your own workflow engine
-
-## Webhook Examples
-
-SubMiner does **not** currently send outbound webhooks by itself. The supported pattern is to consume the websocket locally and relay events into another system.
-
-That still makes webhook-style automation straightforward.
-
-### Example: forward subtitle lines to a local webhook receiver
-
-```js
-import WebSocket from 'ws';
-
-const ws = new WebSocket('ws://127.0.0.1:6678');
-
-ws.on('message', async (raw) => {
-  const payload = JSON.parse(String(raw));
-
-  await fetch('http://127.0.0.1:5678/subminer/subtitle', {
-    method: 'POST',
-    headers: { 'content-type': 'application/json' },
-    body: JSON.stringify({
-      text: payload.text,
-      tokens: payload.tokens,
-      receivedAt: new Date().toISOString(),
-    }),
-  });
-});
-```
-
-### Automation ideas
-
-- **n8n / Make / Zapier relay:** send each subtitle line into an automation workflow for logging, translation, or summarization.
-- **Discord / Slack notifier:** post only lines that contain unknown words or N+1 targets.
-- **Obsidian / Markdown capture:** append subtitle lines plus token metadata to a daily immersion note.
-- **Local LLM pipeline:** trigger a glossary, translation, or sentence-mining workflow whenever a new line arrives.
-
-### Filtering example: only forward N+1 lines
+SubMiner does not send webhooks itself. Relay the stream to your own endpoint instead. This example forwards only lines that contain an N+1 target:
 
 ```js
 import WebSocket from 'ws';
@@ -354,7 +192,6 @@ const ws = new WebSocket('ws://127.0.0.1:6678');
 ws.on('message', async (raw) => {
   const payload = JSON.parse(String(raw));
   const hasNPlusOne = payload.tokens.some((token) => token.isNPlusOneTarget);
-
   if (!hasNPlusOne) return;
 
   await fetch('http://127.0.0.1:5678/subminer/n-plus-one', {
@@ -365,18 +202,39 @@ ws.on('message', async (raw) => {
 });
 ```
 
-## Recommended Integration Combinations
+The same pattern works for n8n or Zapier workflows, Discord notifiers, or appending lines to a notes file.
 
-- **Browser Yomitan client:** `texthooker` + `annotationWebsocket`
-- **Custom dashboard:** `annotationWebsocket` only
-- **Lightweight subtitle mirror:** `websocket` only
-- **mpv-side automation:** mpv plugin script messages + optional websocket relay
-- **Webhook-style workflows:** `annotationWebsocket` + your own local relay service
+## mpv script messages
 
-## Related Pages
+SubMiner has no in-app plugin SDK. Besides the streams above, you can drive it from other mpv scripts and from the [launcher CLI](/launcher-script).
 
-- [Configuration](/configuration#websocket-server)
-- [Mining Workflow - Texthooker](/mining-workflow#texthooker)
-- [MPV Plugin](/mpv-plugin)
-- [Launcher Script](/launcher-script)
-- [Anki Integration](/anki-integration#proxy-mode-setup-yomitan-texthooker)
+The mpv plugin accepts these script messages:
+
+| Message                 | Action                                     |
+| ----------------------- | ------------------------------------------ |
+| `subminer-start`        | Start the overlay                          |
+| `subminer-stop`         | Stop the overlay                           |
+| `subminer-toggle`       | Toggle the visible overlay                 |
+| `subminer-menu`         | Open the plugin menu                       |
+| `subminer-options`      | Open the SubMiner settings window          |
+| `subminer-restart`      | Restart the overlay                        |
+| `subminer-status`       | Show overlay status on the mpv OSD         |
+| `subminer-stats-toggle` | Show an OSD hint for the overlay stats key |
+
+`subminer-start` accepts overrides for `backend` (`auto`, `hyprland`, `sway`, `x11`, `macos`), `socket`, `texthooker`, and `log-level`:
+
+```text
+script-message subminer-start backend=hyprland socket=/custom/path texthooker=no log-level=debug
+```
+
+The plugin also registers `subminer-autoplay-ready`, `subminer-visible-overlay-shown`, `subminer-visible-overlay-hidden`, `subminer-managed-subtitles-loading`, `subminer-overlay-loading-ready`, and `subminer-reload-session-bindings`. The SubMiner app sends these to keep the plugin in sync, so do not send them from your own scripts.
+
+While the app is connected to mpv, it also handles two AniSkip messages over the mpv IPC socket: `subminer-skip-intro` skips the intro, and `subminer-aniskip-refresh` reloads intro data, for example after your script changes title or episode metadata.
+
+## Related pages
+
+- [Configuration](/configuration)
+- [Mining workflow](/mining-workflow)
+- [mpv plugin](/mpv-plugin)
+- [Launcher script](/launcher-script)
+- [Anki integration](/anki-integration)
diff --git a/docs-site/youtube-integration.md b/docs-site/youtube-integration.md
index ac1dbdb9..8017cccb 100644
--- a/docs-site/youtube-integration.md
+++ b/docs-site/youtube-integration.md
@@ -1,158 +1,63 @@
-# YouTube Integration
+# YouTube integration
 
-SubMiner auto-loads Japanese subtitles when you play a YouTube URL, giving you the same sentence-mining overlay experience as local video files. It probes available subtitle tracks via `yt-dlp`, selects the best primary and secondary tracks, downloads them, and loads them into mpv before playback resumes.
+Play a YouTube URL and SubMiner downloads its Japanese subtitles and loads them into mpv, so you can mine from it like a local file.
 
-## Requirements
+## Setup
 
-- **[yt-dlp](https://github.com/yt-dlp/yt-dlp)** must be installed and on your `PATH`. yt-dlp is a free command-line tool that reads YouTube video and subtitle info; SubMiner calls it behind the scenes. (`PATH` is the list of folders your system searches for programs - most installers add yt-dlp to it automatically. If yours did not, set `SUBMINER_YTDLP_BIN` to the full path of the yt-dlp binary.)
-- mpv with `--input-ipc-server` configured (handled automatically when you launch playback through the `subminer` launcher - no manual setup needed).
+Install [yt-dlp](https://github.com/yt-dlp/yt-dlp) and make sure it is on your `PATH`. If it is somewhere else, set `SUBMINER_YTDLP_BIN` to the full path of the binary.
 
-## How It Works
+## Usage
 
-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. 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.
-5. **Load** --- Subtitle files are injected into mpv via `sub-add`. Playback resumes once the primary track is ready; secondary failures do not block.
-
-## Pipeline Diagram
-
-```mermaid
-flowchart TD
-    classDef step fill:#c6a0f6,stroke:#494d64,color:#24273a
-    classDef action fill:#8aadf4,stroke:#494d64,color:#24273a
-    classDef result fill:#a6da95,stroke:#494d64,color:#24273a
-    classDef enrich fill:#8bd5ca,stroke:#494d64,color:#24273a
-    classDef ext fill:#eed49f,stroke:#494d64,color:#24273a
-
-    A[YouTube URL detected]:::step
-    B[yt-dlp probe]:::ext
-    C[Track discovery]:::action
-    D{Auto or manual selection?}:::step
-    E[Auto-select best tracks]:::action
-    F[Manual picker - Ctrl+Alt+C]:::action
-    G[Download subtitle files]:::action
-    H[Convert TimedText to VTT]:::enrich
-    I[Normalize auto-caption duplicates]:::enrich
-    K[sub-add into mpv]:::action
-    L[Overlay renders subtitles]:::result
-
-    A --> B
-    B --> C
-    C --> D
-    D -- startup --> E
-    D -- user request --> F
-    E --> G
-    F --> G
-    G --> H
-    H --> I
-    I --> K
-    K --> L
+```bash
+subminer https://www.youtube.com/watch?v=VIDEO_ID
+subminer ytsearch:"keyword"     # plays the first search result
 ```
 
-## Auto-Load Flow
+mpv starts paused while SubMiner fetches the subtitle list. It picks a primary and a secondary track, loads them, and resumes playback once the primary track is ready. A playlist link plays only the linked video.
 
-On startup with a YouTube URL:
+SubMiner picks tracks in this order. Manual (uploaded) tracks win over auto-generated captions.
 
-1. mpv launches paused.
-2. SubMiner calls `yt-dlp --dump-single-json` to probe all subtitle tracks.
-3. Tracks are split into **manual** (human-uploaded) and **auto** (machine-generated) categories.
-4. The selection algorithm picks:
-   - **Primary**: first Japanese manual track, then Japanese auto track, then any manual track, then first available track.
-   - **Secondary**: first English manual track, then English auto track (excluding the primary).
-5. If mpv already exposes an authoritative matching track, SubMiner reuses it instead of downloading again.
-6. Missing tracks are downloaded to a temp directory and loaded via `sub-add`.
-7. Playback unpauses once the primary subtitle is ready.
+| Track     | Choice                                                                           |
+| --------- | -------------------------------------------------------------------------------- |
+| Primary   | Japanese manual, then Japanese auto, then any manual track, then the first track |
+| Secondary | English manual, then English auto. Skipped if none exists.                       |
 
-## Manual Subtitle Picker
+Press `Ctrl+Alt+C` during playback to open the subtitle picker. It lists every track with its language and kind, and lets you choose different primary and secondary tracks or retry a failed load.
 
-Press **Ctrl+Alt+C** during YouTube playback to open the subtitle picker overlay. This lets you:
+## Secondary subtitle languages
 
-- Browse all discovered tracks (manual and auto-generated)
-- Select different primary and secondary tracks
-- Retry track loading if the auto-load failed or picked the wrong track
+YouTube secondary selection is fixed to English. `secondarySub.secondarySubLanguages` and `secondarySub.autoLoadSecondarySub` apply only to local files and Jellyfin. `secondarySub.defaultMode` still controls how the secondary bar is shown. Use the picker to load a different secondary language.
 
-SubMiner shows an "Opening YouTube subtitle picker..." status through your configured notification
-surface while it probes tracks and prepares the modal, then updates the subtitle download progress
-card to a success notification after the selected tracks load.
+Likewise, `youtube.primarySubLanguages` does not change which YouTube track is picked. It sets which languages count as a primary subtitle for local and playlist subtitle selection and for the "primary subtitle missing" notification.
 
-The picker displays each track with its language, kind (manual/auto), and title when available.
+## Card media
 
-## Subtitle Format Handling
-
-SubMiner handles several YouTube subtitle formats transparently:
-
-| Format                 | Handling                                                 |
-| ---------------------- | -------------------------------------------------------- |
-| `srt`, `vtt`           | Used directly (preferred for manual tracks)              |
-| `srv1`, `srv2`, `srv3` | YouTube TimedText XML --- converted to VTT automatically |
-| Auto-generated VTT     | Normalized to remove rolling-caption text duplication    |
-
-For auto-generated tracks, SubMiner prefers `srv3` > `srv2` > `srv1` > `vtt` (TimedText XML produces cleaner output). For manual tracks, `srt` > `vtt` is preferred.
-
-## Card Media Cache
-
-By default, YouTube card audio and screenshots are extracted directly from mpv's active stream URLs. If generated card media fails with YouTube `403` errors, set `youtube.mediaCache.mode` to `"background"`. Background mode starts a separate `yt-dlp` media download after playback loads, including YouTube URLs opened directly in mpv and resolved stream URLs when mpv still exposes the original YouTube playlist entry. It creates text fields immediately, queues audio/image work for mined notes, and fills those fields once the local cache file is ready.
-
-Background cache downloads are capped at 720p by default (`youtube.mediaCache.maxHeight`; set `0` for unlimited) and use IPv4 and retry flags to reduce YouTube throttling failures. If the background download still fails, SubMiner shows a cache failure notification, shows queued-card failure notifications, and clears those pending updates so cards are not left waiting silently.
-
-## Configuration Reference
-
-### Primary Subtitle Languages
+By default, card audio and screenshots are cut from mpv's live YouTube stream. If card media fails with `403` errors, switch to the background cache:
 
 ```jsonc
 {
   "youtube": {
-    "primarySubLanguages": ["ja", "jpn"],
+    "mediaCache": { "mode": "background" },
   },
 }
 ```
 
-| 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. |
+In background mode, SubMiner downloads the video with yt-dlp after playback starts. Cards you mine get their text fields right away, and audio and images are added once the download finishes. `youtube.mediaCache.maxHeight` caps the download resolution (`0` for no limit). If the download fails, SubMiner tells you and drops the pending media updates.
 
-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.
+See [Configuration](/configuration#youtube-playback-settings) for all `youtube` options and defaults.
 
-### Secondary Subtitle Languages
+## Troubleshooting
 
-YouTube secondary selection is fixed: SubMiner always tries an English track (manual over auto) and loads it when found. The shared `secondarySub` config does not change YouTube track selection — `secondarySubLanguages` and `autoLoadSecondarySub` apply only to local/Jellyfin sidecar selection — but `defaultMode` still controls how the loaded secondary bar is displayed:
+**No Japanese subtitles.** The video may not have any. Open the picker with `Ctrl+Alt+C` to see what is available.
 
-```jsonc
-{
-  "secondarySub": {
-    "secondarySubLanguages": [],
-    "autoLoadSecondarySub": false,
-    "defaultMode": "hover",
-  },
-}
-```
+**yt-dlp not found.** Install it and put it on `PATH`, or set `SUBMINER_YTDLP_BIN`.
 
-| 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"`)                                                                                                                                   |
+**Timeouts.** Each yt-dlp call times out after 15 seconds. Slow or rate-limited connections can hit this. Retry, or update yt-dlp.
 
-These settings come from `config.jsonc` (or built-in defaults); there are no CLI flags or environment variables for subtitle language selection.
+**Poor subtitle quality.** Auto-generated captions are often inaccurate. SubMiner uses a manual track when one exists.
 
-## Limitations and Troubleshooting
+A missing or failed secondary track never blocks playback.
 
-- **No subtitles found**: The video may not have Japanese subtitles. Open the picker with `Ctrl+Alt+C` to see all available tracks.
-- **yt-dlp not found**: Install `yt-dlp` and ensure it is on `PATH`, or set `SUBMINER_YTDLP_BIN` to the binary path.
-- **Probe timeout**: `yt-dlp` has a 15-second timeout per operation. Slow connections or rate-limited IPs may hit this. Retry or update `yt-dlp`.
-- **Card media `403` errors**: Switch `youtube.mediaCache.mode` from `"direct"` to `"background"` so card media is generated from a local `yt-dlp` cache instead of ffmpeg reading an expiring YouTube stream URL.
-- **Auto-caption quality**: YouTube auto-generated captions vary in quality. Manual subtitles (when available) are always preferred.
-- **`ytsearch:` targets**: `subminer ytsearch:"keyword"` plays the first search result. Subtitle availability depends on the matched video.
-- **Secondary subtitle fails**: Secondary track failures never block playback. The primary subtitle loads independently.
-- **Native mpv secondary rendering**: Stays hidden during YouTube flows so the SubMiner overlay remains the visible secondary subtitle surface.
+## Stats
 
-## Related Pages
-
-- [Usage --- YouTube Playback](/usage#youtube-playback)
-- [Configuration --- YouTube Playback Settings](/configuration#youtube-playback-settings)
-- [Configuration --- Secondary Subtitles](/configuration#secondary-subtitles)
-- [Keyboard Shortcuts](/shortcuts)
-- [Jellyfin Integration](/jellyfin-integration)
+The stats Library groups YouTube videos by channel. Choose **YouTube** in the Library filter to see them. See [Immersion tracking](/immersion-tracking).
diff --git a/docs/RELEASING.md b/docs/RELEASING.md
index f815bebe..e11b7e91 100644
--- a/docs/RELEASING.md
+++ b/docs/RELEASING.md
@@ -6,11 +6,46 @@
 
 - `claude` (Claude Code CLI) installed, on `PATH`, and authenticated.
   `changelog:build` and `changelog:prerelease-notes` invoke
-  `claude -p --model sonnet` to merge and rewrite `changes/*.md` fragments into
+  `claude -p --model opus --effort medium` to merge and rewrite `changes/*.md` fragments into
   a polished, user-facing release body. Either OAuth login (`claude /login`) or
   `ANTHROPIC_API_KEY` works. Install from <https://claude.com/claude-code> if
   you don't already have it.
 
+## Package contents checks
+
+Stable and prerelease workflows share `.github/workflows/package-release.yml`.
+Both callers explicitly pass the five required macOS signing/notarization
+secrets plus the optional `SUBMINER_TMDB_API_KEY` (the project TMDB key that
+`scripts/prepare-build-assets.mjs` stages into `dist/bundled-integration-keys.json`;
+artifacts built without it simply require users to set `tmdb.apiKey`).
+`GITHUB_TOKEN` remains automatically available to the reusable workflow.
+Each platform verifies its ASAR and external resources before signing. Missing
+runtime assets, foreign SQLite/Koffi binaries, duplicate UI fonts, demo media,
+source maps, TypeScript files, and nested test or fixture directories fail the build.
+Current targets are Linux x64, macOS arm64, and Windows x64.
+
+The runtime allowlist includes `dist/`, `stats/dist/`, and
+`vendor/texthooker-ui/docs/` plus metadata, config example, and license. The
+texthooker `docs/` directory is its built UI. Keep the positive `package.json`
+pattern in platform `files` lists: electron-builder otherwise treats an
+exclusion-only platform list as a separate include-all matcher. Windows keeps
+only its target Koffi binary; other platforms omit Koffi. Desktop UIs share the
+original M PLUS 1 TTF in `dist/fonts/`.
+
+The shared workflow runs `bun run test:package <resources-directory>` with the
+pinned Electron runtime and temporary user data. On headless Linux, prefix it
+with `xvfb-run -a`. This checks packaged SQLite, Windows FFI loading/polling,
+texthooker serving, Yomitan loading, UI assets, and Japanese font loading.
+Standalone pages lack app IPC handlers and can log related errors; this check
+does not replace an installed app session.
+
+Before shipping packaging changes, check each platform's installed app:
+startup and mpv tracking, dictionary lookup and stroke orders, settings/sync UI,
+stats persistence, sentence mining with AnkiConnect, and updating from the prior
+release. Preserve Electron locales, graphics fallbacks, codecs, dictionaries,
+license notices, updater metadata, blockmaps, and the macOS updater ZIP. Trim
+files before signing and generating updater hashes, never from a signed app.
+
 ## Stable Release
 
 1. Confirm `main` is green: `gh run list --workflow CI --limit 5`.
@@ -31,6 +66,14 @@
    `bun run test:fast`
    `bun run test:env`
    `bun run build`
+   Confirm `dist/launcher` contains only `subminer`, `subminer.cmd`,
+   `subminer.js`, `prepare.cjs`, and `version`. Release CI smoke-tests
+   `subminer.js` with Bun, then publishes both wrapper files and their checksums.
+   Tagged CI runs `bun scripts/package-bun-source.mjs` and must publish
+   `bun-v<version>-source.tar.gz` plus its `.sha256` file. The script
+   fails if Bun's CMake dependency pins, WebKit pin, source checksums, patch
+   inputs, or collected license files differ from
+   `build/bun-source-manifest.json`.
    When validating auto-update metadata, also run the relevant platform package
    build and confirm `release/` contains the generated updater metadata
    (`latest*.yml`) and blockmaps (`*.blockmap`).
@@ -54,16 +97,24 @@
    `bun run test:fast`
    `bun run test:env`
    `bun run build`
+   Confirm both launcher wrappers and their checksums are included in the
+   prerelease assets.
+   Prerelease CI also assembles and publishes the pinned Bun corresponding
+   source archive. A missing source repository or license file fails the
+   release instead of publishing only the executable.
    When validating packaged updater output, confirm the platform build writes
    `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 +129,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.
@@ -89,9 +142,10 @@ Notes:
 - Tagged release workflow now also attempts to update `subminer-bin` on the AUR after GitHub Release publication.
 - Stable release tags update `https://docs.subminer.moe/` and `https://docs.subminer.moe/v/<version>/` through `.github/workflows/docs-pages.yml`; `/main/` continues to show development docs from `main`.
 - Keep Cloudflare Pages Git auto-deploy disabled for `docs.subminer.moe`. Production docs are direct-uploaded by Wrangler from GitHub Actions with `--branch main`.
-- AUR publish is best-effort: the workflow retries transient SSH clone/push failures, then warns and leaves the GitHub Release green if AUR still fails. Follow up with a manual `git push aur master` from the AUR checkout when needed.
+- AUR publish is best-effort: the workflow downloads the three known assets directly from the tagged release URLs, avoiding GitHub's sometimes-stale release asset listing. Downloads and SSH clone/push operations retry transient failures, then warn and skip AUR publication if retries are exhausted. Follow up with a manual `git push aur master` from the AUR checkout when needed.
 - Required GitHub Actions secret: `AUR_SSH_PRIVATE_KEY`. Add the matching public key to your AUR account before relying on the automation.
 - Release and prerelease workflows upload updater metadata (`latest*.yml`) and blockmaps (`*.blockmap`) alongside platform artifacts. Do not remove those files while `electron-updater` is enabled.
+- Release and prerelease workflows publish `subminer` for POSIX systems and `subminer.cmd` for Windows. Both locate a packaged app and use its private Bun runtime. Keep the corresponding-source archive named `bun-v1.3.5-source.tar.gz`.
 - macOS tray app updates use the standard `electron-updater`/Squirrel path. Keep `latest-mac.yml`, the macOS `SubMiner-<version>-mac.zip`, and ZIP blockmap published; Squirrel uses the ZIP payload even when the DMG remains the user-facing installer.
 - macOS update metadata and full ZIP downloads are routed through `/usr/bin/curl` before Squirrel installation to avoid Electron main-process network crashes on update checks.
 - Windows tray app updates use the standard `electron-updater`/NSIS path. Keep `latest.yml`, the Windows NSIS installer, and installer blockmap published; updater HTTP is routed through main-process fetch to avoid Electron main-process network crashes during update checks.
diff --git a/docs/architecture/2026-03-15-renderer-performance-design.md b/docs/architecture/2026-03-15-renderer-performance-design.md
index 4d82583e..809d6b8b 100644
--- a/docs/architecture/2026-03-15-renderer-performance-design.md
+++ b/docs/architecture/2026-03-15-renderer-performance-design.md
@@ -87,7 +87,9 @@ interface 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.
+**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
 
diff --git a/docs/architecture/README.md b/docs/architecture/README.md
index a0c4858a..58eb074b 100644
--- a/docs/architecture/README.md
+++ b/docs/architecture/README.md
@@ -10,11 +10,15 @@ Read when: runtime ownership, composition boundaries, or layering questions
 SubMiner runs as three cooperating runtimes:
 
 - Electron desktop app in `src/`
-- Launcher CLI in `launcher/`
+- Launcher CLI in `launcher/`, with managed app-installed wrappers in `src/main/runtime/managed-launcher.ts`
 - mpv Lua plugin in `plugin/subminer/`
 
 The desktop app keeps `src/main.ts` as composition root and pushes behavior into small runtime/domain modules.
 
+Packaged apps include a private Bun runtime. Setup and release assets provide bootstrap wrappers generated from `src/main/runtime/*-launcher-bootstrap.ts`. macOS runs Bun and the CLI from app resources. Windows stages a versioned private Bun copy under `%LOCALAPPDATA%\SubMiner\launcher-runtime/<version>` so a running launcher does not lock the updater-owned app executable. Linux stages Bun, the matching CLI, and licenses under `${XDG_DATA_HOME:-~/.local/share}/SubMiner/launcher`. Its steady-state path performs one app `stat` and starts the cache without Electron. A missing cache or changed app fingerprint runs `launcher/prepare.cjs` through Electron's Node mode to refresh it. Desktop startup migrates recognized writable legacy JavaScript launchers and refreshes managed payloads after app changes. Development commands still use system Bun.
+
+Update checks and startup launcher migration share a serialized update-state store. Deferred launcher paths are acknowledged only after migration succeeds or the candidate is no longer eligible. Running Windows launchers and unreadable or unwritable candidates remain pending for a later startup.
+
 ## Read Next
 
 - [Domains](./domains.md) - who owns what
@@ -26,7 +30,13 @@ The desktop app keeps `src/main.ts` as composition root and pushes behavior into
 
 - `src/main/` owns composition, runtime setup, IPC wiring, and app lifecycle adapters.
 - `src/main/boot/` owns boot-phase assembly seams so `src/main.ts` can stay focused on lifecycle coordination and startup-path selection.
+- `src/main/runtime/linux-overlay-mode-runtime.ts` owns Linux fullscreen mode state and window replacement. App cleanup cancels pending replacements; `main.ts` supplies window creation and subtitle refresh hooks.
 - `src/core/services/` owns focused runtime services plus pure or side-effect-bounded logic.
+- `src/core/services/subtitle-generation*.ts` shares local whisper.cpp transcription, safe model downloads, and progress between the launcher and Electron. Optional dialogue mode retains both Silero-detected speech and other audible sections, omits confidently silent gaps, decodes passages independently, and restores original media timing. `src/main/runtime/subtitle-generation-runtime.ts` owns the overlay job lifecycle and only loads completed subtitles into the same local media; `src/shared/subtitle-generation*.ts` owns configuration, the multilingual model catalog, and IPC contracts. The overlay runtime retains a session model selection, validates picker requests through IPC, and keeps external model paths authoritative.
+- Subtitle model recommendations use bounded `nvidia-smi` and Whisper CUDA discovery probes in `subtitle-generation-acceleration.ts`. The overlay runtime caches results by executable path for 30 seconds and exposes acceleration status through the existing status IPC. Recommendations do not alter model selection or transcription arguments.
+- `subtitle-generation-reference.ts` ranks mpv's loaded text subtitle tracks, excludes signs/songs and forced references, and extracts timing hints with FFmpeg. The overlay and launcher snapshot references only for matching media, including active subtitle delays. Hints guide long-passage cuts with or without VAD; they never limit audio coverage or replace Whisper timestamps.
+- `src/main/runtime/subtitle-selection.ts` reads and validates mpv subtitle tracks and applies primary/secondary selections. Its opt-in session shortcut opens the shared overlay modal window, with renderer focus and subtitle suppression handled by the modal registry.
+- `src/shared/session-key-sequences.ts` rejects sequence prefixes reserved by single-key actions. The session-binding compiler reserves configured and built-in overlay keys; `src/main/runtime/session-bindings-runtime.ts` adds active mpv bindings and publishes the effective list to both the plugin artifact and the renderer through `session-bindings:changed`. mpv no-op `ignore` bindings do not reserve prefixes.
 - `src/renderer/` owns overlay rendering and input behavior.
 - `src/config/` owns config definitions, defaults, loading, and resolution.
 - `src/types/` owns shared cross-runtime contracts via domain entrypoints; `src/types.ts` stays a compatibility barrel.
@@ -40,3 +50,7 @@ The desktop app keeps `src/main.ts` as composition root and pushes behavior into
 - Composition over monoliths
 - Pure helpers where possible
 - Stable user behavior while internals evolve
+
+Startup resolves and creates the user-data directory in `src/main-entry-runtime.ts`
+before the entry process requests Electron's single-instance lock. Main-process
+config bootstrap then writes the default config only when no config file exists.
diff --git a/docs/architecture/domains.md b/docs/architecture/domains.md
index f35eae38..1cb956e9 100644
--- a/docs/architecture/domains.md
+++ b/docs/architecture/domains.md
@@ -21,13 +21,17 @@ Read when: you need to find the owner module for a behavior or test surface
   `src/config/resolve/anki-connect/`
 - Overlay/window state: `src/core/services/overlay-*`, `src/main/overlay-*.ts`
 - MPV runtime and protocol: `src/core/services/mpv*.ts`
+  Windows executable lookup and detached process creation are shared in `src/main/runtime/mpv-process.ts`. The Windows launcher and Jellyfin handlers retain their own playback and connection workflows.
 - Subtitle/token pipeline: `src/core/services/subtitle-*.ts`, `src/core/services/tokenizer*`, `src/core/services/tokenizer/`, `src/subsync/`
 - 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.
+- Immersion sync: `src/core/services/stats-sync/`, bound by `src/main/sync-cli.ts`.
+  `snapshot-transfer.ts` selects compressed rsync or scp. `transfer-cache.ts` atomically retains the last successfully received snapshot per hashed peer/database identity under the config directory's `sync-transfer-cache/`. Cache copies seed isolated transfer directories; rsync verifies reconstructed files before the existing merge engine runs. The `--make-temp` / `--remove-temp` helpers accept an internal `--transfer-cache` key, with a fallback for older peers that do not recognize it.
 - AniList tracking + character dictionary: `src/core/services/anilist/`, `src/main/runtime/composers/anilist-*`, `src/main/character-dictionary-runtime.ts`, `src/main/character-dictionary-runtime/`
+- TMDB live-action metadata: `src/core/services/tmdb/` (client + exact-title resolver), `src/core/services/immersion-tracker/live-action-link.ts` (links an entry to a TMDB title and merges other holders of the same title). The AniList cover-art fetcher calls the resolver as its fallback; `imm_anime.media_kind` marks the result and keeps the entry out of AniList season repair.
 - Jellyfin integration: `src/core/services/jellyfin*.ts`, `src/main/runtime/composers/jellyfin-*`
 - Window trackers: `src/window-trackers/`
 - Stats HTTP app: `src/core/services/stats-server.ts`, with route groups and shared route support
@@ -37,6 +41,25 @@ Read when: you need to find the owner module for a behavior or test surface
 
 ## Shared Contract Entry Points
 
+Automatic mpv keyboard discovery uses the `get-mpv-input-bindings` IPC request and
+`MpvInputBindingsSnapshot` in `src/types/session-bindings.ts`.
+`src/main/runtime/mpv-input-bindings.ts` queries the connected player and preserves
+configured keys, including disabled entries. `src/shared/mpv-input-bindings.ts`
+validates discovered keys and translates browser input. The renderer's
+`handlers/mpv-input-forwarding.ts` keeps the session lookup, coalesces asynchronous
+refreshes, and releases held keys on blur or disposal. `handlers/keyboard.ts` runs
+this fallback after SubMiner controls and refreshes on startup, a delayed startup
+pass, focus, and binding reload. Discovery does not enter compiled session bindings,
+the plugin artifact, persistent config, or session help.
+
+The subtitle sidebar consumes parsed cues through `SubtitleSidebarSnapshot`. Its `sourceKey`
+identifies the media and subtitle source so renderer selections are invalidated on source changes,
+including changes whose cue text and timings are identical. Native selection and clean clipboard
+serialization live in `src/renderer/modals/subtitle-sidebar-selection.ts`. Electron lets standard
+Copy input reach the renderer, where sidebar selection takes priority over the live-subtitle binding.
+The preload bridge writes selections through Electron's clipboard API so copying does not depend
+on Chromium document focus or require activating the overlay window.
+
 - Config + app-state contracts: `src/types/config.ts`
 - Subtitle/token/media annotation contracts: `src/types/subtitle.ts`
 - Runtime/window/controller/Electron bridge contracts: `src/types/runtime.ts`
diff --git a/docs/architecture/layering.md b/docs/architecture/layering.md
index ef7e1440..794f3c3e 100644
--- a/docs/architecture/layering.md
+++ b/docs/architecture/layering.md
@@ -23,7 +23,7 @@ Renderer, launcher, plugin, and stats each keep their own local layering and sho
 - Keep side effects explicit and close to composition boundaries.
 - Put reusable business logic in focused services, not in top-level lifecycle files.
 - Keep renderer concerns in `src/renderer/`; avoid leaking DOM behavior into main-process code.
-- Treat `launcher/*.ts` as source of truth for the launcher. Never hand-edit `dist/launcher/subminer`.
+- Treat `launcher/*.ts` and the runtime bootstrap generators as source of truth for launcher behavior. `scripts/build-launcher.ts` creates `dist/launcher`; never hand-edit those artifacts.
 
 ## Smells
 
diff --git a/docs/architecture/subtitle-overlay-priming.md b/docs/architecture/subtitle-overlay-priming.md
index 460ea8f4..4c1a0bdc 100644
--- a/docs/architecture/subtitle-overlay-priming.md
+++ b/docs/architecture/subtitle-overlay-priming.md
@@ -3,7 +3,7 @@
 # Subtitle Overlay Priming
 
 Status: active
-Last verified: 2026-08-18
+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
 
@@ -71,11 +71,24 @@ coming and prefetching would otherwise idle for the rest of the cue.
 
 - 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, and
-  shadow events. Any unmatched live line keeps the complete live stack, preserving
-  dialogue or signs that overlap a lyric.
+  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.
@@ -84,17 +97,63 @@ coming and prefetching would otherwise idle for the rest of the cue.
 
 ## Secondary Subtitle Flow
 
-- `secondary-sub-text` remains the immediate fallback, so unreadable and remote subtitle sources
-  still appear without waiting for file resolution.
+- `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. The
+  timing tracker (clipboard copy, recent-line mining) and immersion recorders run the same
+  reconciliation on the `sub-start`/`sub-end` sample, so they record what the overlay shows.
+- Broadcast-caption rows that spell one utterance across several same-timed positioned events
+  (same style, layer, and vertical band, stacked at most two text rows apart) are joined into
+  one cue with a single line break, so `preserveLineBreaks` treats them like an authored `\N`,
+  and the recorders above see the whole sentence. A row continues the one above it when that row
+  is a bare speaker label, ends without terminal punctuation, or leaves a ≪…≫ / ⸨…⸩ span open; a
+  lower row that opens its own label or span always starts a new cue, which keeps two speakers
+  sharing the screen on separate lines. The pass runs only on scripts that read as broadcast
+  captions (a meaningful share of events carry speaker labels or ≪…≫ / ⸨…⸩ spans) and only on
+  rows containing Japanese, because fansub typesetting stacks positioned rows for signs, chat
+  bubbles, and headlines where that punctuation convention does not hold.
+- 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,
diff --git a/docs/knowledge-base/catalog.md b/docs/knowledge-base/catalog.md
index 352865b6..d0120cad 100644
--- a/docs/knowledge-base/catalog.md
+++ b/docs/knowledge-base/catalog.md
@@ -19,7 +19,7 @@ Read when: finding internal docs or checking verification status
 | 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-13 | repo-local workflow skill ownership |
+| 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 |
 
diff --git a/docs/workflow/agent-skills.md b/docs/workflow/agent-skills.md
index 5d87ec2e..aed51d81 100644
--- a/docs/workflow/agent-skills.md
+++ b/docs/workflow/agent-skills.md
@@ -3,7 +3,7 @@
 # Agent Skills
 
 Status: active
-Last verified: 2026-08-13
+Last verified: 2026-08-23
 Owner: Kyle Yasuda
 Read when: using, adding, or changing a repo-local agent workflow skill
 
@@ -12,6 +12,9 @@ Read when: using, adding, or changing a repo-local agent workflow skill
 - `.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.
 
diff --git a/docs/workflow/verification.md b/docs/workflow/verification.md
index 51d1b212..ed780f20 100644
--- a/docs/workflow/verification.md
+++ b/docs/workflow/verification.md
@@ -22,7 +22,15 @@ Read when: selecting the right verification lane for a change
   pull requests, stable tags, and prerelease tags. Keep common quality steps
   there instead of copying them into caller workflows.
 - The reusable gate installs Lua and runs `bun run test:env`, so the shipped mpv
-  plugin tests run for every pull request and tagged release.
+  plugin tests and launcher smoke run for every pull request and tagged release.
+  Lua installation uses only the runner's Ubuntu package sources so unrelated
+  third-party repository failures do not block the gate.
+- In the reusable gate, `test:coverage:src` is also the blocking execution of the
+  discovered `src/**` test lane. The coverage runner returns the failing test's
+  status, so CI does not rerun that lane through `test:fast`. Launcher unit and
+  script tests still run separately because they are outside the coverage lane.
+- Launcher smoke artifacts are uploaded after `test:env` fails. CI does not rerun
+  launcher smoke solely to collect the same artifacts.
 
 ## Default Handoff Gate
 
@@ -47,19 +55,43 @@ 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`
+- Runtime-compat / compiled behavior after `bun run build`: `bun run test:runtime:compat`
 - Stats dashboard UI: `bun run test:stats`
 - Build/release scripts (`scripts/**`): `bun run test:scripts`
+- Packaging: build the platform package, then run `bun run test:package <resources-directory>`.
+  On headless Linux: `xvfb-run -a bun run test:package release/linux-unpacked/resources`.
+  Content checks run inside the electron-builder afterPack hook. See the
+  [release guide](../RELEASING.md#package-contents-checks) for the
+  installed-app verification checklist.
 - Coverage for the maintained source lane: `bun run test:coverage:src`
 - Deep/local full gate: default handoff gate above
 
 ## Coverage Reporting
 
-- `bun run test:coverage:src` runs the maintained `test:src` lane through a sharded coverage runner: one Bun coverage process per test file, then merged LCOV output.
+- `bun run test:coverage:src` runs the same discovered `bun-src-full` membership as
+  `test:src` through a sharded coverage runner: one Bun coverage process per test
+  file, then merged LCOV output.
+- A failing coverage shard stops the runner with a nonzero status. Coverage is a
+  source test gate, not a report-only step.
 - Machine-readable output lands at `coverage/test-src/lcov.info`.
 - Every reusable quality-gate run uploads that LCOV file as the
   `coverage-test-src` artifact.
 
+## Compiled Runtime Smoke
+
+- `bun run test:smoke:dist` and its `test:runtime:compat` alias require an existing
+  full build and fail with the missing artifact paths when `dist/` or the stats UI
+  bundle is absent.
+- The check runs the emitted stats daemon under Electron's Node runtime. It opens
+  the production HTTP server, queries the overview endpoint through native
+  libsql-backed storage, and leaves an HTTP request body unfinished before
+  shutting the daemon down. It verifies a clean exit and that the port and
+  ownership state are released despite the unfinished request.
+- The check also occupies the configured port, requires startup to fail without
+  stale ownership state, releases the conflict, and verifies a clean retry.
+- This is not a full Electron UI startup check. It does not require a display and
+  makes no claims about renderer, window, tray, or mpv behavior.
+
 ## Dependency Audit Policy
 
 - `bun audit --audit-level high` blocks the reusable quality gate.
diff --git a/launcher/commands/generate-subtitles-command.test.ts b/launcher/commands/generate-subtitles-command.test.ts
new file mode 100644
index 00000000..1a685534
--- /dev/null
+++ b/launcher/commands/generate-subtitles-command.test.ts
@@ -0,0 +1,413 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import path from 'node:path';
+import { parseArgs } from '../config.js';
+import {
+  createGenerationProgressReporter,
+  runGenerateSubtitlesCommand,
+} from './generate-subtitles-command.js';
+
+type Deps = NonNullable<Parameters<typeof runGenerateSubtitlesCommand>[1]>;
+
+function fixture(argv: string[] = ['generate-subs', '/media/episode.mkv']) {
+  const output: string[] = [];
+  const commands: unknown[][] = [];
+  const generations: Parameters<NonNullable<Deps['generate']>>[0][] = [];
+  let exitCode: number | undefined;
+  let interrupted: (() => void) | undefined;
+  let detached = false;
+  const context = {
+    args: parseArgs(argv, 'subminer', {}),
+    mpvSocketPath: '/tmp/test-subminer-socket',
+    processAdapter: {
+      writeStdout: (text: string) => {
+        output.push(text);
+      },
+      setExitCode: (code: number) => {
+        exitCode = code;
+      },
+    },
+  };
+  const deps: Deps = {
+    readConfig: () => ({ subtitleGeneration: { modelPath: '/models/external.bin' } }),
+    configPath: () => '/settings/SubMiner/config.jsonc',
+    resolveModel: async () => ({ kind: 'external', path: '/models/external.bin' }),
+    resolveTools: async () => ({
+      ffmpeg: { kind: 'found', path: '/usr/bin/ffmpeg' },
+      ffprobe: { kind: 'found', path: '/usr/bin/ffprobe' },
+      whisper: { kind: 'found', path: '/usr/bin/whisper-cli' },
+      vad: null,
+    }),
+    downloadModel: async () => {
+      throw new Error('Unexpected model download');
+    },
+    generate: async (input) => {
+      generations.push(input);
+      input.onProgress?.({
+        stage: 'transcribe',
+        percent: 50,
+        message: 'Transcribing Japanese audio',
+      });
+      return '/media/episode.ja.srt';
+    },
+    mpvCommand: async (_socket, command) => {
+      commands.push(command);
+      if (command[1] === 'path') return '/media/episode.mkv';
+      if (command[1] === 'track-list') return [{ type: 'audio', selected: true, 'ff-index': 2 }];
+      return undefined;
+    },
+    onInterrupt: (handler) => {
+      interrupted = handler;
+      return () => {
+        detached = true;
+      };
+    },
+  };
+  return {
+    context,
+    deps,
+    output,
+    commands,
+    generations,
+    exitCode: () => exitCode,
+    interrupt: () => interrupted?.(),
+    detached: () => detached,
+  };
+}
+
+test('launcher uses the shared core and selected mpv audio then loads the generated file', async () => {
+  const f = fixture(['generate-subs']);
+  assert.equal(await runGenerateSubtitlesCommand(f.context, f.deps), true);
+  assert.equal(f.generations[0]?.mediaPath, '/media/episode.mkv');
+  assert.equal(f.generations[0]?.audioStreamIndex, 2);
+  assert.equal(
+    f.generations[0]?.modelDirectory,
+    path.join('/settings/SubMiner', 'models', 'whisper'),
+  );
+  assert.equal(f.generations[0]?.config.modelPath, '/models/external.bin');
+  assert.deepEqual(f.commands.at(-2), [
+    'sub-add',
+    '/media/episode.ja.srt',
+    'select',
+    'Japanese (generated)',
+    'ja',
+  ]);
+  assert.deepEqual(f.commands.at(-1), ['set_property', 'sub-delay', 0]);
+  assert.match(f.output.join(''), /50%/);
+  assert.match(f.output.join(''), /Saved Japanese subtitles/);
+  assert.equal(f.detached(), true);
+});
+
+test('launcher reports a missing executable before downloading a model', async () => {
+  const f = fixture(['generate-subs', '/media/episode.mkv', '--download-model']);
+  f.deps.resolveModel = async () => ({ kind: 'missing', path: '/models/missing.bin' });
+  f.deps.resolveTools = async () => ({
+    ffmpeg: { kind: 'found', path: '/usr/bin/ffmpeg' },
+    ffprobe: { kind: 'found', path: '/usr/bin/ffprobe' },
+    whisper: { kind: 'missing', message: 'whisper-cli was not found on PATH.' },
+    vad: null,
+  });
+  await assert.rejects(
+    runGenerateSubtitlesCommand(f.context, f.deps),
+    /whisper-cli was not found on PATH/,
+  );
+  assert.equal(f.generations.length, 0);
+});
+
+test('launcher never downloads a model without the explicit option', async () => {
+  const f = fixture();
+  f.deps.resolveModel = async () => ({ kind: 'missing', path: '/models/missing.bin' });
+  await assert.rejects(runGenerateSubtitlesCommand(f.context, f.deps), /--download-model/);
+  assert.equal(f.generations.length, 0);
+  assert.equal(f.detached(), true);
+});
+
+test('current mpv generation requires an identifiable selected audio track', async () => {
+  for (const tracks of [
+    [],
+    [{ type: 'audio', selected: true }],
+    [{ type: 'audio', selected: true, external: true, 'ff-index': 0 }],
+  ]) {
+    const f = fixture(['generate-subs']);
+    f.deps.mpvCommand = async (_socket, command) =>
+      command[1] === 'path' ? '/media/episode.mkv' : tracks;
+    await assert.rejects(runGenerateSubtitlesCommand(f.context, f.deps), /audio track/);
+    assert.equal(f.generations.length, 0);
+  }
+});
+
+test('explicit playing file leaves audio selection to the generator but inspects subtitle references', async () => {
+  const f = fixture();
+  await runGenerateSubtitlesCommand(f.context, f.deps);
+  assert.equal(f.generations[0]?.audioStreamIndex, undefined);
+  assert.equal(
+    f.commands.some((command) => command[1] === 'track-list'),
+    true,
+  );
+});
+
+test('launcher does not load generated subtitles after mpv switches files', async () => {
+  const f = fixture(['generate-subs']);
+  let changed = false;
+  f.deps.mpvCommand = async (_socket, command) => {
+    f.commands.push(command);
+    if (command[1] === 'path') return changed ? '/media/next.mkv' : '/media/episode.mkv';
+    return [{ type: 'audio', selected: true, 'ff-index': 2 }];
+  };
+  f.deps.generate = async () => {
+    changed = true;
+    return '/media/episode.ja.srt';
+  };
+  await runGenerateSubtitlesCommand(f.context, f.deps);
+  assert.equal(
+    f.commands.some((command) => command[0] === 'sub-add'),
+    false,
+  );
+  assert.match(f.output.join(''), /Saved Japanese subtitles/);
+});
+
+test('current mpv generation rejects tracks when playback changes during capture', async () => {
+  for (const nextMedia of ['/media/next.mkv', null]) {
+    const f = fixture(['generate-subs']);
+    let media: string | null = '/media/episode.mkv';
+    let modelChecks = 0;
+    f.deps.mpvCommand = async (_socket, command) => {
+      if (command[1] === 'path') return media;
+      if (command[1] === 'track-list') {
+        media = nextMedia;
+        return [{ type: 'audio', selected: true, 'ff-index': 99 }];
+      }
+      return undefined;
+    };
+    f.deps.resolveModel = async () => {
+      modelChecks += 1;
+      return { kind: 'external', path: '/models/model.bin' };
+    };
+    await assert.rejects(
+      runGenerateSubtitlesCommand(f.context, f.deps),
+      /mpv media.*Run generate-subs again/,
+    );
+    assert.equal(f.generations.length, 0);
+    assert.equal(modelChecks, 0);
+  }
+});
+
+test('explicit media or audio stream remains usable when the mpv snapshot changes', async () => {
+  for (const options of [['/media/episode.mkv'], ['--audio-stream', '7']]) {
+    const f = fixture(['generate-subs', ...options]);
+    let media = '/media/episode.mkv';
+    f.deps.mpvCommand = async (_socket, command) => {
+      if (command[1] === 'path') return media;
+      if (command[1] === 'track-list') {
+        media = '/media/next.mkv';
+        return [
+          { type: 'audio', selected: true, 'ff-index': 99 },
+          { type: 'sub', lang: 'eng', 'ff-index': 100 },
+        ];
+      }
+      return undefined;
+    };
+    await runGenerateSubtitlesCommand(f.context, f.deps);
+    assert.equal(f.generations[0]?.mediaPath, '/media/episode.mkv');
+    assert.equal(
+      f.generations[0]?.audioStreamIndex,
+      options[0] === '--audio-stream' ? 7 : undefined,
+    );
+    assert.deepEqual(f.generations[0]?.references, []);
+  }
+});
+
+test('launcher captures loaded external references only for the matching media', async () => {
+  for (const matching of [true, false]) {
+    const f = fixture();
+    f.deps.mpvCommand = async (_socket, command) => {
+      if (command[1] === 'path') return matching ? '/media/episode.mkv' : '/media/other.mkv';
+      if (command[1] === 'working-directory') return '/mpv';
+      if (command[1] === 'track-list')
+        return [
+          { type: 'sub', external: true, 'external-filename': 'episode.en.signs.ass' },
+          { type: 'sub', external: true, 'external-filename': 'episode.en.srt' },
+        ];
+      return undefined;
+    };
+    await runGenerateSubtitlesCommand(f.context, f.deps);
+    assert.deepEqual(
+      f.generations[0]?.references,
+      matching
+        ? [
+            {
+              label: 'episode.en.srt',
+              delaySeconds: 0,
+              source: { kind: 'external', path: '/mpv/episode.en.srt' },
+            },
+          ]
+        : [],
+    );
+  }
+});
+
+test('explicit managed model overrides external config and downloads before generation', async () => {
+  const f = fixture([
+    'generate-subs',
+    '/media/episode.mkv',
+    '--model',
+    'medium',
+    '--download-model',
+  ]);
+  f.deps.resolveModel = async (config) => {
+    assert.equal(config.modelPath, '');
+    assert.equal(config.managedModel, 'medium');
+    return { kind: 'missing', path: '/models/medium.bin' };
+  };
+  let downloaded = false;
+  f.deps.downloadModel = async () => {
+    downloaded = true;
+    return '/models/medium.bin';
+  };
+  const generate = f.deps.generate;
+  f.deps.generate = async (input) => {
+    assert.equal(downloaded, true);
+    if (!generate) throw new Error('Missing fixture generator');
+    return generate(input);
+  };
+  await runGenerateSubtitlesCommand(f.context, f.deps);
+  assert.equal(f.generations.length, 1);
+});
+
+test('audio and subtitle timing use the initial mpv snapshot across model setup', async () => {
+  for (const changeDuring of ['resolve', 'download']) {
+    const f = fixture(['generate-subs', '--download-model']);
+    let changed = false;
+    let trackReads = 0;
+    f.deps.mpvCommand = async (_socket, command) => {
+      if (command[1] === 'path') return '/media/episode.mkv';
+      if (command[1] === 'track-list') {
+        trackReads += 1;
+        return [
+          { type: 'audio', selected: true, 'ff-index': changed ? 3 : 2 },
+          { type: 'sub', id: 1, title: 'English Full', lang: 'eng', 'ff-index': changed ? 5 : 4 },
+        ];
+      }
+      if (command[1] === 'sid') return 1;
+      if (command[1] === 'sub-delay') return changed ? 9 : 1.5;
+      return undefined;
+    };
+    f.deps.resolveModel = async () => {
+      if (changeDuring === 'resolve') changed = true;
+      return { kind: 'missing', path: '/models/model.bin' };
+    };
+    f.deps.downloadModel = async () => {
+      changed = true;
+      return '/models/model.bin';
+    };
+    await runGenerateSubtitlesCommand(f.context, f.deps);
+    assert.equal(f.generations[0]?.audioStreamIndex, 2);
+    assert.deepEqual(f.generations[0]?.references, [
+      {
+        label: 'English Full',
+        delaySeconds: 1.5,
+        source: { kind: 'embedded', streamIndex: 4 },
+      },
+    ]);
+    assert.equal(trackReads, 1);
+  }
+});
+
+test('explicit audio stream bypasses mpv audio selection while retaining subtitle references', async () => {
+  const f = fixture(['generate-subs', '--audio-stream', '7']);
+  f.deps.mpvCommand = async (_socket, command) => {
+    if (command[1] === 'path') return '/media/episode.mkv';
+    if (command[1] === 'track-list')
+      return [
+        { type: 'audio', selected: true, external: true, 'ff-index': 0 },
+        { type: 'sub', id: 2, title: 'English Full', lang: 'eng', 'ff-index': 4 },
+      ];
+    if (command[1] === 'secondary-sid') return 2;
+    if (command[1] === 'secondary-sub-delay') return -0.5;
+    return undefined;
+  };
+  await runGenerateSubtitlesCommand(f.context, f.deps);
+  assert.equal(f.generations[0]?.audioStreamIndex, 7);
+  assert.deepEqual(f.generations[0]?.references, [
+    {
+      label: 'English Full',
+      delaySeconds: -0.5,
+      source: { kind: 'embedded', streamIndex: 4 },
+    },
+  ]);
+});
+
+test('generation can run standalone and never loads subtitles into another video', async () => {
+  for (const playing of [null, '/media/different.mkv']) {
+    const f = fixture();
+    f.deps.mpvCommand = async (_socket, command) => {
+      f.commands.push(command);
+      if (playing === null) throw new Error('mpv is not running');
+      return playing;
+    };
+    await runGenerateSubtitlesCommand(f.context, f.deps);
+    assert.equal(f.generations.length, 1);
+    assert.equal(
+      f.commands.some((command) => command[0] === 'sub-add'),
+      false,
+    );
+  }
+});
+
+test('launcher preserves the saved path when loading into mpv fails', async () => {
+  const f = fixture();
+  const mpv = f.deps.mpvCommand;
+  f.deps.mpvCommand = async (socket, command, timeout) => {
+    if (command[0] === 'sub-add') throw new Error('load failed');
+    return mpv?.(socket, command, timeout);
+  };
+  await runGenerateSubtitlesCommand(f.context, f.deps);
+  assert.match(f.output.join(''), /Saved Japanese subtitles: \/media\/episode.ja.srt/);
+  assert.match(f.output.join(''), /mpv could not load them: load failed/);
+  assert.equal(f.exitCode(), 1);
+});
+
+test('SIGINT cancels shared generation and unregisters its handler', async () => {
+  const f = fixture();
+  f.deps.generate = async (input) => {
+    f.interrupt();
+    assert.equal(input.signal?.aborted, true);
+    throw new Error('Aborted');
+  };
+  await runGenerateSubtitlesCommand(f.context, f.deps);
+  assert.equal(f.exitCode(), 130);
+  assert.equal(f.detached(), true);
+  assert.match(f.output.join(''), /cancelled/);
+});
+
+test('cancellation after generation preserves the saved path and skips mpv loading', async () => {
+  const f = fixture();
+  f.deps.generate = async () => {
+    f.interrupt();
+    return '/media/episode.ja.srt';
+  };
+  await runGenerateSubtitlesCommand(f.context, f.deps);
+  assert.equal(
+    f.commands.some((command) => command[0] === 'sub-add'),
+    false,
+  );
+  assert.match(f.output.join(''), /Saved Japanese subtitles: \/media\/episode.ja.srt/);
+  assert.equal(f.exitCode(), 130);
+  assert.equal(f.detached(), true);
+});
+
+test('progress throttles repeated updates but always reports stage changes and completion', () => {
+  const output: string[] = [];
+  let time = 0;
+  const progress = createGenerationProgressReporter(
+    (text) => output.push(text),
+    () => time,
+  );
+  progress({ stage: 'download', percent: 0, message: 'Downloading' });
+  progress({ stage: 'download', percent: 1, message: 'Downloading' });
+  time = 1000;
+  progress({ stage: 'download', percent: 50, message: 'Downloading' });
+  progress({ stage: 'download', percent: 100, message: 'Downloading' });
+  progress({ stage: 'extract', message: 'Extracting audio' });
+  assert.equal(output.length, 4);
+});
diff --git a/launcher/commands/generate-subtitles-command.ts b/launcher/commands/generate-subtitles-command.ts
new file mode 100644
index 00000000..335d2e40
--- /dev/null
+++ b/launcher/commands/generate-subtitles-command.ts
@@ -0,0 +1,245 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  downloadSubtitleGenerationModel,
+  generateJapaneseSubtitles,
+  resolveSubtitleGenerationModel,
+  resolveSubtitleGenerationTools,
+} from '../../src/core/services/subtitle-generation.js';
+import { requireSubtitleGenerationTools } from '../../src/core/services/subtitle-generation-tools.js';
+import {
+  readSubtitleGenerationReferences,
+  type SubtitleGenerationReference,
+} from '../../src/core/services/subtitle-generation-reference.js';
+import {
+  resolveSubtitleGenerationConfig,
+  type SubtitleGenerationProgress,
+} from '../../src/shared/subtitle-generation.js';
+import {
+  readLauncherMainConfigObject,
+  resolveLauncherMainConfigPath,
+} from '../config/shared-config-reader.js';
+import { sendMpvCommandWithResponse } from '../mpv.js';
+import { resolvePathMaybe } from '../util.js';
+import type { LauncherCommandContext } from './context.js';
+
+type GenerationCommandContext = Pick<LauncherCommandContext, 'args' | 'mpvSocketPath'> & {
+  processAdapter: Pick<LauncherCommandContext['processAdapter'], 'writeStdout' | 'setExitCode'>;
+};
+
+interface GenerationCommandDeps {
+  readConfig: typeof readLauncherMainConfigObject;
+  configPath: typeof resolveLauncherMainConfigPath;
+  resolveModel: typeof resolveSubtitleGenerationModel;
+  resolveTools: typeof resolveSubtitleGenerationTools;
+  downloadModel: typeof downloadSubtitleGenerationModel;
+  generate: typeof generateJapaneseSubtitles;
+  mpvCommand: typeof sendMpvCommandWithResponse;
+  onInterrupt: (handler: () => void) => () => void;
+}
+
+const defaultDeps: GenerationCommandDeps = {
+  readConfig: readLauncherMainConfigObject,
+  configPath: resolveLauncherMainConfigPath,
+  resolveModel: resolveSubtitleGenerationModel,
+  resolveTools: resolveSubtitleGenerationTools,
+  downloadModel: downloadSubtitleGenerationModel,
+  generate: generateJapaneseSubtitles,
+  mpvCommand: sendMpvCommandWithResponse,
+  onInterrupt: (handler) => {
+    process.on('SIGINT', handler);
+    return () => process.off('SIGINT', handler);
+  },
+};
+
+function localMediaPath(value: string, workingDirectory = process.cwd()): string {
+  if (value.startsWith('file://')) return fileURLToPath(value);
+  if (/^[a-z][a-z\d+.-]*:\/\//i.test(value)) {
+    throw new Error('Japanese subtitle generation requires a local media file.');
+  }
+  return path.resolve(workingDirectory, resolvePathMaybe(value));
+}
+
+async function readMpvMedia(socketPath: string, command: GenerationCommandDeps['mpvCommand']) {
+  const media = await command(socketPath, ['get_property', 'path'], 1000);
+  if (typeof media !== 'string' || !media.trim()) return null;
+  let workingDirectory: string | undefined;
+  if (!path.isAbsolute(media) && !media.startsWith('file://')) {
+    const directory = await command(socketPath, ['get_property', 'working-directory'], 1000);
+    if (typeof directory !== 'string') return null;
+    workingDirectory = directory;
+  }
+  return localMediaPath(media, workingDirectory);
+}
+
+function selectedMpvAudioStream(value: unknown) {
+  const tracks: unknown[] = Array.isArray(value) ? value : [];
+  for (const track of tracks) {
+    if (
+      typeof track === 'object' &&
+      track !== null &&
+      'type' in track &&
+      track.type === 'audio' &&
+      'selected' in track &&
+      track.selected === true
+    ) {
+      if ('external' in track && track.external === true) {
+        throw new Error(
+          'The selected mpv audio track is external. Pass its local file to generate-subs.',
+        );
+      }
+      if (
+        'ff-index' in track &&
+        typeof track['ff-index'] === 'number' &&
+        Number.isSafeInteger(track['ff-index']) &&
+        track['ff-index'] >= 0
+      ) {
+        return track['ff-index'];
+      }
+    }
+  }
+  throw new Error(
+    'Select an audio track in mpv, or pass --audio-stream with its absolute stream index.',
+  );
+}
+
+function sameFile(left: string, right: string): boolean {
+  try {
+    return fs.realpathSync(left) === fs.realpathSync(right);
+  } catch {
+    return path.resolve(left) === path.resolve(right);
+  }
+}
+
+/** Keep progress readable in terminals and redirected logs, even for large model downloads. */
+export function createGenerationProgressReporter(write: (text: string) => void, now = Date.now) {
+  let previousStage: SubtitleGenerationProgress['stage'] | undefined;
+  let previousTime = -Infinity;
+  let previousLine = '';
+  return (progress: SubtitleGenerationProgress): void => {
+    const percent =
+      typeof progress.percent === 'number' && Number.isFinite(progress.percent)
+        ? Math.floor(Math.max(0, Math.min(100, progress.percent)))
+        : undefined;
+    const line = `[${progress.stage}] ${percent === undefined ? '' : `${percent}% `}${progress.message}\n`;
+    const timestamp = now();
+    if (
+      line === previousLine ||
+      (progress.stage === previousStage && timestamp - previousTime < 1000 && percent !== 100)
+    )
+      return;
+    write(line);
+    previousStage = progress.stage;
+    previousTime = timestamp;
+    previousLine = line;
+  };
+}
+
+export async function runGenerateSubtitlesCommand(
+  context: GenerationCommandContext,
+  overrides: Partial<GenerationCommandDeps> = {},
+): Promise<boolean> {
+  const options = context.args.generateSubtitles;
+  if (!options) return false;
+  const deps = { ...defaultDeps, ...overrides };
+  const write = (text: string) => context.processAdapter.writeStdout(text);
+  const controller = new AbortController();
+  const removeInterrupt = deps.onInterrupt(() => controller.abort());
+  try {
+    const config = resolveSubtitleGenerationConfig(deps.readConfig()?.subtitleGeneration);
+    if (options.managedModel) {
+      config.managedModel = options.managedModel;
+      config.modelPath = '';
+    }
+    if (options.modelPath !== undefined)
+      config.modelPath = path.resolve(resolvePathMaybe(options.modelPath));
+    const modelDirectory = path.join(path.dirname(deps.configPath()), 'models', 'whisper');
+    const currentMedia = await readMpvMedia(context.mpvSocketPath, deps.mpvCommand).catch(
+      () => null,
+    );
+    const mediaPath = options.mediaPath ? localMediaPath(options.mediaPath) : currentMedia;
+    if (!mediaPath)
+      throw new Error('Pass a local video file or open one in mpv before running generate-subs.');
+    // Capture audio and subtitle timing together before model setup can yield to playback changes.
+    const matchesCurrentMedia = currentMedia !== null && sameFile(currentMedia, mediaPath);
+    const tracks = matchesCurrentMedia
+      ? await deps
+          .mpvCommand(context.mpvSocketPath, ['get_property', 'track-list'], 1000)
+          .catch(() => null)
+      : null;
+    let references: SubtitleGenerationReference[] = [];
+    if (matchesCurrentMedia) {
+      const candidates = await readSubtitleGenerationReferences(tracks, (name) =>
+        deps.mpvCommand(context.mpvSocketPath, ['get_property', name], 1000),
+      );
+      const stillPlaying = await readMpvMedia(context.mpvSocketPath, deps.mpvCommand).catch(
+        () => null,
+      );
+      if (stillPlaying && sameFile(stillPlaying, mediaPath)) references = candidates;
+      else if (!options.mediaPath && options.audioStreamIndex === undefined)
+        throw new Error(
+          'The current mpv media changed or could not be verified while reading tracks. Run generate-subs again.',
+        );
+    }
+    const audioStreamIndex =
+      options.audioStreamIndex ?? (!options.mediaPath ? selectedMpvAudioStream(tracks) : undefined);
+    const onProgress = createGenerationProgressReporter(write);
+    // Missing executables fail here, before any model download starts.
+    requireSubtitleGenerationTools(await deps.resolveTools(config));
+    const model = await deps.resolveModel(config, modelDirectory);
+    if (model.kind === 'invalid') throw new Error(model.message);
+    if (model.kind === 'missing') {
+      if (!options.downloadModel) {
+        throw new Error(
+          'No Whisper model found. Run again with --download-model, or set subtitleGeneration.modelPath / --model-path.',
+        );
+      }
+      await deps.downloadModel({ config, modelDirectory, onProgress, signal: controller.signal });
+    }
+    const outputPath = await deps.generate({
+      config,
+      modelDirectory,
+      mediaPath,
+      audioStreamIndex,
+      references,
+      outputPath: options.outputPath
+        ? path.resolve(resolvePathMaybe(options.outputPath))
+        : undefined,
+      onProgress,
+      signal: controller.signal,
+    });
+    write(`Saved Japanese subtitles: ${outputPath}\n`);
+    controller.signal.throwIfAborted();
+    const playingMedia = await readMpvMedia(context.mpvSocketPath, deps.mpvCommand).catch(
+      () => null,
+    );
+    controller.signal.throwIfAborted();
+    if (playingMedia && sameFile(playingMedia, mediaPath)) {
+      try {
+        await deps.mpvCommand(context.mpvSocketPath, [
+          'sub-add',
+          outputPath,
+          'select',
+          'Japanese (generated)',
+          'ja',
+        ]);
+        await deps.mpvCommand(context.mpvSocketPath, ['set_property', 'sub-delay', 0]);
+        write('Loaded Japanese subtitles into mpv.\n');
+      } catch (error) {
+        write(
+          `Subtitles are saved, but mpv could not load them: ${error instanceof Error ? error.message : String(error)}\n`,
+        );
+        context.processAdapter.setExitCode(1);
+      }
+    }
+    return true;
+  } catch (error) {
+    if (!controller.signal.aborted) throw error;
+    write('Subtitle generation cancelled.\n');
+    context.processAdapter.setExitCode(130);
+    return true;
+  } finally {
+    removeInterrupt();
+  }
+}
diff --git a/launcher/commands/history-command.ts b/launcher/commands/history-command.ts
index 352bbee5..37d10be8 100644
--- a/launcher/commands/history-command.ts
+++ b/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();
diff --git a/launcher/commands/jellyfin-command.ts b/launcher/commands/jellyfin-command.ts
index cc22b0f1..f4fe2b94 100644
--- a/launcher/commands/jellyfin-command.ts
+++ b/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;
   }
diff --git a/launcher/commands/playback-command.test.ts b/launcher/commands/playback-command.test.ts
index ffae2d8a..9ef761ca 100644
--- a/launcher/commands/playback-command.test.ts
+++ b/launcher/commands/playback-command.test.ts
@@ -496,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']);
+});
diff --git a/launcher/commands/playback-command.ts b/launcher/commands/playback-command.ts
index 56a55c3c..78ae0b49 100644
--- a/launcher/commands/playback-command.ts
+++ b/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,
diff --git a/launcher/commands/update-command.test.ts b/launcher/commands/update-command.test.ts
index 3766916e..8f358e69 100644
--- a/launcher/commands/update-command.test.ts
+++ b/launcher/commands/update-command.test.ts
@@ -1,5 +1,9 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
 import { runUpdateCommand } from './update-command';
 import type { LauncherCommandContext } from './context';
 
@@ -36,6 +40,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,10 +61,29 @@ 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.',
   ]);
 });
 
+test('runUpdateCommand sends symlinked AUR installs to the package helper without network access', async () => {
+  const calls: string[] = [];
+  const handled = await runUpdateCommand(makeContext({ appPath: '/usr/bin/SubMiner.AppImage' }), {
+    resolveRealPath: () => '/opt/SubMiner/SubMiner.AppImage',
+    runDirectReleaseUpdate: async () => {
+      throw new Error('must not check GitHub releases for an AUR install');
+    },
+    log: (level, _configured, message) => {
+      calls.push(`${level}:${message}`);
+    },
+  });
+
+  assert.equal(handled, true);
+  assert.deepEqual(calls, [
+    'warn:SubMiner is installed through subminer-bin. Update it with your AUR helper, for example: yay -S subminer-bin.',
+  ]);
+});
+
 test('runUpdateCommand skips Linux asset replacement when release is not newer', async () => {
   const calls: string[] = [];
   const originalFetch = globalThis.fetch;
@@ -112,6 +140,65 @@ test('runUpdateCommand skips Linux asset replacement when release is not newer',
   }
 });
 
+test('Linux update does not replace the launcher after an AppImage hash failure', async () => {
+  const workspace = fs.mkdtempSync(path.join(os.tmpdir(), 'subminer-update-order-'));
+  const appImagePath = path.join(workspace, 'SubMiner.AppImage');
+  const launcherPath = path.join(workspace, 'subminer');
+  fs.writeFileSync(appImagePath, 'old app');
+  fs.writeFileSync(launcherPath, '#!/bin/sh\n# SubMiner launcher\n');
+
+  const fetched: string[] = [];
+  const originalFetch = globalThis.fetch;
+  globalThis.fetch = (async (input: string | URL | Request) => {
+    const url = input instanceof Request ? input.url : String(input);
+    fetched.push(url);
+    if (url.endsWith('/releases')) {
+      return Response.json([
+        {
+          tag_name: 'v999.0.0',
+          prerelease: false,
+          draft: false,
+          assets: [
+            {
+              name: 'SHA256SUMS.txt',
+              browser_download_url: 'https://example.test/SHA256SUMS.txt',
+            },
+            {
+              name: 'SubMiner.AppImage',
+              browser_download_url: 'https://example.test/SubMiner.AppImage',
+            },
+            { name: 'subminer', browser_download_url: 'https://example.test/subminer' },
+          ],
+        },
+      ]);
+    }
+    if (url.endsWith('/SHA256SUMS.txt')) {
+      return new Response(
+        `${createHash('sha256').update('expected app').digest('hex')}  SubMiner.AppImage\n${createHash('sha256').update('new launcher').digest('hex')}  subminer\n`,
+      );
+    }
+    if (url.endsWith('/SubMiner.AppImage')) {
+      return new Response('corrupt app');
+    }
+    throw new Error(`launcher asset should not be fetched: ${url}`);
+  }) as typeof globalThis.fetch;
+
+  try {
+    const handled = await runUpdateCommand(
+      makeContext({ appPath: appImagePath, scriptPath: launcherPath }),
+      { readMainConfig: () => null, log: () => {} },
+    );
+
+    assert.equal(handled, true);
+    assert.equal(fs.readFileSync(appImagePath, 'utf8'), 'old app');
+    assert.equal(fs.readFileSync(launcherPath, 'utf8'), '#!/bin/sh\n# SubMiner launcher\n');
+    assert.equal(fetched.includes('https://example.test/subminer'), false);
+  } finally {
+    globalThis.fetch = originalFetch;
+    fs.rmSync(workspace, { recursive: true, force: true });
+  }
+});
+
 test('runUpdateCommand keeps app-mediated update path on non-Linux', async () => {
   const calls: string[] = [];
 
@@ -142,3 +229,32 @@ test('runUpdateCommand keeps app-mediated update path on non-Linux', async () =>
     'remove:/tmp/subminer-update-test',
   ]);
 });
+
+test('managed launcher passes its wrapper to app updates, protecting signed resources', async () => {
+  const previous = process.env.SUBMINER_LAUNCHER_PATH;
+  process.env.SUBMINER_LAUNCHER_PATH = '/Users/tester/.local/bin/subminer';
+  try {
+    let forwarded: string[] = [];
+    await runUpdateCommand(
+      makeContext({
+        processAdapter: { ...makeContext().processAdapter, platform: () => 'darwin' },
+        scriptPath: '/Applications/SubMiner.app/Contents/Resources/launcher/subminer',
+        appPath: '/Applications/SubMiner.app/Contents/MacOS/SubMiner',
+      }),
+      {
+        createTempDir: () => '/tmp/subminer-update-test',
+        joinPath: (...parts) => parts.join('/'),
+        runAppCommandCaptureOutput: (_app, args) => {
+          forwarded = args;
+          return { status: 0, stdout: '', stderr: '' };
+        },
+        waitForUpdateResponse: async () => ({ ok: true }),
+        removeDir: () => {},
+      },
+    );
+    assert.equal(forwarded[2], '/Users/tester/.local/bin/subminer');
+  } finally {
+    if (previous === undefined) delete process.env.SUBMINER_LAUNCHER_PATH;
+    else process.env.SUBMINER_LAUNCHER_PATH = previous;
+  }
+});
diff --git a/launcher/commands/update-command.ts b/launcher/commands/update-command.ts
index e1050513..5fbf6c46 100644
--- a/launcher/commands/update-command.ts
+++ b/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 = {
@@ -56,6 +58,7 @@ type UpdateCommandDeps = {
   ) => { status: number; stdout: string; stderr: string; error?: Error };
   waitForUpdateResponse: (responsePath: string) => Promise<UpdateCommandResponse>;
   removeDir: (targetPath: string) => void;
+  resolveRealPath: (targetPath: string) => string;
   runDirectReleaseUpdate: (
     request: DirectReleaseUpdateRequest,
   ) => Promise<DirectReleaseUpdateResult>;
@@ -96,25 +99,36 @@ async function runDirectReleaseUpdate(
       : new Map<string, string>();
   const downloadAsset = (url: string) => fetchReleaseAssetBuffer(fetchForUpdater, url);
 
-  const [appImage, launcher, supportAssets] = await Promise.all([
-    updateAppImageFromRelease({
-      release,
-      sha256Sums,
-      appImagePath: request.appPath,
-      downloadAsset,
-    }),
-    updateLauncherFromRelease({
+  const appImage = await updateAppImageFromRelease({
+    release,
+    sha256Sums,
+    appImagePath: request.appPath,
+    downloadAsset,
+  });
+  let launcher: DirectReleaseUpdateResult['launcher'];
+  if (appImage.status !== 'updated') {
+    launcher = {
+      status: 'skipped',
+      message: 'Launcher update requires a successful AppImage update first.',
+    };
+  } else if (process.env.SUBMINER_MANAGED_LAUNCHER === '1') {
+    launcher = {
+      status: 'skipped',
+      message: 'This launcher is updated with the SubMiner app.',
+    };
+  } else {
+    launcher = await updateLauncherFromRelease({
       release,
       sha256Sums,
       launcherPath: request.launcherPath,
       downloadAsset,
-    }),
-    updateSupportAssetsFromRelease({
-      release,
-      sha256Sums,
-      downloadAsset,
-    }),
-  ]);
+    });
+  }
+  const supportAssets = await updateSupportAssetsFromRelease({
+    release,
+    sha256Sums,
+    downloadAsset,
+  });
 
   return { appImage, launcher, supportAssets };
 }
@@ -129,12 +143,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 {
@@ -176,6 +185,13 @@ const defaultDeps: UpdateCommandDeps = {
   removeDir: (targetPath) => {
     fs.rmSync(targetPath, { recursive: true, force: true });
   },
+  resolveRealPath: (targetPath) => {
+    try {
+      return fs.realpathSync(targetPath);
+    } catch {
+      return targetPath;
+    }
+  },
   runDirectReleaseUpdate,
   readMainConfig: readLauncherMainConfigObject,
   log: launcherLog,
@@ -192,12 +208,20 @@ export async function runUpdateCommand(
   }
 
   if (context.processAdapter.platform() === 'linux') {
+    const logLevel = args.logLevel ?? 'warn';
+    if (resolvedDeps.resolveRealPath(appPath) === '/opt/SubMiner/SubMiner.AppImage') {
+      resolvedDeps.log(
+        'warn',
+        logLevel,
+        'SubMiner is installed through subminer-bin. Update it with your AUR helper, for example: yay -S subminer-bin.',
+      );
+      return true;
+    }
     const result = await resolvedDeps.runDirectReleaseUpdate({
       appPath,
       launcherPath: scriptPath,
       channel: readUpdateChannel(resolvedDeps.readMainConfig()),
     });
-    const logLevel = args.logLevel ?? 'warn';
     logUpdateResult('AppImage', result.appImage, logLevel, resolvedDeps);
     logUpdateResult('Launcher', result.launcher, logLevel, resolvedDeps);
     for (const supportResult of result.supportAssets) {
@@ -206,6 +230,7 @@ export async function runUpdateCommand(
     return true;
   }
 
+  const launcherPath = path.resolve(process.env.SUBMINER_LAUNCHER_PATH ?? scriptPath);
   const tempDir = resolvedDeps.createTempDir('subminer-update-');
   const responsePath = resolvedDeps.joinPath(tempDir, 'response.json');
 
@@ -213,7 +238,7 @@ export async function runUpdateCommand(
     const result = resolvedDeps.runAppCommandCaptureOutput(appPath, [
       '--update',
       '--update-launcher-path',
-      scriptPath,
+      launcherPath,
       '--update-response-path',
       responsePath,
     ]);
diff --git a/launcher/config/args-normalizer.ts b/launcher/config/args-normalizer.ts
index a1568cd5..3e3c3845 100644
--- a/launcher/config/args-normalizer.ts
+++ b/launcher/config/args-normalizer.ts
@@ -248,6 +248,7 @@ export function applyRootOptionsToArgs(
 }
 
 export function applyInvocationsToArgs(parsed: Args, invocations: CliInvocations): void {
+  if (invocations.generateSubtitles) parsed.generateSubtitles = invocations.generateSubtitles;
   if (invocations.dictionaryTriggered) parsed.dictionary = true;
   if (invocations.dictionaryCandidates) parsed.dictionaryCandidates = true;
   if (invocations.dictionarySelect) parsed.dictionarySelect = true;
diff --git a/launcher/config/cli-parser-builder.test.ts b/launcher/config/cli-parser-builder.test.ts
index 70ff8592..0360211e 100644
--- a/launcher/config/cli-parser-builder.test.ts
+++ b/launcher/config/cli-parser-builder.test.ts
@@ -1,6 +1,61 @@
 import assert from 'node:assert/strict';
 import test from 'node:test';
 import { parseCliPrograms, resolveTopLevelCommand } from './cli-parser-builder.js';
+import { SUBTITLE_GENERATION_MODELS } from '../../src/shared/subtitle-generation-model-catalog.js';
+
+test('generate-subs accepts all downloadable multilingual model variants', () => {
+  for (const { id } of SUBTITLE_GENERATION_MODELS) {
+    const { invocations } = parseCliPrograms(['generate-subs', '--model', id], 'subminer');
+    assert.equal(invocations.generateSubtitles?.managedModel, id);
+  }
+});
+
+test('generate-subs parses local generation options separately from YouTube options', () => {
+  const result = parseCliPrograms(
+    [
+      'generate-subs',
+      'episode.mkv',
+      '--download-model',
+      '--model',
+      'medium',
+      '--output',
+      'episode.ja.srt',
+      '--audio-stream',
+      '2',
+    ],
+    'subminer',
+  );
+  assert.deepEqual(result.invocations.generateSubtitles, {
+    mediaPath: 'episode.mkv',
+    downloadModel: true,
+    managedModel: 'medium',
+    modelPath: undefined,
+    outputPath: 'episode.ja.srt',
+    audioStreamIndex: 2,
+  });
+  assert.equal(
+    parseCliPrograms(['generate-subs'], 'subminer').invocations.generateSubtitles?.mediaPath,
+    undefined,
+  );
+  assert.equal(
+    parseCliPrograms(['generate-subs', '--model-path', '/models/ggml.bin'], 'subminer').invocations
+      .generateSubtitles?.modelPath,
+    '/models/ggml.bin',
+  );
+});
+
+test('generate-subs rejects conflicting models and malformed audio stream indices', () => {
+  for (const flags of [
+    ['--model', 'tiny.en'],
+    ['--model', 'small.en-q5_1'],
+    ['--model', 'toString'],
+    ['--audio-stream', '-1'],
+    ['--audio-stream', '1.5'],
+    ['--model-path', '/model.bin', '--download-model'],
+    ['--model-path', '/model.bin', '--model', 'small'],
+  ])
+    assert.throws(() => parseCliPrograms(['generate-subs', ...flags], 'subminer'), /Generation/);
+});
 
 test('resolveTopLevelCommand skips root options and finds the first command', () => {
   assert.deepEqual(resolveTopLevelCommand(['--backend', 'macos', 'config', 'show']), {
@@ -94,6 +149,23 @@ test('parseCliPrograms lowers sync options into app-owned CLI tokens', () => {
   assert.deepEqual(removeTemp.invocations.syncCliTokens, ['--remove-temp', '/tmp/subminer-sync-x']);
 });
 
+test('parseCliPrograms forwards transfer cache keys with both sync temp helpers', () => {
+  const key = 'a'.repeat(64);
+  for (const helper of [['--make-temp'], ['--remove-temp', '/tmp/subminer-sync-x']]) {
+    const tokens = [...helper, '--transfer-cache', key];
+    const result = parseCliPrograms(['sync', ...tokens], 'subminer');
+    assert.equal(result.invocations.syncTriggered, true);
+    assert.deepEqual(result.invocations.syncCliTokens, tokens);
+  }
+});
+
+test('parseCliPrograms rejects sync --ui with --transfer-cache', () => {
+  assert.throws(
+    () => parseCliPrograms(['sync', '--ui', '--transfer-cache', 'a'.repeat(64)], 'subminer'),
+    { message: 'Sync --ui cannot be combined with other sync options.' },
+  );
+});
+
 test('parseCliPrograms leaves sync validation to the app parser', () => {
   // Invalid combinations are forwarded; the app's parseSyncCliTokens rejects them.
   const invalid = parseCliPrograms(['sync', 'media-box', '--push', '--pull'], 'subminer');
diff --git a/launcher/config/cli-parser-builder.ts b/launcher/config/cli-parser-builder.ts
index e531123d..82eb46f4 100644
--- a/launcher/config/cli-parser-builder.ts
+++ b/launcher/config/cli-parser-builder.ts
@@ -1,4 +1,9 @@
 import { Command } from 'commander';
+import type { Args } from '../types.js';
+import {
+  isSubtitleGenerationModelId,
+  SUBTITLE_GENERATION_MODELS,
+} from '../../src/shared/subtitle-generation-model-catalog.js';
 
 export interface JellyfinInvocation {
   action?: string;
@@ -20,6 +25,7 @@ export interface CommandActionInvocation {
 }
 
 export interface CliInvocations {
+  generateSubtitles?: Args['generateSubtitles'];
   jellyfinInvocation: JellyfinInvocation | null;
   configInvocation: CommandActionInvocation | null;
   settingsInvocation: CommandActionInvocation | null;
@@ -118,6 +124,7 @@ function getTopLevelCommand(argv: string[]): { name: string; index: number } | n
     'mpv',
     'logs',
     'dictionary',
+    'generate-subs',
     'dict',
     'stats',
     'sync',
@@ -199,6 +206,7 @@ export function parseCliPrograms(
   let texthookerOpenBrowser = false;
   let doctorTriggered = false;
   let texthookerTriggered = false;
+  let generateSubtitles: Args['generateSubtitles'];
 
   const commandProgram = new Command();
   commandProgram
@@ -223,6 +231,50 @@ export function parseCliPrograms(
     .argument('[target]', 'file, directory, or URL');
   applyRootOptions(rootProgram);
 
+  commandProgram
+    .command('generate-subs')
+    .description('Generate Japanese subtitles locally with whisper.cpp')
+    .argument('[video]', 'Local media file, or the current mpv file if omitted')
+    .option('--download-model', 'Download the selected managed model if missing')
+    .option('--model-path <path>', 'Use an existing whisper.cpp model file')
+    .option(
+      '--model <name>',
+      `Managed model: ${SUBTITLE_GENERATION_MODELS.map((model) => model.id).join(', ')}`,
+    )
+    .option('--output <path>', 'Save subtitles to this SRT path')
+    .option('--audio-stream <index>', 'Absolute audio stream index from ffprobe')
+    .action((mediaPath: string | undefined, options: Record<string, unknown>) => {
+      const model = options.model;
+      if (model !== undefined && !isSubtitleGenerationModelId(model)) {
+        throw new Error(
+          `Generation --model must be one of: ${SUBTITLE_GENERATION_MODELS.map((entry) => entry.id).join(', ')}.`,
+        );
+      }
+      if (
+        options.modelPath !== undefined &&
+        (model !== undefined || options.downloadModel === true)
+      ) {
+        throw new Error(
+          'Generation --model-path cannot be combined with --model or --download-model.',
+        );
+      }
+      let audioStreamIndex: number | undefined;
+      if (typeof options.audioStream === 'string') {
+        audioStreamIndex = Number(options.audioStream);
+        if (!/^\d+$/.test(options.audioStream) || !Number.isSafeInteger(audioStreamIndex)) {
+          throw new Error('Generation --audio-stream must be a non-negative integer stream index.');
+        }
+      }
+      generateSubtitles = {
+        mediaPath,
+        downloadModel: options.downloadModel === true,
+        modelPath: typeof options.modelPath === 'string' ? options.modelPath : undefined,
+        managedModel: model,
+        outputPath: typeof options.output === 'string' ? options.output : undefined,
+        audioStreamIndex,
+      };
+    });
+
   commandProgram
     .command('jellyfin')
     .alias('jf')
@@ -360,6 +412,7 @@ export function parseCliPrograms(
     .option('--json', 'Emit machine-readable NDJSON progress output')
     .option('--make-temp', 'Create a sync temp directory and print its path (used over SSH)')
     .option('--remove-temp <dir>', 'Remove a sync temp directory created by --make-temp')
+    .option('--transfer-cache <key>', 'Reuse/save a received snapshot with temp helpers (internal)')
     .option('--ui', 'Open the SubMiner sync window')
     .option('--log-level <level>', 'Log level')
     .action((rawHost: string | undefined, options: Record<string, unknown>) => {
@@ -381,6 +434,7 @@ export function parseCliPrograms(
           check ||
           makeTemp ||
           removeTemp ||
+          options.transferCache !== undefined ||
           options.remoteCmd !== undefined ||
           options.db !== undefined ||
           options.json === true ||
@@ -402,6 +456,8 @@ export function parseCliPrograms(
       if (merge) tokens.push('--merge', merge);
       if (makeTemp) tokens.push('--make-temp');
       if (removeTemp) tokens.push('--remove-temp', removeTemp);
+      if (typeof options.transferCache === 'string')
+        tokens.push('--transfer-cache', options.transferCache);
       if (push) tokens.push('--push');
       if (pull) tokens.push('--pull');
       if (check) tokens.push('--check');
@@ -507,6 +563,7 @@ export function parseCliPrograms(
     options: selectedProgram.opts<Record<string, unknown>>(),
     rootTarget: rootProgram.processedArgs[0],
     invocations: {
+      generateSubtitles,
       jellyfinInvocation,
       configInvocation,
       settingsInvocation,
diff --git a/launcher/jellyfin.ts b/launcher/jellyfin.ts
index 742e4ffb..15cc1b26 100644
--- a/launcher/jellyfin.ts
+++ b/launcher/jellyfin.ts
@@ -89,7 +89,6 @@ export async function jellyfinApiRequest<T>(
   const url = `${session.serverUrl}${requestPath}`;
   const response = await fetch(url, {
     headers: {
-      'X-Emby-Token': session.accessToken,
       Authorization: `MediaBrowser Token="${session.accessToken}"`,
     },
   });
@@ -103,7 +102,7 @@ export async function jellyfinApiRequest<T>(
 }
 
 function itemPreviewUrl(session: JellyfinSessionConfig, id: string): string {
-  return `${session.serverUrl}/Items/${id}/Images/Primary?maxHeight=720&quality=85&api_key=${encodeURIComponent(session.accessToken)}`;
+  return `${session.serverUrl}/Items/${id}/Images/Primary?maxHeight=720&quality=85&ApiKey=${encodeURIComponent(session.accessToken)}`;
 }
 
 function jellyfinIconCacheDir(session: JellyfinSessionConfig): string {
diff --git a/launcher/main.test.ts b/launcher/main.test.ts
index 96c938cd..463420f1 100644
--- a/launcher/main.test.ts
+++ b/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"
diff --git a/launcher/main.ts b/launcher/main.ts
index 884f5528..c68106b2 100644
--- a/launcher/main.ts
+++ b/launcher/main.ts
@@ -25,6 +25,7 @@ import { runHistorySession } from './commands/history-command.js';
 import { runSyncCommand } from './commands/sync-command.js';
 import { runPlaybackCommand } from './commands/playback-command.js';
 import { runUpdateCommand } from './commands/update-command.js';
+import { runGenerateSubtitlesCommand } from './commands/generate-subtitles-command.js';
 
 const APP_VERSION =
   typeof packageJson.version === 'string' && packageJson.version.trim()
@@ -112,6 +113,10 @@ async function main(): Promise<void> {
     return;
   }
 
+  if (await runGenerateSubtitlesCommand(context)) {
+    return;
+  }
+
   const resolvedAppPath = ensureAppPath(context);
   state.appPath = resolvedAppPath;
   log('debug', args.logLevel, `Using SubMiner app binary: ${resolvedAppPath}`);
diff --git a/launcher/picker.test.ts b/launcher/picker.test.ts
index 281d1d1f..3a148d74 100644
--- a/launcher/picker.test.ts
+++ b/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`,
+  );
+});
diff --git a/launcher/picker.ts b/launcher/picker.ts
index c35e3205..98947048 100644
--- a/launcher/picker.ts
+++ b/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,
@@ -225,7 +228,7 @@ export function pickLibrary(
     commandExists('chafa') && commandExists('curl')
       ? `
 id={1}
-url=${escapeShellSingle(session.serverUrl)}/Items/$id/Images/Primary?maxHeight=720\\&quality=85\\&api_key=${escapeShellSingle(session.accessToken)}
+url=${escapeShellSingle(session.serverUrl)}/Items/$id/Images/Primary?maxHeight=720\\&quality=85\\&ApiKey=${escapeShellSingle(session.accessToken)}
 curl -fsSL "$url" 2>/dev/null | chafa --format=symbols --symbols=vhalf+wide --size=${'${FZF_PREVIEW_COLUMNS}'}x${'${FZF_PREVIEW_LINES}'} - 2>/dev/null
 `.trim()
       : 'echo "Install curl + chafa for image preview"';
@@ -263,7 +266,7 @@ export function pickItem(
     commandExists('chafa') && commandExists('curl')
       ? `
 id={1}
-url=${escapeShellSingle(session.serverUrl)}/Items/$id/Images/Primary?maxHeight=720\\&quality=85\\&api_key=${escapeShellSingle(session.accessToken)}
+url=${escapeShellSingle(session.serverUrl)}/Items/$id/Images/Primary?maxHeight=720\\&quality=85\\&ApiKey=${escapeShellSingle(session.accessToken)}
 curl -fsSL "$url" 2>/dev/null | chafa --format=symbols --symbols=vhalf+wide --size=${'${FZF_PREVIEW_COLUMNS}'}x${'${FZF_PREVIEW_LINES}'} - 2>/dev/null
 `.trim()
       : 'echo "Install curl + chafa for image preview"';
@@ -301,7 +304,7 @@ export function pickGroup(
     commandExists('chafa') && commandExists('curl')
       ? `
 id={1}
-url=${escapeShellSingle(session.serverUrl)}/Items/$id/Images/Primary?maxHeight=720\\&quality=85\\&api_key=${escapeShellSingle(session.accessToken)}
+url=${escapeShellSingle(session.serverUrl)}/Items/$id/Images/Primary?maxHeight=720\\&quality=85\\&ApiKey=${escapeShellSingle(session.accessToken)}
 curl -fsSL "$url" 2>/dev/null | chafa --format=symbols --symbols=vhalf+wide --size=${'${FZF_PREVIEW_COLUMNS}'}x${'${FZF_PREVIEW_LINES}'} - 2>/dev/null
 `.trim()
       : 'echo "Install curl + chafa for image preview"';
@@ -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) {
diff --git a/launcher/runtime-plugin-preflight.test.ts b/launcher/runtime-plugin-preflight.test.ts
index e07dfe67..7d9be846 100644
--- a/launcher/runtime-plugin-preflight.test.ts
+++ b/launcher/runtime-plugin-preflight.test.ts
@@ -1,6 +1,8 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
 import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
 import {
   ensureLinuxRuntimePluginAvailable,
   installManagedPluginAssetsViaApp,
@@ -31,7 +33,7 @@ test('ensureLinuxRuntimePluginAvailable is a no-op on non-Linux platforms', asyn
   assert.deepEqual(calls, []);
 });
 
-test('ensureLinuxRuntimePluginAvailable skips install when installed global plugin and managed theme exist', async () => {
+test('ensureLinuxRuntimePluginAvailable skips install when plugin, theme, and thumbnailer exist', async () => {
   const calls: string[] = [];
 
   await ensureLinuxRuntimePluginAvailable({
@@ -52,13 +54,17 @@ test('ensureLinuxRuntimePluginAvailable skips install when installed global plug
       calls.push('theme');
       return true;
     },
+    isManagedThumbnailerAvailable: () => {
+      calls.push('thumbnailer');
+      return true;
+    },
     log: () => {},
   });
 
-  assert.deepEqual(calls, ['detect', 'theme']);
+  assert.deepEqual(calls, ['detect', 'theme', 'thumbnailer']);
 });
 
-test('ensureLinuxRuntimePluginAvailable skips install when managed runtime path and theme already resolve', async () => {
+test('ensureLinuxRuntimePluginAvailable skips install when all managed assets resolve', async () => {
   const calls: string[] = [];
 
   await ensureLinuxRuntimePluginAvailable({
@@ -80,14 +86,19 @@ test('ensureLinuxRuntimePluginAvailable skips install when managed runtime path
       calls.push('theme');
       return true;
     },
+    isManagedThumbnailerAvailable: () => {
+      calls.push('thumbnailer');
+      return true;
+    },
     log: () => {},
   });
 
-  assert.deepEqual(calls, ['detect', 'resolve', 'theme']);
+  assert.deepEqual(calls, ['detect', 'resolve', 'theme', 'thumbnailer']);
 });
 
 test('ensureLinuxRuntimePluginAvailable installs managed assets when rofi theme is missing', async () => {
   const calls: string[] = [];
+  let themeAvailable = false;
 
   await ensureLinuxRuntimePluginAvailable({
     platform: 'linux',
@@ -102,10 +113,15 @@ test('ensureLinuxRuntimePluginAvailable installs managed assets when rofi theme
     },
     isManagedThemeAvailable: () => {
       calls.push('theme');
-      return false;
+      return themeAvailable;
+    },
+    isManagedThumbnailerAvailable: () => {
+      calls.push('thumbnailer');
+      return true;
     },
     installManagedPluginAssets: async () => {
       calls.push('install');
+      themeAvailable = true;
       return { ok: true, status: 'installed', path: '/tmp/plugin/main.lua' };
     },
     log: (level, _configured, message) => {
@@ -117,13 +133,68 @@ test('ensureLinuxRuntimePluginAvailable installs managed assets when rofi theme
     'detect',
     'resolve',
     'theme',
-    'info:Linux runtime support assets missing; installing managed plugin/theme assets.',
+    'info:Linux runtime support assets missing; installing managed plugin/theme/thumbnailer assets.',
     'install',
-    'info:Managed Linux runtime support assets installed: plugin=/tmp/plugin/main.lua theme=/tmp/xdg-data/SubMiner/themes/subminer.rasi',
+    'info:Managed Linux runtime support assets installed: plugin=/tmp/plugin/main.lua theme=/tmp/xdg-data/SubMiner/themes/subminer.rasi thumbnailer=/tmp/xdg-data/SubMiner/thumbnailers/subminer-ffmpegthumbnailer.thumbnailer',
     'resolve',
+    'theme',
+    'thumbnailer',
   ]);
 });
 
+test('ensureLinuxRuntimePluginAvailable installs managed assets when thumbnailer is missing', async () => {
+  const calls: string[] = [];
+  let thumbnailerAvailable = false;
+
+  await ensureLinuxRuntimePluginAvailable({
+    platform: 'linux',
+    xdgDataHome: '/tmp/xdg-data',
+    detectInstalledPlugin: () => true,
+    resolveRuntimePluginPath: () => '/tmp/plugin/main.lua',
+    isManagedThemeAvailable: () => true,
+    isManagedThumbnailerAvailable: () => thumbnailerAvailable,
+    installManagedPluginAssets: async () => {
+      calls.push('install');
+      thumbnailerAvailable = true;
+      return { ok: true, status: 'installed', path: '/tmp/plugin/main.lua' };
+    },
+    log: (_level, _configured, message) => {
+      calls.push(message);
+    },
+  });
+
+  assert.deepEqual(calls, [
+    'Linux runtime support assets missing; installing managed plugin/theme/thumbnailer assets.',
+    'install',
+    'Managed Linux runtime support assets installed: plugin=/tmp/plugin/main.lua theme=/tmp/xdg-data/SubMiner/themes/subminer.rasi thumbnailer=/tmp/xdg-data/SubMiner/thumbnailers/subminer-ffmpegthumbnailer.thumbnailer',
+  ]);
+});
+
+test('ensureLinuxRuntimePluginAvailable retains an installed plugin after installing support assets', async () => {
+  const calls: string[] = [];
+  let thumbnailerAvailable = false;
+
+  await ensureLinuxRuntimePluginAvailable({
+    platform: 'linux',
+    xdgDataHome: '/tmp/xdg-data',
+    detectInstalledPlugin: () => true,
+    resolveRuntimePluginPath: () => {
+      calls.push('resolve');
+      return null;
+    },
+    isManagedThemeAvailable: () => true,
+    isManagedThumbnailerAvailable: () => thumbnailerAvailable,
+    installManagedPluginAssets: async () => {
+      calls.push('install');
+      thumbnailerAvailable = true;
+      return { ok: true, status: 'installed', path: '/tmp/plugin/main.lua' };
+    },
+    log: () => {},
+  });
+
+  assert.deepEqual(calls, ['install']);
+});
+
 test('ensureLinuxRuntimePluginAvailable installs managed assets and re-resolves plugin path', async () => {
   const calls: string[] = [];
   let resolveCount = 0;
@@ -137,6 +208,8 @@ test('ensureLinuxRuntimePluginAvailable installs managed assets and re-resolves
       calls.push(`resolve:${resolveCount}`);
       return resolveCount === 1 ? null : '/tmp/plugin/main.lua';
     },
+    isManagedThemeAvailable: () => true,
+    isManagedThumbnailerAvailable: () => true,
     installManagedPluginAssets: async () => {
       calls.push('install');
       return { ok: true, status: 'installed', path: '/tmp/plugin/main.lua' };
@@ -148,9 +221,9 @@ test('ensureLinuxRuntimePluginAvailable installs managed assets and re-resolves
 
   assert.deepEqual(calls, [
     'resolve:1',
-    'info:Linux runtime support assets missing; installing managed plugin/theme assets.',
+    'info:Linux runtime support assets missing; installing managed plugin/theme/thumbnailer assets.',
     'install',
-    'info:Managed Linux runtime support assets installed: plugin=/tmp/plugin/main.lua theme=/tmp/xdg-data/SubMiner/themes/subminer.rasi',
+    'info:Managed Linux runtime support assets installed: plugin=/tmp/plugin/main.lua theme=/tmp/xdg-data/SubMiner/themes/subminer.rasi thumbnailer=/tmp/xdg-data/SubMiner/thumbnailers/subminer-ffmpegthumbnailer.thumbnailer',
     'resolve:2',
   ]);
 });
@@ -191,6 +264,60 @@ test('ensureLinuxRuntimePluginAvailable fails when runtime path remains unresolv
   );
 });
 
+test('ensureLinuxRuntimePluginAvailable fails when thumbnailer remains missing after install', async () => {
+  await assert.rejects(
+    () =>
+      ensureLinuxRuntimePluginAvailable({
+        platform: 'linux',
+        xdgDataHome: '/tmp/xdg-data',
+        detectInstalledPlugin: () => true,
+        resolveRuntimePluginPath: () => '/tmp/plugin/main.lua',
+        isManagedThemeAvailable: () => true,
+        isManagedThumbnailerAvailable: () => false,
+        installManagedPluginAssets: async () => ({
+          ok: true,
+          status: 'installed',
+          path: '/tmp/plugin/main.lua',
+        }),
+        log: () => {},
+      }),
+    /thumbnailer=.*subminer-ffmpegthumbnailer\.thumbnailer/i,
+  );
+});
+
+test('ensureLinuxRuntimePluginAvailable rejects a thumbnailer directory before and after install', async () => {
+  const xdgDataHome = fs.mkdtempSync(path.join(os.tmpdir(), 'subminer-thumbnailer-directory-'));
+  const thumbnailerPath = path.join(
+    xdgDataHome,
+    'SubMiner',
+    'thumbnailers',
+    'subminer-ffmpegthumbnailer.thumbnailer',
+  );
+  fs.mkdirSync(thumbnailerPath, { recursive: true });
+  const calls: string[] = [];
+
+  try {
+    await assert.rejects(
+      () =>
+        ensureLinuxRuntimePluginAvailable({
+          platform: 'linux',
+          xdgDataHome,
+          detectInstalledPlugin: () => true,
+          isManagedThemeAvailable: () => true,
+          installManagedPluginAssets: async () => {
+            calls.push('install');
+            return { ok: true, status: 'installed', path: '/tmp/plugin/main.lua' };
+          },
+          log: () => {},
+        }),
+      /thumbnailer=.*subminer-ffmpegthumbnailer\.thumbnailer/i,
+    );
+    assert.deepEqual(calls, ['install']);
+  } finally {
+    fs.rmSync(xdgDataHome, { recursive: true, force: true });
+  }
+});
+
 test('installManagedPluginAssetsViaApp returns launch errors without waiting for a response file', async () => {
   let waited = false;
 
diff --git a/launcher/runtime-plugin-preflight.ts b/launcher/runtime-plugin-preflight.ts
index b794cd6b..e1771a3e 100644
--- a/launcher/runtime-plugin-preflight.ts
+++ b/launcher/runtime-plugin-preflight.ts
@@ -31,6 +31,7 @@ type EnsureLinuxRuntimePluginAvailableOptions = {
   detectInstalledPlugin?: () => boolean;
   resolveRuntimePluginPath?: () => string | null;
   isManagedThemeAvailable?: () => boolean;
+  isManagedThumbnailerAvailable?: () => boolean;
   installManagedPluginAssets?: () => Promise<EnsureLinuxRuntimePluginAssetsResult>;
   log?: PreflightLog;
 };
@@ -48,6 +49,14 @@ function resolveConfiguredLogLevel(
   return logLevel ?? 'warn';
 }
 
+function isRegularFile(filePath: string): boolean {
+  try {
+    return fs.statSync(filePath).isFile();
+  } catch {
+    return false;
+  }
+}
+
 async function waitForInstallResponse(
   responsePath: string,
 ): Promise<RuntimePluginPreflightResponse | null> {
@@ -170,15 +179,17 @@ export async function ensureLinuxRuntimePluginAvailable(
     });
   const isManagedThemeAvailable =
     options.isManagedThemeAvailable ?? (() => fs.existsSync(managedPaths.themePath));
+  const isManagedThumbnailerAvailable =
+    options.isManagedThumbnailerAvailable ?? (() => isRegularFile(managedPaths.thumbnailerPath));
   const runtimePluginAvailable = installedPluginAvailable || Boolean(resolveRuntimePluginPath());
-  if (runtimePluginAvailable && isManagedThemeAvailable()) {
+  if (runtimePluginAvailable && isManagedThemeAvailable() && isManagedThumbnailerAvailable()) {
     return;
   }
 
   log(
     'info',
     configuredLogLevel,
-    'Linux runtime support assets missing; installing managed plugin/theme assets.',
+    'Linux runtime support assets missing; installing managed plugin/theme/thumbnailer assets.',
   );
   const installManagedPluginAssets =
     options.installManagedPluginAssets ??
@@ -207,16 +218,21 @@ export async function ensureLinuxRuntimePluginAvailable(
   log(
     'info',
     configuredLogLevel,
-    `Managed Linux runtime support assets installed: plugin=${installResult.path ?? 'unknown path'} theme=${managedPaths.themePath}`,
+    `Managed Linux runtime support assets installed: plugin=${installResult.path ?? 'unknown path'} theme=${managedPaths.themePath} thumbnailer=${managedPaths.thumbnailerPath}`,
   );
-  const runtimePluginPath = resolveRuntimePluginPath();
-  if (runtimePluginPath) {
+  const runtimePluginAvailableAfterInstall =
+    installedPluginAvailable || Boolean(resolveRuntimePluginPath());
+  if (
+    runtimePluginAvailableAfterInstall &&
+    isManagedThemeAvailable() &&
+    isManagedThumbnailerAvailable()
+  ) {
     return;
   }
 
   const message =
     `Linux managed runtime plugin assets could not be installed. ` +
-    `Checked path: ${managedPaths.pluginEntrypointPath}. ` +
+    `Checked paths: plugin=${managedPaths.pluginEntrypointPath} theme=${managedPaths.themePath} thumbnailer=${managedPaths.thumbnailerPath}. ` +
     'Launch aborted before starting mpv.';
   log('warn', configuredLogLevel, message);
   throw new Error(message);
diff --git a/launcher/smoke.e2e.test.ts b/launcher/smoke.e2e.test.ts
index d44a07c4..718622f8 100644
--- a/launcher/smoke.e2e.test.ts
+++ b/launcher/smoke.e2e.test.ts
@@ -165,11 +165,14 @@ if (entry.argv.includes('--ensure-linux-runtime-plugin-assets')) {
   const pluginDir = path.join(dataDir, 'plugin', 'subminer');
   const pluginConfigPath = path.join(dataDir, 'plugin', 'subminer.conf');
   const themePath = path.join(dataDir, 'themes', 'subminer.rasi');
+  const thumbnailerPath = path.join(dataDir, 'thumbnailers', 'subminer-ffmpegthumbnailer.thumbnailer');
   fs.mkdirSync(pluginDir, { recursive: true });
   fs.mkdirSync(path.dirname(themePath), { recursive: true });
+  fs.mkdirSync(path.dirname(thumbnailerPath), { recursive: true });
   fs.writeFileSync(path.join(pluginDir, 'main.lua'), '-- smoke plugin\\n');
   fs.writeFileSync(pluginConfigPath, 'smoke=true\\n');
   fs.writeFileSync(themePath, '/* smoke theme */\\n');
+  fs.writeFileSync(thumbnailerPath, '[Thumbnailer Entry]\\n');
   if (responsePath) {
     fs.mkdirSync(path.dirname(responsePath), { recursive: true });
     fs.writeFileSync(responsePath, JSON.stringify({ ok: true, status: 'installed', path: path.join(pluginDir, 'main.lua') }));
@@ -620,11 +623,22 @@ test(
       );
       assert.match(result.stdout, /pause mpv until overlay and tokenization are ready/i);
       if (process.platform === 'linux') {
-        assert.match(result.stdout, /managed plugin\/theme assets/i);
+        assert.match(result.stdout, /managed plugin\/theme\/thumbnailer assets/i);
         assert.equal(
           fs.existsSync(path.join(smokeCase.xdgDataHome, 'SubMiner', 'themes', 'subminer.rasi')),
           true,
         );
+        assert.equal(
+          fs.existsSync(
+            path.join(
+              smokeCase.xdgDataHome,
+              'SubMiner',
+              'thumbnailers',
+              'subminer-ffmpegthumbnailer.thumbnailer',
+            ),
+          ),
+          true,
+        );
       }
     });
   },
diff --git a/launcher/test-support/immersion-db-schema.test.ts b/launcher/test-support/immersion-db-schema.test.ts
index 0320a7c9..22d71d2e 100644
--- a/launcher/test-support/immersion-db-schema.test.ts
+++ b/launcher/test-support/immersion-db-schema.test.ts
@@ -31,6 +31,7 @@ const SYNC_SCHEMA_OBJECTS = [
   'imm_lifetime_applied_sessions',
   'imm_stats_excluded_words',
   'idx_anime_normalized_title',
+  'idx_anime_namespace_title',
   'idx_anime_anilist_id',
   'idx_videos_anime_id',
   'idx_sessions_video_started',
diff --git a/launcher/test-support/immersion-db-schema.ts b/launcher/test-support/immersion-db-schema.ts
index c99e2cf4..dcf1c681 100644
--- a/launcher/test-support/immersion-db-schema.ts
+++ b/launcher/test-support/immersion-db-schema.ts
@@ -12,7 +12,7 @@ export const IMMERSION_DB_FIXTURE_DDL = `
   );
   CREATE TABLE imm_anime(
     anime_id INTEGER PRIMARY KEY AUTOINCREMENT,
-    normalized_title_key TEXT NOT NULL UNIQUE,
+    normalized_title_key TEXT NOT NULL,
     canonical_title TEXT NOT NULL,
     anilist_id INTEGER UNIQUE,
     title_romaji TEXT,
@@ -20,10 +20,14 @@ export const IMMERSION_DB_FIXTURE_DDL = `
     title_native TEXT,
     episodes_total INTEGER,
     description TEXT,
+    media_kind TEXT NOT NULL DEFAULT 'anime',
+    tmdb_id INTEGER,
+    tmdb_type TEXT,
     metadata_json TEXT,
     CREATED_DATE TEXT,
     LAST_UPDATE_DATE TEXT
   );
+  CREATE UNIQUE INDEX idx_anime_namespace_title ON imm_anime((media_kind = 'youtube'), normalized_title_key);
   CREATE TABLE imm_videos(
     video_id INTEGER PRIMARY KEY AUTOINCREMENT,
     video_key TEXT NOT NULL UNIQUE,
diff --git a/launcher/types.ts b/launcher/types.ts
index bfc82ea0..ffee903e 100644
--- a/launcher/types.ts
+++ b/launcher/types.ts
@@ -1,6 +1,7 @@
 import path from 'node:path';
 import os from 'node:os';
 import type { MpvBackend, MpvLaunchMode } from '../src/types/config.js';
+import type { SubtitleGenerationConfig } from '../src/shared/subtitle-generation.js';
 import {
   resolveDefaultLogFilePath,
   type LogFileToggles,
@@ -88,6 +89,14 @@ export interface LauncherAiConfig {
 }
 
 export interface Args {
+  generateSubtitles?: {
+    mediaPath?: string;
+    downloadModel: boolean;
+    modelPath?: string;
+    managedModel?: SubtitleGenerationConfig['managedModel'];
+    outputPath?: string;
+    audioStreamIndex?: number;
+  };
   backend: Backend;
   directory: string;
   recursive: boolean;
diff --git a/package.json b/package.json
index 354132fc..b21262be 100644
--- a/package.json
+++ b/package.json
@@ -2,7 +2,7 @@
   "name": "subminer",
   "productName": "SubMiner",
   "desktopName": "SubMiner.desktop",
-  "version": "0.19.4-beta.1",
+  "version": "0.20.0",
   "description": "All-in-one sentence mining overlay with AnkiConnect and dictionary integration",
   "packageManager": "bun@1.3.5",
   "main": "dist/main-entry.js",
@@ -18,7 +18,7 @@
     "compare-yomitan-api:electron": "bun run build:yomitan && bun build scripts/compare-yomitan-api.ts --format=cjs --target=node --outfile dist/scripts/compare-yomitan-api.js --external electron && env -u ELECTRON_RUN_AS_NODE electron dist/scripts/compare-yomitan-api.js",
     "build:yomitan": "bun scripts/build-yomitan.mjs",
     "build:assets": "bun scripts/prepare-build-assets.mjs",
-    "build:launcher": "bun build ./launcher/main.ts --target=bun --packages=bundle --banner='#!/usr/bin/env bun' --outfile=dist/launcher/subminer",
+    "build:launcher": "bun run scripts/build-launcher.ts",
     "build:stats": "cd stats && bun run build",
     "dev:stats": "cd stats && bun run dev",
     "build": "bun run build:yomitan && bun run build:stats && tsc -p tsconfig.json && bun run build:renderer && bun run build:settings && bun run build:syncui && bun run build:launcher && bun run build:assets",
@@ -32,6 +32,7 @@
     "changelog:pr-check": "bun run scripts/build-changelog.ts pr-check",
     "changelog:release-notes": "bun run scripts/build-changelog.ts release-notes",
     "changelog:prerelease-notes": "bun run scripts/build-changelog.ts prerelease-notes",
+    "changelog:check-prerelease-notes": "bun run scripts/build-changelog.ts check-prerelease-notes",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
     "format:src": "bash scripts/prettier-scope.sh --write",
@@ -50,7 +51,7 @@
     "test:docs:kb": "bun test scripts/docs-knowledge-base.test.ts",
     "test:plugin:src": "lua scripts/test-plugin-lua-compat.lua && lua scripts/test-plugin-start-gate.lua && lua scripts/test-plugin-process-start-retries.lua && lua scripts/test-plugin-restart-feedback.lua && lua scripts/test-plugin-session-bindings.lua && lua scripts/test-plugin-binary-windows.lua",
     "test:launcher:smoke:src": "bun test launcher/smoke.e2e.test.ts",
-    "test:smoke:dist": "bun scripts/run-test-lane.mjs bun-src-full",
+    "test:smoke:dist": "env ELECTRON_RUN_AS_NODE=1 electron scripts/compiled-runtime-smoke.mjs",
     "test:subtitle:src": "bun test src/core/services/subsync.test.ts src/subsync/utils.test.ts",
     "test:immersion:sqlite:src": "bun test src/core/services/immersion-tracker-service.test.ts src/core/services/immersion-tracker/storage-session.test.ts",
     "test:immersion:sqlite:dist": "bun test dist/core/services/immersion-tracker-service.test.js dist/core/services/immersion-tracker/storage-session.test.js",
@@ -62,7 +63,7 @@
     "test:scripts": "bun scripts/run-test-lane.mjs scripts",
     "test:stats": "bun scripts/run-test-lane.mjs stats",
     "test:env": "bun run test:launcher:smoke:src && bun run test:plugin:src && bun run test:immersion:sqlite:src",
-    "test:runtime:compat": "bun run tsc && bun scripts/run-test-lane.mjs bun-src-full",
+    "test:runtime:compat": "bun run test:smoke:dist",
     "test": "bun run test:fast",
     "test:config": "bun scripts/run-test-lane.mjs config",
     "test:launcher": "bun scripts/run-test-lane.mjs launcher && bun run test:plugin:src",
@@ -79,17 +80,18 @@
     "build:mac:unsigned": "bun run build && env -u APPLE_ID -u APPLE_APP_SPECIFIC_PASSWORD -u APPLE_TEAM_ID -u CSC_LINK -u CSC_KEY_PASSWORD CSC_IDENTITY_AUTO_DISCOVERY=false electron-builder --mac dmg zip --publish never",
     "build:mac:zip": "bun run build && electron-builder --mac zip --publish never",
     "build:win": "bun run build && electron-builder --win nsis zip --publish never",
-    "build:win:unsigned": "bun run build && node scripts/build-win-unsigned.mjs"
+    "build:win:unsigned": "bun run build && node scripts/build-win-unsigned.mjs",
+    "test:package": "bun scripts/run-package-smoke.mjs"
   },
   "overrides": {
-    "@xmldom/xmldom": "0.8.13",
-    "app-builder-lib": "26.15.3",
+    "@xmldom/xmldom": "0.8.15",
+    "app-builder-lib": "26.16.1",
     "brace-expansion": "5.0.9",
-    "electron-builder-squirrel-windows": "26.15.3",
-    "fast-uri": "3.1.5",
+    "electron-builder-squirrel-windows": "26.16.1",
+    "fast-uri": "3.1.6",
     "form-data": "4.0.6",
     "ip-address": "10.2.0",
-    "js-yaml": "4.3.1",
+    "js-yaml": "4.3.2",
     "lodash": "4.18.0",
     "minimatch": "10.2.5",
     "picomatch": "4.0.4",
@@ -123,15 +125,16 @@
     "ws": "^8.21.0"
   },
   "devDependencies": {
+    "@electron/asar": "3.4.1",
     "@types/node": "^24.10.0",
     "@types/ws": "^8.18.1",
-    "electron": "43.4.1",
-    "electron-builder": "26.15.3",
-    "undici": "7.29.0",
+    "electron": "43.7.2",
+    "electron-builder": "26.16.1",
     "esbuild": "^0.25.12",
     "eslint": "^10.8.0",
     "prettier": "^3.8.1",
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3",
+    "undici": "7.29.0"
   },
   "build": {
     "appId": "com.sudacode.SubMiner",
@@ -158,6 +161,10 @@
       "category": "AudioVideo",
       "executableArgs": [
         "--background"
+      ],
+      "files": [
+        "package.json",
+        "!node_modules/koffi{,/**/*}"
       ]
     },
     "mac": {
@@ -176,6 +183,10 @@
           "from": "dist/scripts/get-mpv-window-macos",
           "to": "scripts/get-mpv-window-macos"
         }
+      ],
+      "files": [
+        "package.json",
+        "!node_modules/koffi{,/**/*}"
       ]
     },
     "dmg": {
@@ -187,7 +198,11 @@
         "nsis",
         "zip"
       ],
-      "icon": "assets/SubMiner.ico"
+      "icon": "assets/SubMiner.ico",
+      "files": [
+        "package.json",
+        "!node_modules/koffi/build/koffi/!(win32_${arch}){,/**/*}"
+      ]
     },
     "nsis": {
       "artifactName": "SubMiner-${version}.${ext}",
@@ -197,43 +212,19 @@
       "include": "build/installer.nsh"
     },
     "files": [
-      "**/*",
-      "!assets{,/**/*}",
-      "!src{,/**/*}",
-      "!launcher{,/**/*}",
-      "!docs{,/**/*}",
-      "!tests{,/**/*}",
-      "!packaging{,/**/*}",
-      "!README.md",
-      "!CHANGELOG.md",
-      "!AGENTS.md",
-      "!CLAUDE.md",
-      "!stats/src{,/**/*}",
-      "!stats/index.html",
-      "!stats/public{,/**/*}",
-      "!stats/package.json",
-      "!stats/tsconfig.json",
-      "!stats/vite.config.ts",
-      "!docs-site{,/**/*}",
-      "!changes{,/**/*}",
-      "!.tmp{,/**/*}",
-      "!release-*{,/**/*}",
-      "!dist/**/*.map",
-      "!dist/**/*.test.*",
-      "!dist/**/__tests__{,/**/*}",
-      "!scripts/**/*.test.*",
-      "!plugin{,/**/*}",
-      "!vendor/subminer-yomitan{,/**/*}",
-      "!vendor/yomitan-jlpt-vocab{,/**/*}",
-      "!vendor/texthooker-ui/src{,/**/*}",
-      "!vendor/texthooker-ui/node_modules{,/**/*}",
-      "!vendor/texthooker-ui/.svelte-kit{,/**/*}",
-      "!vendor/texthooker-ui/.vscode{,/**/*}",
-      "!vendor/texthooker-ui/public{,/**/*}",
-      "!vendor/texthooker-ui/README.md",
-      "!vendor/texthooker-ui/package.json",
-      "!vendor/texthooker-ui/package-lock.json",
-      "!vendor/texthooker-ui/tsconfig*.json",
+      "dist/**/*",
+      "stats/dist/**/*",
+      "vendor/texthooker-ui/docs/**/*",
+      "config.example.jsonc",
+      "LICENSE",
+      "!**/*.map",
+      "!**/*.{ts,tsx,mts,cts}",
+      "!**/*.{test,spec}.*",
+      "!**/{test,tests,__tests__,fixture,fixtures,__fixtures__}{,/**/*}",
+      "!dist/launcher{,/**/*}",
+      "!dist/scripts{,/**/*}",
+      "!dist/{renderer,settings,syncui}/fonts{,/**/*}",
+      "!node_modules/koffi/{src,vendor,doc}{,/**/*}",
       "!node_modules/@libsql/linux-x64-musl{,/**/*}"
     ],
     "extraResources": [
@@ -247,7 +238,13 @@
       },
       {
         "from": "assets",
-        "to": "assets"
+        "to": "assets",
+        "filter": [
+          "SubMiner*.png",
+          "SubMiner.ico",
+          "themes/**/*",
+          "thumbnailers/**/*"
+        ]
       },
       {
         "from": "plugin/subminer",
@@ -258,8 +255,15 @@
         "to": "plugin/subminer.conf"
       },
       {
-        "from": "dist/launcher/subminer",
-        "to": "launcher/subminer"
+        "from": "dist/launcher",
+        "to": "launcher",
+        "filter": [
+          "subminer",
+          "subminer.cmd",
+          "subminer.js",
+          "prepare.cjs",
+          "version"
+        ]
       },
       {
         "from": "CHANGELOG.md",
diff --git a/packaging/aur/subminer-bin/.SRCINFO b/packaging/aur/subminer-bin/.SRCINFO
index 5f734785..cb84fc25 100644
--- a/packaging/aur/subminer-bin/.SRCINFO
+++ b/packaging/aur/subminer-bin/.SRCINFO
@@ -5,7 +5,11 @@ pkgbase = subminer-bin
 	url = https://github.com/ksyasuda/SubMiner
 	arch = x86_64
 	license = GPL-3.0-or-later
-	depends = bun
+	license = MIT
+	license = LGPL-2.0-only
+	license = LGPL-2.1-only
+	license = Apache-2.0
+	license = BSD-3-Clause
 	depends = fuse2
 	depends = glibc
 	depends = mpv
diff --git a/packaging/aur/subminer-bin/PKGBUILD b/packaging/aur/subminer-bin/PKGBUILD
index c01e73ab..99ef6aec 100644
--- a/packaging/aur/subminer-bin/PKGBUILD
+++ b/packaging/aur/subminer-bin/PKGBUILD
@@ -6,10 +6,9 @@ pkgrel=1
 pkgdesc='All-in-one sentence mining overlay with AnkiConnect and dictionary integration'
 arch=('x86_64')
 url='https://github.com/ksyasuda/SubMiner'
-license=('GPL-3.0-or-later')
+license=('GPL-3.0-or-later' 'MIT' 'LGPL-2.0-only' 'LGPL-2.1-only' 'Apache-2.0' 'BSD-3-Clause')
 options=('!strip' '!debug')
 depends=(
-	'bun'
 	'fuse2'
 	'glibc'
 	'mpv'
@@ -58,7 +57,14 @@ package() {
 		"${pkgdir}/usr/share/SubMiner/plugin/subminer.conf"
 	install -Dm644 "${srcdir}/assets/themes/subminer.rasi" \
 		"${pkgdir}/usr/share/SubMiner/themes/subminer.rasi"
+	install -Dm644 "${srcdir}/assets/thumbnailers/subminer-ffmpegthumbnailer.thumbnailer" \
+		"${pkgdir}/usr/share/SubMiner/thumbnailers/subminer-ffmpegthumbnailer.thumbnailer"
 
 	install -dm755 "${pkgdir}/usr/share/SubMiner/plugin/subminer"
 	cp -a "${srcdir}/plugin/subminer/." "${pkgdir}/usr/share/SubMiner/plugin/subminer/"
+
+	# Bundled Bun runtime notices: MIT and BSD texts are not in the licenses package.
+	install -dm755 "${pkgdir}/usr/share/licenses/${pkgname}"
+	install -m644 "${srcdir}"/resources/bun/licenses/* \
+		"${pkgdir}/usr/share/licenses/${pkgname}/"
 }
diff --git a/plugin/subminer/session_bindings.lua b/plugin/subminer/session_bindings.lua
index 8c40b8b3..b0f81a5a 100644
--- a/plugin/subminer/session_bindings.lua
+++ b/plugin/subminer/session_bindings.lua
@@ -91,6 +91,10 @@ function M.create(ctx)
 	end
 
 	local function key_code_to_mpv_name(code)
+		local first, second = code:match("^Key([A-Z])%-Key([A-Z])$")
+		if first and second then
+			return string.lower(first) .. "-" .. string.lower(second)
+		end
 		if KEY_NAME_MAP[code] then
 			return KEY_NAME_MAP[code]
 		end
@@ -187,6 +191,110 @@ function M.create(ctx)
 		return bindings
 	end
 
+	-- Match letter strokes, including mpv's uppercase spelling for Shift.
+	local function letter_key_signature(value)
+		if type(value) ~= "string" then
+			return nil
+		end
+		local modifiers = {}
+		while true do
+			local modifier, rest = value:match("^([%a]+)%+(.+)$")
+			if not modifier then
+				break
+			end
+			modifier = string.lower(modifier)
+			if not MODIFIER_MAP[modifier] then
+				return nil
+			end
+			modifiers[modifier] = true
+			value = rest
+		end
+		if not value:match("^[a-zA-Z]$") then
+			return nil
+		end
+		if value:match("^[A-Z]$") then
+			modifiers.shift = true
+		end
+		local parts = {}
+		for _, modifier in ipairs({ "ctrl", "alt", "shift", "meta" }) do
+			if modifiers[modifier] then
+				parts[#parts + 1] = modifier
+			end
+		end
+		parts[#parts + 1] = string.lower(value)
+		return table.concat(parts, "+")
+	end
+
+	local function external_single_keys()
+		local keys = {}
+		local native = mp.get_property_native and mp.get_property_native("input-bindings") or {}
+		for _, entry in ipairs(native or {}) do
+			local signature = letter_key_signature(entry.key)
+			if
+				signature
+				and type(entry.cmd) == "string"
+				and type(entry.priority) == "number"
+				and entry.priority >= 0
+			then
+				local owned = entry.owner == "subminer"
+					or (
+						entry.owner == nil
+						and (
+							entry.cmd:match("script%-binding%s+['\"]?subminer/")
+							or entry.cmd:match("script%-message%s+['\"]?subminer%-")
+						)
+					)
+				local previous = keys[signature]
+				if
+					not previous
+					or entry.priority > previous.priority
+					or (entry.priority == previous.priority and owned)
+				then
+					local command = entry.cmd:match("^%s*(.-)%s*$")
+					local flags = {
+						["no-osd"] = true,
+						["osd-bar"] = true,
+						["osd-msg"] = true,
+						["osd-msg-bar"] = true,
+						["osd-auto"] = true,
+						["expand-properties"] = true,
+						["raw"] = true,
+						["repeatable"] = true,
+						["nonrepeatable"] = true,
+						["nonscalable"] = true,
+						["async"] = true,
+						["sync"] = true,
+					}
+					while true do
+						local flag, rest = command:match("^(%S+)%s+(.+)$")
+						if not flags[flag] then
+							break
+						end
+						command = rest
+					end
+					keys[signature] = { priority = entry.priority, owned = owned, ignored = command == "ignore" }
+				end
+			end
+		end
+		return keys
+	end
+
+	local function sequence_conflict(binding, singles)
+		local code = binding.key and binding.key.code
+		local prefix = type(code) == "string" and code:match("^(Key[A-Z])%-Key[A-Z]$")
+		if not prefix then
+			return nil
+		end
+		local names = key_spec_to_mpv_bindings({ code = prefix, modifiers = binding.key.modifiers }) or {}
+		for _, name in ipairs(names) do
+			local existing = singles[letter_key_signature(name)]
+			if existing and not existing.owned and not existing.ignored then
+				return name
+			end
+		end
+		return nil
+	end
+
 	local function normalize_cli_args(cli_args)
 		if type(cli_args) ~= "table" then
 			return nil
@@ -391,17 +499,23 @@ function M.create(ctx)
 		local next_binding_names = {}
 		state.session_binding_generation = (state.session_binding_generation or 0) + 1
 		local generation = state.session_binding_generation
+		local singles = external_single_keys()
 
 		for index, binding in ipairs(artifact.bindings) do
 			if not is_supported_binding(binding) then
-				subminer_log(
-					"warn",
-					"session-bindings",
-					"Skipped unsupported session binding from artifact"
-				)
+				subminer_log("warn", "session-bindings", "Skipped unsupported session binding from artifact")
 			else
 				local key_names = key_spec_to_mpv_bindings(binding.key)
-				if key_names then
+				local conflict = sequence_conflict(binding, singles)
+				if conflict then
+					local message = "Disabled sequence "
+						.. tostring(binding.originalKey or binding.key.code)
+						.. ": mpv already uses "
+						.. conflict
+						.. ". Single-key bindings take priority."
+					subminer_log("warn", "session-bindings", message)
+					show_osd(message)
+				elseif key_names then
 					for key_index, key_name in ipairs(key_names) do
 						local name = "subminer-session-binding-"
 							.. tostring(generation)
@@ -418,7 +532,8 @@ function M.create(ctx)
 					subminer_log(
 						"warn",
 						"session-bindings",
-						"Skipped unsupported key code from artifact: " .. tostring(binding.key and binding.key.code or "unknown")
+						"Skipped unsupported key code from artifact: "
+							.. tostring(binding.key and binding.key.code or "unknown")
 					)
 				end
 			end
diff --git a/release/prerelease-notes.md b/release/prerelease-notes.md
index 38af51ad..60889b1f 100644
--- a/release/prerelease-notes.md
+++ b/release/prerelease-notes.md
@@ -1,52 +1,125 @@
 > This is a prerelease build for testing. Stable changelog and docs-site updates remain pending until the final stable release.
 
-<!-- prerelease-base-version: 0.19.4 -->
+<!-- prerelease-version: 0.20.0-beta.2; since: v0.20.0-beta.1 -->
+
+## Changes since v0.20.0-beta.1
+
+- Added an optional subtitle selection modal for primary and secondary mpv subtitle tracks. Enable it in Settings > Behavior, then press `g` followed by `s`. Disabling it restores mpv's subtitle selection binding.
+  - Single-key shortcut actions now take priority over configured multi-key sequence prefixes, conflicting sequences are disabled with a warning, and existing `y` commands remain reserved.
+- Jellyfin casting and playback now honor a configured mpv executable path, allowing playback when mpv is installed outside the system PATH, and portable plugins located beside that executable are now detected.
+- Fixed word-card sentence furigana falling out of sync with full stats-search context and expanded timing-review selections; stale furigana is now cleared if regeneration fails.
 
 ## Highlights
+
 ### Added
-- **Library Merge and Move**
-  - Duplicate library cards for the same show can now be combined: select cards in the library grid, choose "Merge Selected," and pick which entry to keep. Sessions, mined cards, and watch time move over, and future episodes stay matched to the merged card.
-  - Episodes can be reassigned to a different library entry with a "→" button on the episode row, fixing cases where a file lands under the wrong title. Manual assignments survive later filename parsing, Jellyfin refreshes, and season repair.
-  - Exact AniList matches with compatible seasons now merge automatically, while fuzzy matches show up as a dismissible "Possible duplicate" prompt instead of merging without confirmation.
+
+- **Japanese Subtitle Generation**:
+  - Generate Japanese subtitles locally with whisper.cpp, right from a modal (`Ctrl+Shift+G`), the subtitle sidebar's generation button when no subtitles are loaded, or `subminer generate-subs`, with progress, cancellation, and automatic loading into mpv when it's done.
+  - Pick and download an official multilingual Whisper model in-app (including smaller quantized variants), or point Settings at one you already have. SubMiner recommends `large-v3-turbo` when CUDA is available and `small` otherwise, and tells you up front if `whisper-cli`, `ffmpeg`, or `ffprobe` can't be found.
+  - An optional "Focus on spoken dialogue" mode uses a Silero VAD model to keep quiet or music-covered dialogue that would otherwise get dropped.
+  - Long passages split near natural speech pauses, guided by an existing subtitle track when one is loaded, giving tighter timing and fewer repeated-word glitches.
+
+- **Media Timing Review Frame Picker**:
+  - The screenshot used for a mined card can now be chosen independently of the audio clip, with its own live preview, time slider, and frame-by-frame stepping.
+  - Works for local video and for seekable remote streams like Jellyfin.
+
+- **Overlay Keybinding Pickup**: The overlay now recognizes your mpv keybindings (from mpv's defaults, `input.conf`, and loaded scripts) as long as they don't conflict with SubMiner's own controls. Picked-up bindings work for the session but won't show up in the help menu.
+
+- **Subtitle Selection Modal**:
+  - An optional subtitle selection modal lets you pick primary and secondary mpv subtitle tracks without leaving the overlay.
+  - Enable it in Settings under Behavior, then trigger it with `g` followed by `s`; turning it off restores mpv's normal subtitle selection binding.
+  - Single-key shortcuts always take priority over multi-key sequences, and any conflicting sequence is disabled with a warning instead of misbehaving.
+
+- **Subtitle Sidebar Selection & Copy**: You can now select dialogue across multiple subtitle sidebar rows and copy it, without timestamps, using Ctrl/Cmd+C or the Copy button, without seeking or mining a card.
+
+- **Jimaku Live Action Search**: The Jimaku modal has separate Anime and Live Action tabs (switch with Arrow Left/Right) so you can search Jimaku's live-action subtitle catalogue directly.
+
+- **Live-Action TMDB Library**:
+  - Live-action dramas and movies in the stats Library now get posters, synopses, and titles from TMDB.
+  - Titles AniList can't match are looked up on TMDB automatically when the parsed filename matches a title exactly; otherwise use the new **Link to TMDB** action. Entries linked to the same TMDB title merge into one card, and the Library kind selector gained a Live Action option.
+  - Release builds already include a TMDB key; if you run from source, set `tmdb.apiKey` (or `tmdb.apiKeyCommand`) yourself.
+
+- **YouTube Library Kind**:
+  - YouTube channels are now their own Library media kind, with new All Titles, Anime, and YouTube filters. Existing channel entries migrate automatically with viewing history and manual video assignments intact.
+  - Channels stay out of AniList matching, season repair, and duplicate recommendations, and can't be merged or moved into an anime entry.
+
+### Changed
+
+- **Bundled Bun Runtime**: Every SubMiner launcher, installed or downloaded, now runs on the Bun runtime bundled with the app instead of a system-wide Bun install. Recognized legacy launchers migrate automatically, Windows users get a new `subminer.cmd` download, and first-run setup now shows a single optional launcher control with runtime repair guidance only when something actually needs it.
+
+- **Compressed Incremental Sync**: Cross-machine sync between compatible macOS/Linux machines now transfers only what changed, compressed, using a cached snapshot from the last sync to cut traffic further. Machines without a compatible rsync (including Windows) fall back to compressed scp automatically, older peers keep working, and transfers now time out after 30 minutes instead of hanging indefinitely.
+
+- **Smaller Install Size**: Installers and the unpacked app are smaller after dropping demo media, source maps, TypeScript sources, test fixtures, and unused binaries, and sharing one Japanese UI font across windows. Release builds now publish a package-size comparison against the previous release.
+
+- **Stats Server Request Safety**: The stats server, including the in-app stats overlay which now loads through it, only accepts requests from the local machine and requires a JSON content type for anything that changes data. If you were exposing the dashboard through a reverse proxy or Tailscale Serve, that's no longer supported, and any script posting to the stats API needs to send `Content-Type: application/json`.
+
+- **Yomitan Updated**: Bundled Yomitan is updated to upstream 26.9.8, adding historical Japanese kana transformations and Ukrainian language support, plus improvements to Anki duplicate search and audio retrieval.
 
 ### Fixed
-- **Anki Audio Generation on Network Drives**
-  - Fixed sentence-audio generation timing out on slow network-mounted video files with many subtitle and font-attachment streams.
-  - Extraction now uses bounded probing and a two-minute budget, and failures show a clear error instead of a cryptic one.
-- **Duplicate Subtitle Line Stats**
-  - Fixed karaoke openings and animated signs (which record one subtitle event per animation frame) inflating word and kanji counts and skewing "Top Repeated Words." Ordinary repeated dialogue and rewatches are unaffected.
-  - Already-inflated stats can be cleaned up with the new "Duplicates" button in the Vocabulary tab, or `subminer stats cleanup --duplicate-lines` (supports `--dry-run` and `--lookback-days`). Only the affected subtitle lines and vocabulary counts are touched; watch time and lines-seen totals are untouched.
-- **Overlay Modals on macOS and Windows**
-  - Fixed overlay modals and the stats window opening on the wrong macOS Space, or forcing a Space switch, when mpv is fullscreen. They now open above fullscreen mpv on its current Space.
-  - Modals are now prewarmed on macOS and Windows so shortcuts open them promptly, and Windows keeps the hidden modal responsive between sessions.
-- **Wayland File Drag-and-Drop**
-  - Fixed dragging subtitle and video files from file managers like Thunar onto the overlay on native Wayland; dropped files are now resolved and sent to mpv.
-- **Windows Mouse Lag**
-  - Fixed system-wide mouse lag while SubMiner is running on Windows, caused by a global mouse hook and blocking window lookups during click-through tracking.
-- **Mining Clip Accuracy**
-  - Fixed mined audio and animated image clips sometimes capturing the wrong subtitle line when audio extraction was slow. The clip range is now locked in at the moment of lookup, so audio and image clips always match.
-- **Linux Notifications**
-  - Character dictionary progress notifications on Linux now update in place instead of flickering off and back on with every status change.
-- **Stats Delete Performance**
-  - Fixed stats deletes freezing the dashboard; deletes now reliably run off the main thread, with automatic retry if the delete worker crashes.
-  - Deletes, library merges/moves, and AniList reassignments are now much faster because totals are updated incrementally instead of rebuilt from scratch, and no longer erase lifetime totals older than the recent session history.
-  - Session deletes on large libraries dropped from minutes to milliseconds.
 
-### Docs
-- **Feature Demos Page**
-  - Hidden the unfinished feature demos page from the documentation sidebar; it's still reachable by direct URL.
+- **Jellyfin**:
+  - Playback, subtitles, artwork, and remote control now authenticate with an `ApiKey` parameter instead of legacy headers, so Jellyfin 12 works correctly even with legacy authorization disabled.
+  - "Play on SubMiner" no longer silently drops the connection after about a minute on Jellyfin 12.
+  - Casting now honors your configured mpv executable path, so playback works and portable plugins are detected correctly when mpv isn't on PATH.
+  - The "now playing" bar clears when you close or finish a cast video instead of running to the end of the episode.
+  - Anki cards mined from Jellyfin now get the real episode title in the misc info field instead of "Unknown media".
+  - Jellyfin streams no longer leak URL-derived titles or credential-bearing URLs into metadata, Anki fields, Discord presence, stats, or AniList lookups; previously cached data that had credentials in it is cleaned up automatically.
+
+- **Anki & Mining**:
+  - Word audio now reads from its own configured field (`ankiConnect.fields.wordAudio`) instead of the sentence-audio field, fixing animated word images that started moving immediately instead of on demand.
+  - Setting `ankiConnect.media.maxMediaDuration` to `0` for unlimited duration now also applies when mining from the stats dashboard, matching overlay mining.
+  - Closing the overlay while a media timing review is still loading now properly cancels setup, restores playback if the review had paused it, and cleans up the hidden preview player.
+  - Word-card sentence furigana now stays in sync with the full stats-search context and expanded timing-review selections, and clears stale readings automatically if regeneration fails.
+
+- **Settings**:
+  - AnkiConnect, Kiku, and Senren settings are now validated before use, with a warning and a safe default for anything invalid instead of a bad value reaching runtime.
+  - Settings marked as applying live now correctly avoid showing a restart warning, and mixed saves apply the live parts immediately while listing only the sections that actually need a restart.
+
+- **Overlay**:
+  - Clicking a subtitle sidebar cue no longer leaves Space bound to seeking back to it; Enter still seeks the focused cue, and Space keeps whatever playback action you've configured.
+  - Hyprland recovery dialogs now stay above SubMiner windows instead of being covered by overlay placement updates.
+  - Fixed a rare case on Linux where a delayed window-close callback could reopen the overlay after it was torn down.
+
+- **Stats**:
+  - Malformed or partly invalid resource IDs are now rejected before they can affect library mutations or cover-art backfills.
+  - Stats server port conflicts now surface as a status notification instead of crashing SubMiner, and startup/shutdown are more robust: concurrent startup requests share one attempt, stopping a background instance no longer disconnects an open dashboard, and shutdown no longer waits indefinitely on active requests.
+
+- **Subtitle Sidebar Gap Follow**: The subtitle sidebar now stays near actual playback position during gaps in files where a cue starts at time zero.
+
+- **First Launch on macOS**: Fixed first launch exiting immediately when the SubMiner config directory didn't exist yet.
 
 ## What's Changed
 
-- feat(stats): add library entry merge and episode move by @ksyasuda in #190
-- fix(stats): stop counting duplicate typeset subtitle lines by @ksyasuda in #191
-- fix(media): tolerate slow MKV audio extraction by @ksyasuda in #195
-- fix(stats): subtract lifetime totals incrementally on delete by @ksyasuda in #196
-- fix(anki): snapshot mining media clip timing by @ksyasuda in #197
-- fix(notifications): replace Linux progress updates in place by @ksyasuda in #198
-- fix(overlay): support native Wayland file drag-and-drop by @ksyasuda in #199
-- fix(overlay): keep macOS modal windows on fullscreen Spaces by @ksyasuda in #200
-- fix(overlay): prevent Windows mouse lag during click-through tracking by @ksyasuda in #201
+- feat(sidebar): add dialogue selection and copying by @ksyasuda in #238
+- feat(subtitles): add local Japanese subtitle generation by @ksyasuda in #240
+- perf(stats): use compressed incremental snapshot transfers by @ksyasuda in #241
+- fix(startup): create config directory before singleton lock by @ksyasuda in #242
+- feat(launcher): bundle Bun and use it across all launchers by @ksyasuda in #243
+- build(release): reduce package size and report release sizes by @ksyasuda in #244
+- fix(overlay): keep Hyprland recovery dialogs above overlays by @ksyasuda in #245
+- feat(overlay): discover unclaimed mpv key bindings by @ksyasuda in #246
+- fix(sidebar): preserve Space playback after cue seeking by @ksyasuda in #247
+- fix(jellyfin): fix jellyfin media metadata by @ksyasuda in #250
+- feat(jimaku): add live-action subtitle search by @ksyasuda in #251
+- feat(stats): add TMDB metadata for live-action dramas in the Library by @ksyasuda in #252
+- feat(stats): separate YouTube channels in the Library by @ksyasuda in #253
+- feat(mining): add a screenshot frame picker to media review by @aalhendi in #254
+- fix(config): align live save feedback with hot reload policy by @ksyasuda in #255
+- fix(anki): separate word audio mapping for animation sync by @ksyasuda in #256
+- fix(config): validate AnkiConnect and field grouping settings by @ksyasuda in #257
+- fix(anki): honor unlimited duration in stats mining by @ksyasuda in #258
+- fix(stats): reject malformed resource IDs before mutations by @ksyasuda in #259
+- fix(stats): harden server lifecycle and verify compiled runtime by @ksyasuda in #261
+- fix(overlay): cancel pending window transitions and timing reviews by @ksyasuda in #262
+- fix(stats): restrict local requests and serve the dashboard over HTTP by @ksyasuda in #263
+- fix(jellyfin): support modern authentication by @ksyasuda in #264
+- feat(overlay): add optional subtitle selection modal by @ksyasuda in #265
+- fix(jellyfin): respect Windows mpv configuration when casting by @aalhendi in #267
+- fix(anki): regenerate sentence furigana from the final sentence by @ksyasuda in #268
+
+## New Contributors
+
+- @aalhendi made their first contribution in #254
 
 ## Installation
 
@@ -57,6 +130,9 @@ See the README and docs/installation guide for full setup steps.
 - Linux: `SubMiner.AppImage`
 - macOS: `SubMiner-*.dmg` and `SubMiner-*.zip`
 - Windows: `SubMiner-*.exe` and `SubMiner-*-win.zip`
-- Optional extras: `subminer-assets.tar.gz` and the `subminer` launcher
+- Optional extras: `subminer-assets.tar.gz`, the `subminer` launcher, and the Windows `subminer.cmd` launcher
+- Bun corresponding source: `bun-v1.3.5-source.tar.gz` and its `.sha256` file
 
-Note: the `subminer` wrapper script uses Bun (`#!/usr/bin/env bun`), so `bun` must be installed and on `PATH`.
+Both launcher downloads use Bun included with the SubMiner app. Download `subminer` on Linux or macOS and `subminer.cmd` on Windows.
+
+The app bundles an unmodified Bun 1.3.5 runtime. Bun is MIT licensed and statically links JavaScriptCore (LGPL 2.0) and TinyCC (LGPL 2.1). License texts and third-party notices ship inside the app under `resources/bun/licenses`, and the source archive above contains the matching Bun, WebKit, and dependency sources for relinking.
diff --git a/release/release-notes.md b/release/release-notes.md
new file mode 100644
index 00000000..93dcd0ef
--- /dev/null
+++ b/release/release-notes.md
@@ -0,0 +1,159 @@
+## Highlights
+### Added
+- **Japanese Subtitle Generation**:
+  - Generate Japanese SRT subtitles locally with whisper.cpp. Start it from a new modal (Ctrl+Shift+G), from the generate button in an empty subtitle sidebar, or with `subminer generate-subs`.
+  - Generation shows progress, can be cancelled, and loads the finished subtitles into mpv automatically.
+  - Pick an official multilingual Whisper model, including quantized variants, with size and accuracy guidance. You can download it in the app or point Settings at a model you already have.
+  - `large-v3-turbo` is recommended when CUDA support is detected, and `small` otherwise.
+  - whisper-cli, ffmpeg, and ffprobe are found on PATH unless you override them. SubMiner names any missing tools before a download starts.
+  - An optional "Focus on spoken dialogue" mode uses a separately downloaded Silero VAD model. It keeps audible sections it is unsure about, so dialogue under music is not dropped, but songs may also be transcribed.
+  - Long passages are split near speech starts or quiet pauses to reduce subtitles that appear too early. When an eligible embedded or external subtitle track is loaded in mpv, it guides the split points.
+  - Each passage runs in a fresh Whisper process, which prevents repeated-character output.
+- **Subtitle Selection Modal**:
+  - An optional modal for choosing primary and secondary mpv subtitle tracks.
+  - Turn it on in Settings under Behavior, then press g followed by s to open it. Turning it off restores mpv's own subtitle selection binding.
+  - Single-key actions take priority over configured key sequence prefixes.
+  - Conflicting sequences are disabled with a warning, and the existing y commands stay reserved.
+- **Subtitle Sidebar Copy**:
+  - Select dialogue across several sidebar rows and copy it without timestamps using Ctrl/Cmd+C or the Copy button.
+  - Selecting text does not seek playback and does not require mining a card.
+- **Media Timing Review Screenshot Picker**:
+  - Choose the still screenshot separately from the audio range, with a live preview and its own time slider.
+  - Step through decoded frames one at a time to get the exact frame you want.
+  - Works with local video and with seekable remote streams such as Jellyfin.
+- **mpv Keybindings in the Overlay**:
+  - The overlay now picks up keyboard bindings from mpv defaults, `input.conf`, and loaded scripts when they do not conflict with SubMiner.
+  - SubMiner controls and bindings you explicitly disabled take precedence.
+  - These bindings apply only to the current session and are not listed in the help menu.
+- **Jimaku Live Action Search**: The Jimaku modal has new Anime and Live action tabs, so you can search Jimaku's live action catalogue as well as anime. Use Arrow Left and Arrow Right to switch tabs.
+- **TMDB Live-Action Library**:
+  - Live-action dramas and movies in the stats Library now get posters, synopses, and titles from TMDB.
+  - Release builds include a project key. Setting `tmdb.apiKey` or `tmdb.apiKeyCommand` overrides it, and one of them is required when running from source.
+  - Titles that AniList cannot match are looked up on TMDB automatically when the parsed filename exactly matches a Japanese live-action title. For everything else, use the new **Link to TMDB** action.
+  - Entries linked to the same TMDB title merge into one card, and the Library kind selector has a new Live Action option.
+  - If a replacement download fails during provider reassignment, the previous link and artwork are kept. Merges and sync keep AniList and TMDB identities separate, and the merge dialog explains mixed selections instead of failing.
+- **YouTube Library Kind**:
+  - YouTube channels are now their own Library media kind. Existing channel entries migrate automatically, and viewing history and manual video assignments are unchanged.
+  - New All Titles, Anime, and YouTube Library filters.
+  - Channels are excluded from AniList matching, season repair, and duplicate recommendations.
+  - Merges and video moves can no longer combine an anime entry with a YouTube channel.
+
+### Changed
+- **Launcher Uses Bundled Bun**:
+  - Every installed and downloadable launcher now runs on the Bun runtime that ships with SubMiner. A system Bun is no longer needed.
+  - Recognized legacy launchers migrate automatically.
+  - Windows gets a `subminer.cmd` launcher download.
+  - First-run setup is reduced to one optional launcher control. Runtime repair guidance appears only when it is needed.
+- **Faster Sync Transfers**:
+  - Sync between compatible macOS and Linux machines now uses compressed, incremental rsync transfers.
+  - The last snapshot received from each peer is cached, which reduces traffic on later syncs.
+  - Machines without a compatible rsync, including Windows, fall back to compressed scp.
+  - Older peers still work without the upload cache.
+  - Transfers abort after 30 minutes.
+- **Stats Server Request Safety**:
+  - The stats server now accepts loopback hosts only and rejects requests from browser origins other than its own.
+  - Requests that change data must send an `application/json` body. Scripts that POST to the server need to set a JSON content type.
+  - The in-app stats overlay now loads from the local server, so it gets the same protection.
+  - Dashboards served through a reverse proxy or Tailscale Serve are no longer supported.
+- **Smaller Downloads**:
+  - Installers and unpacked apps are smaller. Demo media, source maps, TypeScript sources, test fixtures, and unused Koffi binaries are no longer packaged.
+  - All windows now share one Japanese UI font.
+  - Release builds publish package size reports that compare against the previous release.
+- **Bundled Yomitan**: Updated with upstream Yomitan 26.9.8 changes, including historical Japanese kana transformations, Ukrainian language support, and improvements to Anki duplicate searches and audio retrieval.
+
+### Fixed
+- **Jellyfin 12 Compatibility**:
+  - Playback, subtitle, artwork, and remote-control requests now authenticate with the `ApiKey` query parameter, so the integration works on Jellyfin 12, where legacy authorization is off by default.
+  - "Play on SubMiner" stays available. The cast connection now answers keep-alive requests and reconnects when the server stops responding, instead of silently dying after about a minute.
+  - The Jellyfin "now playing" bar clears when you close or finish a cast video instead of running on to the end of the episode.
+  - Cards mined during Jellyfin playback get the episode title in the misc info field again instead of "Unknown media".
+- **Jellyfin Privacy and Playback**:
+  - Jellyfin streams no longer leak titles taken from the stream URL, or stream URLs that contain credentials, into metadata lookups, Anki source fields, Discord presence, stats, or AniList retries.
+  - Previously cached metadata that contained credentials is cleaned up. Watch history and library assignments are not touched.
+  - Jellyfin playback and casting now use your configured mpv executable, so they work when mpv is installed outside PATH. Portable plugins next to that executable are detected.
+- **Anki Mining**:
+  - New `ankiConnect.fields.wordAudio` setting reads word audio separately from the sentence audio field. This fixes animated images that started moving immediately when `fields.audio` pointed to `SentenceAudio`. Existing animated images need to be regenerated to pick up the fix.
+  - Sentence furigana on word cards stays in sync with the full stats-search context and with expanded timing review selections. Stale readings are cleared if regeneration fails.
+  - Closing the overlay while media timing review is still loading now cancels the review, resumes playback if the review paused it, and cleans up the hidden preview player.
+  - `ankiConnect.media.maxMediaDuration: 0` now means unlimited when mining from the stats dashboard, matching overlay mining.
+  - Invalid AnkiConnect, Kiku, and Senren settings are now rejected with a warning and fall back to defaults.
+- **Stats Server Stability**:
+  - A port conflict is now reported in a status notification instead of crashing SubMiner.
+  - Simultaneous startup requests share one server start. Stopping the background server no longer disconnects dashboards open in the foreground.
+  - Shutdown waits only a limited time for active requests to finish.
+  - Malformed resource IDs, and ID lists with any invalid entries, are rejected before Library changes or cover backfills run.
+- **Subtitle Sidebar**:
+  - Clicking a cue no longer leaves the row focused, and Space no longer seeks back to a focused cue. Enter still seeks to the focused cue, and Space keeps its configured playback action.
+  - The sidebar stays near the current playback position during gaps when the subtitle file has a cue that starts at zero.
+- **Settings Save Feedback**:
+  - Settings marked LIVE no longer show false restart warnings, including for notifications and subtitle generation.
+  - When a save mixes live and restart-only changes, the live changes apply right away and only the changed sections that need a restart are listed.
+- **Overlay Windows**:
+  - On Hyprland, recovery dialogs stay above SubMiner windows so overlay placement updates no longer cover their Wait and Close buttons.
+  - On Linux, a delayed close callback during teardown can no longer reopen the overlay.
+- **First Launch on macOS**: SubMiner no longer exits on first launch when the config directory does not exist yet.
+
+### Docs
+- **Launcher**: Documented the launcher install that uses the bundled runtime, migration from legacy launchers, package-managed updates, and the bundled Bun runtime's MIT and LGPL notices. The AUR package installs these notices under `/usr/share/licenses/subminer-bin`, and they are also included in `subminer-assets.tar.gz`.
+- **Subtitle Generation**: Documented model choice, VAD behavior, splitting guided by a reference track, fallback behavior, and known limits.
+- **Subtitle Selection**: Documented the subtitle selector setting, its shortcut override, and the primary and secondary track controls.
+- **Settings**: Clarified save feedback for live settings, warnings for saves that mix live and restart-only changes, and how subtitle generation settings reload.
+- **Jellyfin**:
+  - Clarified that Windows mpv playback and Jellyfin casting can use a configured executable path instead of PATH.
+  - Documented how Jellyfin media titles and stats identities keep stream credentials out of metadata.
+- **Stats Library**:
+  - Documented TMDB linking, provider reassignment, merge compatibility, and caching of the credential command's output.
+  - Documented YouTube channel filtering and video statistics in the Library.
+- **Mining**:
+  - Documented choosing the screenshot separately in media timing review.
+  - Documented the separate word audio field mapping, including that existing animated images need to be regenerated.
+- **Sync**: Documented compressed transfers, where the incremental sync cache is stored, and compatibility with older peers.
+
+## What's Changed
+
+- feat(sidebar): add dialogue selection and copying by @ksyasuda in #238
+- feat(subtitles): add local Japanese subtitle generation by @ksyasuda in #240
+- perf(stats): use compressed incremental snapshot transfers by @ksyasuda in #241
+- fix(startup): create config directory before singleton lock by @ksyasuda in #242
+- feat(launcher): bundle Bun and use it across all launchers by @ksyasuda in #243
+- build(release): reduce package size and report release sizes by @ksyasuda in #244
+- fix(overlay): keep Hyprland recovery dialogs above overlays by @ksyasuda in #245
+- feat(overlay): discover unclaimed mpv key bindings by @ksyasuda in #246
+- fix(sidebar): preserve Space playback after cue seeking by @ksyasuda in #247
+- fix(jellyfin): fix jellyfin media metadata by @ksyasuda in #250
+- feat(jimaku): add live-action subtitle search by @ksyasuda in #251
+- feat(stats): add TMDB metadata for live-action dramas in the Library by @ksyasuda in #252
+- feat(stats): separate YouTube channels in the Library by @ksyasuda in #253
+- feat(mining): add a screenshot frame picker to media review by @aalhendi in #254
+- fix(config): align live save feedback with hot reload policy by @ksyasuda in #255
+- fix(anki): separate word audio mapping for animation sync by @ksyasuda in #256
+- fix(config): validate AnkiConnect and field grouping settings by @ksyasuda in #257
+- fix(anki): honor unlimited duration in stats mining by @ksyasuda in #258
+- fix(stats): reject malformed resource IDs before mutations by @ksyasuda in #259
+- fix(stats): harden server lifecycle and verify compiled runtime by @ksyasuda in #261
+- fix(overlay): cancel pending window transitions and timing reviews by @ksyasuda in #262
+- fix(stats): restrict local requests and serve the dashboard over HTTP by @ksyasuda in #263
+- fix(jellyfin): support modern authentication by @ksyasuda in #264
+- feat(overlay): add optional subtitle selection modal by @ksyasuda in #265
+- fix(jellyfin): respect Windows mpv configuration when casting by @aalhendi in #267
+- fix(anki): regenerate sentence furigana from the final sentence by @ksyasuda in #268
+
+## New Contributors
+
+- @aalhendi made their first contribution in #254
+
+## Installation
+
+See the README and docs/installation guide for full setup steps.
+
+## Assets
+
+- Linux: `SubMiner.AppImage`
+- macOS: `SubMiner-*.dmg` and `SubMiner-*.zip`
+- Windows: `SubMiner-*.exe` and `SubMiner-*-win.zip`
+- Optional extras: `subminer-assets.tar.gz`, the `subminer` launcher, and the Windows `subminer.cmd` launcher
+- Bun corresponding source: `bun-v1.3.5-source.tar.gz` and its `.sha256` file
+
+Both launcher downloads use Bun included with the SubMiner app. Download `subminer` on Linux or macOS and `subminer.cmd` on Windows.
+
+The app bundles an unmodified Bun 1.3.5 runtime. Bun is MIT licensed and statically links JavaScriptCore (LGPL 2.0) and TinyCC (LGPL 2.1). License texts and third-party notices ship inside the app under `resources/bun/licenses`, and the source archive above contains the matching Bun, WebKit, and dependency sources for relinking.
diff --git a/resources/bun/licenses/Bun-LICENSE.md b/resources/bun/licenses/Bun-LICENSE.md
new file mode 100644
index 00000000..df8d965c
--- /dev/null
+++ b/resources/bun/licenses/Bun-LICENSE.md
@@ -0,0 +1,73 @@
+Bun itself is MIT-licensed.
+
+## JavaScriptCore
+
+Bun statically links JavaScriptCore (and WebKit) which is LGPL-2 licensed. WebCore files from WebKit are also licensed under LGPL2. Per LGPL2:
+
+> (1) If you statically link against an LGPL’d library, you must also provide your application in an object (not necessarily source) format, so that a user has the opportunity to modify the library and relink the application.
+
+You can find the patched version of WebKit used by Bun here: <https://github.com/oven-sh/webkit>. If you would like to relink Bun with changes:
+
+- `git submodule update --init --recursive`
+- `make jsc`
+- `zig build`
+
+This compiles JavaScriptCore, compiles Bun’s `.cpp` bindings for JavaScriptCore (which are the object files using JavaScriptCore) and outputs a new `bun` binary with your changes.
+
+## Linked libraries
+
+Bun statically links these libraries:
+
+| Library | License |
+|---------|---------|
+| [`boringssl`](https://boringssl.googlesource.com/boringssl/) | [several licenses](https://boringssl.googlesource.com/boringssl/+/refs/heads/master/LICENSE) |
+| [`brotli`](https://github.com/google/brotli) | MIT |
+| [`libarchive`](https://github.com/libarchive/libarchive) | [several licenses](https://github.com/libarchive/libarchive/blob/master/COPYING) |
+| [`lol-html`](https://github.com/cloudflare/lol-html/tree/master/c-api) | BSD 3-Clause |
+| [`mimalloc`](https://github.com/microsoft/mimalloc) | MIT |
+| [`picohttp`](https://github.com/h2o/picohttpparser) | dual-licensed under the Perl License or the MIT License |
+| [`zstd`](https://github.com/facebook/zstd) | dual-licensed under the BSD License or GPLv2 license |
+| [`simdutf`](https://github.com/simdutf/simdutf) | Apache 2.0 |
+| [`tinycc`](https://github.com/tinycc/tinycc) | LGPL v2.1 |
+| [`uSockets`](https://github.com/uNetworking/uSockets) | Apache 2.0 |
+| [`zlib-cloudflare`](https://github.com/cloudflare/zlib) | zlib |
+| [`c-ares`](https://github.com/c-ares/c-ares) | MIT licensed |
+| [`libicu`](https://github.com/unicode-org/icu) 72 | [license here](https://github.com/unicode-org/icu/blob/main/icu4c/LICENSE) |
+| [`libbase64`](https://github.com/aklomp/base64/blob/master/LICENSE) | BSD 2-Clause |
+| [`libuv`](https://github.com/libuv/libuv) (on Windows) | MIT |
+| [`libdeflate`](https://github.com/ebiggers/libdeflate) | MIT |
+| A fork of [`uWebsockets`](https://github.com/jarred-sumner/uwebsockets) | Apache 2.0 licensed |
+| Parts of [Tigerbeetle's IO code](https://github.com/tigerbeetle/tigerbeetle/blob/532c8b70b9142c17e07737ab6d3da68d7500cbca/src/io/windows.zig#L1) | Apache 2.0 licensed |
+
+## Polyfills
+
+For compatibility reasons, the following packages are embedded into Bun's binary and injected if imported.
+
+| Package | License |
+|---------|---------|
+| [`assert`](https://npmjs.com/package/assert) | MIT |
+| [`browserify-zlib`](https://npmjs.com/package/browserify-zlib) | MIT |
+| [`buffer`](https://npmjs.com/package/buffer) | MIT |
+| [`constants-browserify`](https://npmjs.com/package/constants-browserify) | MIT |
+| [`crypto-browserify`](https://npmjs.com/package/crypto-browserify) | MIT |
+| [`domain-browser`](https://npmjs.com/package/domain-browser) | MIT |
+| [`events`](https://npmjs.com/package/events) | MIT |
+| [`https-browserify`](https://npmjs.com/package/https-browserify) | MIT |
+| [`os-browserify`](https://npmjs.com/package/os-browserify) | MIT |
+| [`path-browserify`](https://npmjs.com/package/path-browserify) | MIT |
+| [`process`](https://npmjs.com/package/process) | MIT |
+| [`punycode`](https://npmjs.com/package/punycode) | MIT |
+| [`querystring-es3`](https://npmjs.com/package/querystring-es3) | MIT |
+| [`stream-browserify`](https://npmjs.com/package/stream-browserify) | MIT |
+| [`stream-http`](https://npmjs.com/package/stream-http) | MIT |
+| [`string_decoder`](https://npmjs.com/package/string_decoder) | MIT |
+| [`timers-browserify`](https://npmjs.com/package/timers-browserify) | MIT |
+| [`tty-browserify`](https://npmjs.com/package/tty-browserify) | MIT |
+| [`url`](https://npmjs.com/package/url) | MIT |
+| [`util`](https://npmjs.com/package/util) | MIT |
+| [`vm-browserify`](https://npmjs.com/package/vm-browserify) | MIT |
+
+## Additional credits
+
+- Bun's JS transpiler, CSS lexer, and Node.js module resolver source code is a Zig port of [@evanw](https://github.com/evanw)’s [esbuild](https://github.com/evanw/esbuild) project.
+- Credit to [@kipply](https://github.com/kipply) for the name "Bun"!
diff --git a/resources/bun/licenses/LGPL-2.0.txt b/resources/bun/licenses/LGPL-2.0.txt
new file mode 100644
index 00000000..87c4a33d
--- /dev/null
+++ b/resources/bun/licenses/LGPL-2.0.txt
@@ -0,0 +1,488 @@
+
+
+NOTE! The LGPL below is copyrighted by the Free Software Foundation, but 
+the instance of code that it refers to (the kde libraries) are copyrighted 
+by the authors who actually wrote it.
+				   
+---------------------------------------------------------------------------
+		  GNU LIBRARY GENERAL PUBLIC LICENSE
+		       Version 2, June 1991
+
+ Copyright (C) 1991 Free Software Foundation, Inc.
+                    51 Franklin Street, Fifth Floor
+                    Boston, MA 02110-1301, USA.
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+[This is the first released version of the library GPL.  It is
+ numbered 2 because it goes with version 2 of the ordinary GPL.]
+
+			    Preamble
+
+  The licenses for most software are designed to take away your
+freedom to share and change it.  By contrast, the GNU General Public
+Licenses are intended to guarantee your freedom to share and change
+free software--to make sure the software is free for all its users.
+
+  This license, the Library General Public License, applies to some
+specially designated Free Software Foundation software, and to any
+other libraries whose authors decide to use it.  You can use it for
+your libraries, too.
+
+  When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+this service if you wish), that you receive source code or can get it
+if you want it, that you can change the software or use pieces of it
+in new free programs; and that you know you can do these things.
+
+  To protect your rights, we need to make restrictions that forbid
+anyone to deny you these rights or to ask you to surrender the rights.
+These restrictions translate to certain responsibilities for you if
+you distribute copies of the library, or if you modify it.
+
+  For example, if you distribute copies of the library, whether gratis
+or for a fee, you must give the recipients all the rights that we gave
+you.  You must make sure that they, too, receive or can get the source
+code.  If you link a program with the library, you must provide
+complete object files to the recipients so that they can relink them
+with the library, after making changes to the library and recompiling
+it.  And you must show them these terms so they know their rights.
+
+  Our method of protecting your rights has two steps: (1) copyright
+the library, and (2) offer you this license which gives you legal
+permission to copy, distribute and/or modify the library.
+
+  Also, for each distributor's protection, we want to make certain
+that everyone understands that there is no warranty for this free
+library.  If the library is modified by someone else and passed on, we
+want its recipients to know that what they have is not the original
+version, so that any problems introduced by others will not reflect on
+the original authors' reputations.
+
+  Finally, any free program is threatened constantly by software
+patents.  We wish to avoid the danger that companies distributing free
+software will individually obtain patent licenses, thus in effect
+transforming the program into proprietary software.  To prevent this,
+we have made it clear that any patent must be licensed for everyone's
+free use or not licensed at all.
+
+  Most GNU software, including some libraries, is covered by the ordinary
+GNU General Public License, which was designed for utility programs.  This
+license, the GNU Library General Public License, applies to certain
+designated libraries.  This license is quite different from the ordinary
+one; be sure to read it in full, and don't assume that anything in it is
+the same as in the ordinary license.
+
+  The reason we have a separate public license for some libraries is that
+they blur the distinction we usually make between modifying or adding to a
+program and simply using it.  Linking a program with a library, without
+changing the library, is in some sense simply using the library, and is
+analogous to running a utility program or application program.  However, in
+a textual and legal sense, the linked executable is a combined work, a
+derivative of the original library, and the ordinary General Public License
+treats it as such.
+
+  Because of this blurred distinction, using the ordinary General
+Public License for libraries did not effectively promote software
+sharing, because most developers did not use the libraries.  We
+concluded that weaker conditions might promote sharing better.
+
+  However, unrestricted linking of non-free programs would deprive the
+users of those programs of all benefit from the free status of the
+libraries themselves.  This Library General Public License is intended to
+permit developers of non-free programs to use free libraries, while
+preserving your freedom as a user of such programs to change the free
+libraries that are incorporated in them.  (We have not seen how to achieve
+this as regards changes in header files, but we have achieved it as regards
+changes in the actual functions of the Library.)  The hope is that this
+will lead to faster development of free libraries.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.  Pay close attention to the difference between a
+"work based on the library" and a "work that uses the library".  The
+former contains code derived from the library, while the latter only
+works together with the library.
+
+  Note that it is possible for a library to be covered by the ordinary
+General Public License rather than by this special one.
+
+		  GNU LIBRARY GENERAL PUBLIC LICENSE
+   TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+
+  0. This License Agreement applies to any software library which
+contains a notice placed by the copyright holder or other authorized
+party saying it may be distributed under the terms of this Library
+General Public License (also called "this License").  Each licensee is
+addressed as "you".
+
+  A "library" means a collection of software functions and/or data
+prepared so as to be conveniently linked with application programs
+(which use some of those functions and data) to form executables.
+
+  The "Library", below, refers to any such software library or work
+which has been distributed under these terms.  A "work based on the
+Library" means either the Library or any derivative work under
+copyright law: that is to say, a work containing the Library or a
+portion of it, either verbatim or with modifications and/or translated
+straightforwardly into another language.  (Hereinafter, translation is
+included without limitation in the term "modification".)
+
+  "Source code" for a work means the preferred form of the work for
+making modifications to it.  For a library, complete source code means
+all the source code for all modules it contains, plus any associated
+interface definition files, plus the scripts used to control compilation
+and installation of the library.
+
+  Activities other than copying, distribution and modification are not
+covered by this License; they are outside its scope.  The act of
+running a program using the Library is not restricted, and output from
+such a program is covered only if its contents constitute a work based
+on the Library (independent of the use of the Library in a tool for
+writing it).  Whether that is true depends on what the Library does
+and what the program that uses the Library does.
+  
+  1. You may copy and distribute verbatim copies of the Library's
+complete source code as you receive it, in any medium, provided that
+you conspicuously and appropriately publish on each copy an
+appropriate copyright notice and disclaimer of warranty; keep intact
+all the notices that refer to this License and to the absence of any
+warranty; and distribute a copy of this License along with the
+Library.
+
+  You may charge a fee for the physical act of transferring a copy,
+and you may at your option offer warranty protection in exchange for a
+fee.
+
+  2. You may modify your copy or copies of the Library or any portion
+of it, thus forming a work based on the Library, and copy and
+distribute such modifications or work under the terms of Section 1
+above, provided that you also meet all of these conditions:
+
+    a) The modified work must itself be a software library.
+
+    b) You must cause the files modified to carry prominent notices
+    stating that you changed the files and the date of any change.
+
+    c) You must cause the whole of the work to be licensed at no
+    charge to all third parties under the terms of this License.
+
+    d) If a facility in the modified Library refers to a function or a
+    table of data to be supplied by an application program that uses
+    the facility, other than as an argument passed when the facility
+    is invoked, then you must make a good faith effort to ensure that,
+    in the event an application does not supply such function or
+    table, the facility still operates, and performs whatever part of
+    its purpose remains meaningful.
+
+    (For example, a function in a library to compute square roots has
+    a purpose that is entirely well-defined independent of the
+    application.  Therefore, Subsection 2d requires that any
+    application-supplied function or table used by this function must
+    be optional: if the application does not supply it, the square
+    root function must still compute square roots.)
+
+These requirements apply to the modified work as a whole.  If
+identifiable sections of that work are not derived from the Library,
+and can be reasonably considered independent and separate works in
+themselves, then this License, and its terms, do not apply to those
+sections when you distribute them as separate works.  But when you
+distribute the same sections as part of a whole which is a work based
+on the Library, the distribution of the whole must be on the terms of
+this License, whose permissions for other licensees extend to the
+entire whole, and thus to each and every part regardless of who wrote
+it.
+
+Thus, it is not the intent of this section to claim rights or contest
+your rights to work written entirely by you; rather, the intent is to
+exercise the right to control the distribution of derivative or
+collective works based on the Library.
+
+In addition, mere aggregation of another work not based on the Library
+with the Library (or with a work based on the Library) on a volume of
+a storage or distribution medium does not bring the other work under
+the scope of this License.
+
+  3. You may opt to apply the terms of the ordinary GNU General Public
+License instead of this License to a given copy of the Library.  To do
+this, you must alter all the notices that refer to this License, so
+that they refer to the ordinary GNU General Public License, version 2,
+instead of to this License.  (If a newer version than version 2 of the
+ordinary GNU General Public License has appeared, then you can specify
+that version instead if you wish.)  Do not make any other change in
+these notices.
+
+  Once this change is made in a given copy, it is irreversible for
+that copy, so the ordinary GNU General Public License applies to all
+subsequent copies and derivative works made from that copy.
+
+  This option is useful when you wish to copy part of the code of
+the Library into a program that is not a library.
+
+  4. You may copy and distribute the Library (or a portion or
+derivative of it, under Section 2) in object code or executable form
+under the terms of Sections 1 and 2 above provided that you accompany
+it with the complete corresponding machine-readable source code, which
+must be distributed under the terms of Sections 1 and 2 above on a
+medium customarily used for software interchange.
+
+  If distribution of object code is made by offering access to copy
+from a designated place, then offering equivalent access to copy the
+source code from the same place satisfies the requirement to
+distribute the source code, even though third parties are not
+compelled to copy the source along with the object code.
+
+  5. A program that contains no derivative of any portion of the
+Library, but is designed to work with the Library by being compiled or
+linked with it, is called a "work that uses the Library".  Such a
+work, in isolation, is not a derivative work of the Library, and
+therefore falls outside the scope of this License.
+
+  However, linking a "work that uses the Library" with the Library
+creates an executable that is a derivative of the Library (because it
+contains portions of the Library), rather than a "work that uses the
+library".  The executable is therefore covered by this License.
+Section 6 states terms for distribution of such executables.
+
+  When a "work that uses the Library" uses material from a header file
+that is part of the Library, the object code for the work may be a
+derivative work of the Library even though the source code is not.
+Whether this is true is especially significant if the work can be
+linked without the Library, or if the work is itself a library.  The
+threshold for this to be true is not precisely defined by law.
+
+  If such an object file uses only numerical parameters, data
+structure layouts and accessors, and small macros and small inline
+functions (ten lines or less in length), then the use of the object
+file is unrestricted, regardless of whether it is legally a derivative
+work.  (Executables containing this object code plus portions of the
+Library will still fall under Section 6.)
+
+  Otherwise, if the work is a derivative of the Library, you may
+distribute the object code for the work under the terms of Section 6.
+Any executables containing that work also fall under Section 6,
+whether or not they are linked directly with the Library itself.
+
+  6. As an exception to the Sections above, you may also compile or
+link a "work that uses the Library" with the Library to produce a
+work containing portions of the Library, and distribute that work
+under terms of your choice, provided that the terms permit
+modification of the work for the customer's own use and reverse
+engineering for debugging such modifications.
+
+  You must give prominent notice with each copy of the work that the
+Library is used in it and that the Library and its use are covered by
+this License.  You must supply a copy of this License.  If the work
+during execution displays copyright notices, you must include the
+copyright notice for the Library among them, as well as a reference
+directing the user to the copy of this License.  Also, you must do one
+of these things:
+
+    a) Accompany the work with the complete corresponding
+    machine-readable source code for the Library including whatever
+    changes were used in the work (which must be distributed under
+    Sections 1 and 2 above); and, if the work is an executable linked
+    with the Library, with the complete machine-readable "work that
+    uses the Library", as object code and/or source code, so that the
+    user can modify the Library and then relink to produce a modified
+    executable containing the modified Library.  (It is understood
+    that the user who changes the contents of definitions files in the
+    Library will not necessarily be able to recompile the application
+    to use the modified definitions.)
+
+    b) Accompany the work with a written offer, valid for at
+    least three years, to give the same user the materials
+    specified in Subsection 6a, above, for a charge no more
+    than the cost of performing this distribution.
+
+    c) If distribution of the work is made by offering access to copy
+    from a designated place, offer equivalent access to copy the above
+    specified materials from the same place.
+
+    d) Verify that the user has already received a copy of these
+    materials or that you have already sent this user a copy.
+
+  For an executable, the required form of the "work that uses the
+Library" must include any data and utility programs needed for
+reproducing the executable from it.  However, as a special exception,
+the source code distributed need not include anything that is normally
+distributed (in either source or binary form) with the major
+components (compiler, kernel, and so on) of the operating system on
+which the executable runs, unless that component itself accompanies
+the executable.
+
+  It may happen that this requirement contradicts the license
+restrictions of other proprietary libraries that do not normally
+accompany the operating system.  Such a contradiction means you cannot
+use both them and the Library together in an executable that you
+distribute.
+
+  7. You may place library facilities that are a work based on the
+Library side-by-side in a single library together with other library
+facilities not covered by this License, and distribute such a combined
+library, provided that the separate distribution of the work based on
+the Library and of the other library facilities is otherwise
+permitted, and provided that you do these two things:
+
+    a) Accompany the combined library with a copy of the same work
+    based on the Library, uncombined with any other library
+    facilities.  This must be distributed under the terms of the
+    Sections above.
+
+    b) Give prominent notice with the combined library of the fact
+    that part of it is a work based on the Library, and explaining
+    where to find the accompanying uncombined form of the same work.
+
+  8. You may not copy, modify, sublicense, link with, or distribute
+the Library except as expressly provided under this License.  Any
+attempt otherwise to copy, modify, sublicense, link with, or
+distribute the Library is void, and will automatically terminate your
+rights under this License.  However, parties who have received copies,
+or rights, from you under this License will not have their licenses
+terminated so long as such parties remain in full compliance.
+
+  9. You are not required to accept this License, since you have not
+signed it.  However, nothing else grants you permission to modify or
+distribute the Library or its derivative works.  These actions are
+prohibited by law if you do not accept this License.  Therefore, by
+modifying or distributing the Library (or any work based on the
+Library), you indicate your acceptance of this License to do so, and
+all its terms and conditions for copying, distributing or modifying
+the Library or works based on it.
+
+  10. Each time you redistribute the Library (or any work based on the
+Library), the recipient automatically receives a license from the
+original licensor to copy, distribute, link with or modify the Library
+subject to these terms and conditions.  You may not impose any further
+restrictions on the recipients' exercise of the rights granted herein.
+You are not responsible for enforcing compliance by third parties to
+this License.
+
+  11. If, as a consequence of a court judgment or allegation of patent
+infringement or for any other reason (not limited to patent issues),
+conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot
+distribute so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you
+may not distribute the Library at all.  For example, if a patent
+license would not permit royalty-free redistribution of the Library by
+all those who receive copies directly or indirectly through you, then
+the only way you could satisfy both it and this License would be to
+refrain entirely from distribution of the Library.
+
+If any portion of this section is held invalid or unenforceable under any
+particular circumstance, the balance of the section is intended to apply,
+and the section as a whole is intended to apply in other circumstances.
+
+It is not the purpose of this section to induce you to infringe any
+patents or other property right claims or to contest validity of any
+such claims; this section has the sole purpose of protecting the
+integrity of the free software distribution system which is
+implemented by public license practices.  Many people have made
+generous contributions to the wide range of software distributed
+through that system in reliance on consistent application of that
+system; it is up to the author/donor to decide if he or she is willing
+to distribute software through any other system and a licensee cannot
+impose that choice.
+
+This section is intended to make thoroughly clear what is believed to
+be a consequence of the rest of this License.
+
+  12. If the distribution and/or use of the Library is restricted in
+certain countries either by patents or by copyrighted interfaces, the
+original copyright holder who places the Library under this License may add
+an explicit geographical distribution limitation excluding those countries,
+so that distribution is permitted only in or among countries not thus
+excluded.  In such case, this License incorporates the limitation as if
+written in the body of this License.
+
+  13. The Free Software Foundation may publish revised and/or new
+versions of the Library General Public License from time to time.
+Such new versions will be similar in spirit to the present version,
+but may differ in detail to address new problems or concerns.
+
+Each version is given a distinguishing version number.  If the Library
+specifies a version number of this License which applies to it and
+"any later version", you have the option of following the terms and
+conditions either of that version or of any later version published by
+the Free Software Foundation.  If the Library does not specify a
+license version number, you may choose any version ever published by
+the Free Software Foundation.
+
+  14. If you wish to incorporate parts of the Library into other free
+programs whose distribution conditions are incompatible with these,
+write to the author to ask for permission.  For software which is
+copyrighted by the Free Software Foundation, write to the Free
+Software Foundation; we sometimes make exceptions for this.  Our
+decision will be guided by the two goals of preserving the free status
+of all derivatives of our free software and of promoting the sharing
+and reuse of software generally.
+
+			    NO WARRANTY
+
+  15. BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO
+WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW.
+EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR
+OTHER PARTIES PROVIDE THE LIBRARY "AS IS" WITHOUT WARRANTY OF ANY
+KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE
+LIBRARY IS WITH YOU.  SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME
+THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+  16. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
+WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY
+AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU
+FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR
+CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
+LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
+RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
+FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
+SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
+DAMAGES.
+
+		     END OF TERMS AND CONDITIONS
+           How to Apply These Terms to Your New Libraries
+
+  If you develop a new library, and you want it to be of the greatest
+possible use to the public, we recommend making it free software that
+everyone can redistribute and change.  You can do so by permitting
+redistribution under these terms (or, alternatively, under the terms of the
+ordinary General Public License).
+
+  To apply these terms, attach the following notices to the library.  It is
+safest to attach them to the start of each source file to most effectively
+convey the exclusion of warranty; and each file should have at least the
+"copyright" line and a pointer to where the full notice is found.
+
+    <one line to give the library's name and a brief idea of what it does.>
+    Copyright (C) <year>  <name of author>
+
+    This library is free software; you can redistribute it and/or
+    modify it under the terms of the GNU Lesser General Public
+    License as published by the Free Software Foundation; either
+    version 2 of the License, or (at your option) any later version.
+
+    This library is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+    Lesser General Public License for more details.
+
+    You should have received a copy of the GNU Lesser General Public
+    License along with this library; if not, write to the Free Software
+    Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
+
+Also add information on how to contact you by electronic and paper mail.
+
+You should also get your employer (if you work as a programmer) or your
+school, if any, to sign a "copyright disclaimer" for the library, if
+necessary.  Here is a sample; alter the names:
+
+  Yoyodyne, Inc., hereby disclaims all copyright interest in the
+  library `Frob' (a library for tweaking knobs) written by James Random Hacker.
+
+  <signature of Ty Coon>, 1 April 1990
+  Ty Coon, President of Vice
+
+That's all there is to it!
diff --git a/resources/bun/licenses/LGPL-2.1.txt b/resources/bun/licenses/LGPL-2.1.txt
new file mode 100644
index 00000000..223ede7d
--- /dev/null
+++ b/resources/bun/licenses/LGPL-2.1.txt
@@ -0,0 +1,504 @@
+		  GNU LESSER GENERAL PUBLIC LICENSE
+		       Version 2.1, February 1999
+
+ Copyright (C) 1991, 1999 Free Software Foundation, Inc.
+     59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+[This is the first released version of the Lesser GPL.  It also counts
+ as the successor of the GNU Library Public License, version 2, hence
+ the version number 2.1.]
+
+			    Preamble
+
+  The licenses for most software are designed to take away your
+freedom to share and change it.  By contrast, the GNU General Public
+Licenses are intended to guarantee your freedom to share and change
+free software--to make sure the software is free for all its users.
+
+  This license, the Lesser General Public License, applies to some
+specially designated software packages--typically libraries--of the
+Free Software Foundation and other authors who decide to use it.  You
+can use it too, but we suggest you first think carefully about whether
+this license or the ordinary General Public License is the better
+strategy to use in any particular case, based on the explanations below.
+
+  When we speak of free software, we are referring to freedom of use,
+not price.  Our General Public Licenses are designed to make sure that
+you have the freedom to distribute copies of free software (and charge
+for this service if you wish); that you receive source code or can get
+it if you want it; that you can change the software and use pieces of
+it in new free programs; and that you are informed that you can do
+these things.
+
+  To protect your rights, we need to make restrictions that forbid
+distributors to deny you these rights or to ask you to surrender these
+rights.  These restrictions translate to certain responsibilities for
+you if you distribute copies of the library or if you modify it.
+
+  For example, if you distribute copies of the library, whether gratis
+or for a fee, you must give the recipients all the rights that we gave
+you.  You must make sure that they, too, receive or can get the source
+code.  If you link other code with the library, you must provide
+complete object files to the recipients, so that they can relink them
+with the library after making changes to the library and recompiling
+it.  And you must show them these terms so they know their rights.
+
+  We protect your rights with a two-step method: (1) we copyright the
+library, and (2) we offer you this license, which gives you legal
+permission to copy, distribute and/or modify the library.
+
+  To protect each distributor, we want to make it very clear that
+there is no warranty for the free library.  Also, if the library is
+modified by someone else and passed on, the recipients should know
+that what they have is not the original version, so that the original
+author's reputation will not be affected by problems that might be
+introduced by others.
+
+  Finally, software patents pose a constant threat to the existence of
+any free program.  We wish to make sure that a company cannot
+effectively restrict the users of a free program by obtaining a
+restrictive license from a patent holder.  Therefore, we insist that
+any patent license obtained for a version of the library must be
+consistent with the full freedom of use specified in this license.
+
+  Most GNU software, including some libraries, is covered by the
+ordinary GNU General Public License.  This license, the GNU Lesser
+General Public License, applies to certain designated libraries, and
+is quite different from the ordinary General Public License.  We use
+this license for certain libraries in order to permit linking those
+libraries into non-free programs.
+
+  When a program is linked with a library, whether statically or using
+a shared library, the combination of the two is legally speaking a
+combined work, a derivative of the original library.  The ordinary
+General Public License therefore permits such linking only if the
+entire combination fits its criteria of freedom.  The Lesser General
+Public License permits more lax criteria for linking other code with
+the library.
+
+  We call this license the "Lesser" General Public License because it
+does Less to protect the user's freedom than the ordinary General
+Public License.  It also provides other free software developers Less
+of an advantage over competing non-free programs.  These disadvantages
+are the reason we use the ordinary General Public License for many
+libraries.  However, the Lesser license provides advantages in certain
+special circumstances.
+
+  For example, on rare occasions, there may be a special need to
+encourage the widest possible use of a certain library, so that it becomes
+a de-facto standard.  To achieve this, non-free programs must be
+allowed to use the library.  A more frequent case is that a free
+library does the same job as widely used non-free libraries.  In this
+case, there is little to gain by limiting the free library to free
+software only, so we use the Lesser General Public License.
+
+  In other cases, permission to use a particular library in non-free
+programs enables a greater number of people to use a large body of
+free software.  For example, permission to use the GNU C Library in
+non-free programs enables many more people to use the whole GNU
+operating system, as well as its variant, the GNU/Linux operating
+system.
+
+  Although the Lesser General Public License is Less protective of the
+users' freedom, it does ensure that the user of a program that is
+linked with the Library has the freedom and the wherewithal to run
+that program using a modified version of the Library.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.  Pay close attention to the difference between a
+"work based on the library" and a "work that uses the library".  The
+former contains code derived from the library, whereas the latter must
+be combined with the library in order to run.
+
+		  GNU LESSER GENERAL PUBLIC LICENSE
+   TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+
+  0. This License Agreement applies to any software library or other
+program which contains a notice placed by the copyright holder or
+other authorized party saying it may be distributed under the terms of
+this Lesser General Public License (also called "this License").
+Each licensee is addressed as "you".
+
+  A "library" means a collection of software functions and/or data
+prepared so as to be conveniently linked with application programs
+(which use some of those functions and data) to form executables.
+
+  The "Library", below, refers to any such software library or work
+which has been distributed under these terms.  A "work based on the
+Library" means either the Library or any derivative work under
+copyright law: that is to say, a work containing the Library or a
+portion of it, either verbatim or with modifications and/or translated
+straightforwardly into another language.  (Hereinafter, translation is
+included without limitation in the term "modification".)
+
+  "Source code" for a work means the preferred form of the work for
+making modifications to it.  For a library, complete source code means
+all the source code for all modules it contains, plus any associated
+interface definition files, plus the scripts used to control compilation
+and installation of the library.
+
+  Activities other than copying, distribution and modification are not
+covered by this License; they are outside its scope.  The act of
+running a program using the Library is not restricted, and output from
+such a program is covered only if its contents constitute a work based
+on the Library (independent of the use of the Library in a tool for
+writing it).  Whether that is true depends on what the Library does
+and what the program that uses the Library does.
+  
+  1. You may copy and distribute verbatim copies of the Library's
+complete source code as you receive it, in any medium, provided that
+you conspicuously and appropriately publish on each copy an
+appropriate copyright notice and disclaimer of warranty; keep intact
+all the notices that refer to this License and to the absence of any
+warranty; and distribute a copy of this License along with the
+Library.
+
+  You may charge a fee for the physical act of transferring a copy,
+and you may at your option offer warranty protection in exchange for a
+fee.
+
+  2. You may modify your copy or copies of the Library or any portion
+of it, thus forming a work based on the Library, and copy and
+distribute such modifications or work under the terms of Section 1
+above, provided that you also meet all of these conditions:
+
+    a) The modified work must itself be a software library.
+
+    b) You must cause the files modified to carry prominent notices
+    stating that you changed the files and the date of any change.
+
+    c) You must cause the whole of the work to be licensed at no
+    charge to all third parties under the terms of this License.
+
+    d) If a facility in the modified Library refers to a function or a
+    table of data to be supplied by an application program that uses
+    the facility, other than as an argument passed when the facility
+    is invoked, then you must make a good faith effort to ensure that,
+    in the event an application does not supply such function or
+    table, the facility still operates, and performs whatever part of
+    its purpose remains meaningful.
+
+    (For example, a function in a library to compute square roots has
+    a purpose that is entirely well-defined independent of the
+    application.  Therefore, Subsection 2d requires that any
+    application-supplied function or table used by this function must
+    be optional: if the application does not supply it, the square
+    root function must still compute square roots.)
+
+These requirements apply to the modified work as a whole.  If
+identifiable sections of that work are not derived from the Library,
+and can be reasonably considered independent and separate works in
+themselves, then this License, and its terms, do not apply to those
+sections when you distribute them as separate works.  But when you
+distribute the same sections as part of a whole which is a work based
+on the Library, the distribution of the whole must be on the terms of
+this License, whose permissions for other licensees extend to the
+entire whole, and thus to each and every part regardless of who wrote
+it.
+
+Thus, it is not the intent of this section to claim rights or contest
+your rights to work written entirely by you; rather, the intent is to
+exercise the right to control the distribution of derivative or
+collective works based on the Library.
+
+In addition, mere aggregation of another work not based on the Library
+with the Library (or with a work based on the Library) on a volume of
+a storage or distribution medium does not bring the other work under
+the scope of this License.
+
+  3. You may opt to apply the terms of the ordinary GNU General Public
+License instead of this License to a given copy of the Library.  To do
+this, you must alter all the notices that refer to this License, so
+that they refer to the ordinary GNU General Public License, version 2,
+instead of to this License.  (If a newer version than version 2 of the
+ordinary GNU General Public License has appeared, then you can specify
+that version instead if you wish.)  Do not make any other change in
+these notices.
+
+  Once this change is made in a given copy, it is irreversible for
+that copy, so the ordinary GNU General Public License applies to all
+subsequent copies and derivative works made from that copy.
+
+  This option is useful when you wish to copy part of the code of
+the Library into a program that is not a library.
+
+  4. You may copy and distribute the Library (or a portion or
+derivative of it, under Section 2) in object code or executable form
+under the terms of Sections 1 and 2 above provided that you accompany
+it with the complete corresponding machine-readable source code, which
+must be distributed under the terms of Sections 1 and 2 above on a
+medium customarily used for software interchange.
+
+  If distribution of object code is made by offering access to copy
+from a designated place, then offering equivalent access to copy the
+source code from the same place satisfies the requirement to
+distribute the source code, even though third parties are not
+compelled to copy the source along with the object code.
+
+  5. A program that contains no derivative of any portion of the
+Library, but is designed to work with the Library by being compiled or
+linked with it, is called a "work that uses the Library".  Such a
+work, in isolation, is not a derivative work of the Library, and
+therefore falls outside the scope of this License.
+
+  However, linking a "work that uses the Library" with the Library
+creates an executable that is a derivative of the Library (because it
+contains portions of the Library), rather than a "work that uses the
+library".  The executable is therefore covered by this License.
+Section 6 states terms for distribution of such executables.
+
+  When a "work that uses the Library" uses material from a header file
+that is part of the Library, the object code for the work may be a
+derivative work of the Library even though the source code is not.
+Whether this is true is especially significant if the work can be
+linked without the Library, or if the work is itself a library.  The
+threshold for this to be true is not precisely defined by law.
+
+  If such an object file uses only numerical parameters, data
+structure layouts and accessors, and small macros and small inline
+functions (ten lines or less in length), then the use of the object
+file is unrestricted, regardless of whether it is legally a derivative
+work.  (Executables containing this object code plus portions of the
+Library will still fall under Section 6.)
+
+  Otherwise, if the work is a derivative of the Library, you may
+distribute the object code for the work under the terms of Section 6.
+Any executables containing that work also fall under Section 6,
+whether or not they are linked directly with the Library itself.
+
+  6. As an exception to the Sections above, you may also combine or
+link a "work that uses the Library" with the Library to produce a
+work containing portions of the Library, and distribute that work
+under terms of your choice, provided that the terms permit
+modification of the work for the customer's own use and reverse
+engineering for debugging such modifications.
+
+  You must give prominent notice with each copy of the work that the
+Library is used in it and that the Library and its use are covered by
+this License.  You must supply a copy of this License.  If the work
+during execution displays copyright notices, you must include the
+copyright notice for the Library among them, as well as a reference
+directing the user to the copy of this License.  Also, you must do one
+of these things:
+
+    a) Accompany the work with the complete corresponding
+    machine-readable source code for the Library including whatever
+    changes were used in the work (which must be distributed under
+    Sections 1 and 2 above); and, if the work is an executable linked
+    with the Library, with the complete machine-readable "work that
+    uses the Library", as object code and/or source code, so that the
+    user can modify the Library and then relink to produce a modified
+    executable containing the modified Library.  (It is understood
+    that the user who changes the contents of definitions files in the
+    Library will not necessarily be able to recompile the application
+    to use the modified definitions.)
+
+    b) Use a suitable shared library mechanism for linking with the
+    Library.  A suitable mechanism is one that (1) uses at run time a
+    copy of the library already present on the user's computer system,
+    rather than copying library functions into the executable, and (2)
+    will operate properly with a modified version of the library, if
+    the user installs one, as long as the modified version is
+    interface-compatible with the version that the work was made with.
+
+    c) Accompany the work with a written offer, valid for at
+    least three years, to give the same user the materials
+    specified in Subsection 6a, above, for a charge no more
+    than the cost of performing this distribution.
+
+    d) If distribution of the work is made by offering access to copy
+    from a designated place, offer equivalent access to copy the above
+    specified materials from the same place.
+
+    e) Verify that the user has already received a copy of these
+    materials or that you have already sent this user a copy.
+
+  For an executable, the required form of the "work that uses the
+Library" must include any data and utility programs needed for
+reproducing the executable from it.  However, as a special exception,
+the materials to be distributed need not include anything that is
+normally distributed (in either source or binary form) with the major
+components (compiler, kernel, and so on) of the operating system on
+which the executable runs, unless that component itself accompanies
+the executable.
+
+  It may happen that this requirement contradicts the license
+restrictions of other proprietary libraries that do not normally
+accompany the operating system.  Such a contradiction means you cannot
+use both them and the Library together in an executable that you
+distribute.
+
+  7. You may place library facilities that are a work based on the
+Library side-by-side in a single library together with other library
+facilities not covered by this License, and distribute such a combined
+library, provided that the separate distribution of the work based on
+the Library and of the other library facilities is otherwise
+permitted, and provided that you do these two things:
+
+    a) Accompany the combined library with a copy of the same work
+    based on the Library, uncombined with any other library
+    facilities.  This must be distributed under the terms of the
+    Sections above.
+
+    b) Give prominent notice with the combined library of the fact
+    that part of it is a work based on the Library, and explaining
+    where to find the accompanying uncombined form of the same work.
+
+  8. You may not copy, modify, sublicense, link with, or distribute
+the Library except as expressly provided under this License.  Any
+attempt otherwise to copy, modify, sublicense, link with, or
+distribute the Library is void, and will automatically terminate your
+rights under this License.  However, parties who have received copies,
+or rights, from you under this License will not have their licenses
+terminated so long as such parties remain in full compliance.
+
+  9. You are not required to accept this License, since you have not
+signed it.  However, nothing else grants you permission to modify or
+distribute the Library or its derivative works.  These actions are
+prohibited by law if you do not accept this License.  Therefore, by
+modifying or distributing the Library (or any work based on the
+Library), you indicate your acceptance of this License to do so, and
+all its terms and conditions for copying, distributing or modifying
+the Library or works based on it.
+
+  10. Each time you redistribute the Library (or any work based on the
+Library), the recipient automatically receives a license from the
+original licensor to copy, distribute, link with or modify the Library
+subject to these terms and conditions.  You may not impose any further
+restrictions on the recipients' exercise of the rights granted herein.
+You are not responsible for enforcing compliance by third parties with
+this License.
+
+  11. If, as a consequence of a court judgment or allegation of patent
+infringement or for any other reason (not limited to patent issues),
+conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot
+distribute so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you
+may not distribute the Library at all.  For example, if a patent
+license would not permit royalty-free redistribution of the Library by
+all those who receive copies directly or indirectly through you, then
+the only way you could satisfy both it and this License would be to
+refrain entirely from distribution of the Library.
+
+If any portion of this section is held invalid or unenforceable under any
+particular circumstance, the balance of the section is intended to apply,
+and the section as a whole is intended to apply in other circumstances.
+
+It is not the purpose of this section to induce you to infringe any
+patents or other property right claims or to contest validity of any
+such claims; this section has the sole purpose of protecting the
+integrity of the free software distribution system which is
+implemented by public license practices.  Many people have made
+generous contributions to the wide range of software distributed
+through that system in reliance on consistent application of that
+system; it is up to the author/donor to decide if he or she is willing
+to distribute software through any other system and a licensee cannot
+impose that choice.
+
+This section is intended to make thoroughly clear what is believed to
+be a consequence of the rest of this License.
+
+  12. If the distribution and/or use of the Library is restricted in
+certain countries either by patents or by copyrighted interfaces, the
+original copyright holder who places the Library under this License may add
+an explicit geographical distribution limitation excluding those countries,
+so that distribution is permitted only in or among countries not thus
+excluded.  In such case, this License incorporates the limitation as if
+written in the body of this License.
+
+  13. The Free Software Foundation may publish revised and/or new
+versions of the Lesser General Public License from time to time.
+Such new versions will be similar in spirit to the present version,
+but may differ in detail to address new problems or concerns.
+
+Each version is given a distinguishing version number.  If the Library
+specifies a version number of this License which applies to it and
+"any later version", you have the option of following the terms and
+conditions either of that version or of any later version published by
+the Free Software Foundation.  If the Library does not specify a
+license version number, you may choose any version ever published by
+the Free Software Foundation.
+
+  14. If you wish to incorporate parts of the Library into other free
+programs whose distribution conditions are incompatible with these,
+write to the author to ask for permission.  For software which is
+copyrighted by the Free Software Foundation, write to the Free
+Software Foundation; we sometimes make exceptions for this.  Our
+decision will be guided by the two goals of preserving the free status
+of all derivatives of our free software and of promoting the sharing
+and reuse of software generally.
+
+			    NO WARRANTY
+
+  15. BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO
+WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW.
+EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR
+OTHER PARTIES PROVIDE THE LIBRARY "AS IS" WITHOUT WARRANTY OF ANY
+KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE
+LIBRARY IS WITH YOU.  SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME
+THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+  16. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
+WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY
+AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU
+FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR
+CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
+LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
+RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
+FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
+SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
+DAMAGES.
+
+		     END OF TERMS AND CONDITIONS
+
+           How to Apply These Terms to Your New Libraries
+
+  If you develop a new library, and you want it to be of the greatest
+possible use to the public, we recommend making it free software that
+everyone can redistribute and change.  You can do so by permitting
+redistribution under these terms (or, alternatively, under the terms of the
+ordinary General Public License).
+
+  To apply these terms, attach the following notices to the library.  It is
+safest to attach them to the start of each source file to most effectively
+convey the exclusion of warranty; and each file should have at least the
+"copyright" line and a pointer to where the full notice is found.
+
+    <one line to give the library's name and a brief idea of what it does.>
+    Copyright (C) <year>  <name of author>
+
+    This library is free software; you can redistribute it and/or
+    modify it under the terms of the GNU Lesser General Public
+    License as published by the Free Software Foundation; either
+    version 2 of the License, or (at your option) any later version.
+
+    This library is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+    Lesser General Public License for more details.
+
+    You should have received a copy of the GNU Lesser General Public
+    License along with this library; if not, write to the Free Software
+    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+
+Also add information on how to contact you by electronic and paper mail.
+
+You should also get your employer (if you work as a programmer) or your
+school, if any, to sign a "copyright disclaimer" for the library, if
+necessary.  Here is a sample; alter the names:
+
+  Yoyodyne, Inc., hereby disclaims all copyright interest in the
+  library `Frob' (a library for tweaking knobs) written by James Random Hacker.
+
+  <signature of Ty Coon>, 1 April 1990
+  Ty Coon, President of Vice
+
+That's all there is to it!
+
+
diff --git a/resources/bun/licenses/SOURCE.md b/resources/bun/licenses/SOURCE.md
new file mode 100644
index 00000000..8fa0a336
--- /dev/null
+++ b/resources/bun/licenses/SOURCE.md
@@ -0,0 +1,19 @@
+# Bun 1.3.5 source and relinking materials
+
+SubMiner redistributes unmodified Bun 1.3.5 executables from the official Bun release. The executables report revision `1e86cebd74a5723e818b5c0555276b646bcf0e4c` through `bun --revision`. Bun's `bun-v1.3.5` Git tag points to the next commit, `fa5a5bbe556a4bda5bde77b4013aa6c3bb4ec9ab`, so the tag archive does not exactly match the distributed executables.
+
+The SubMiner GitHub release containing this application also contains `bun-v1.3.5-source.tar.gz` and its `.sha256` file. The archive contains:
+
+- Bun source at the binary's reported revision
+- WebKit and JavaScriptCore source at `6d0f3aac0b817cc01a846b3754b21271adedac12`
+- TinyCC source at `29985a3b59898861442fa3b43f663fc1af2591d7`
+- every external source repository registered by that Bun revision's CMake build, at its exact commit
+- Bun's dependency patches, build scripts, lockfiles, collected third-party license files, and instructions for rebuilding Bun against a modified JavaScriptCore
+
+The machine-readable inventory lives at `SOURCE-INVENTORY.json` inside the source archive and at `build/bun-source-manifest.json` in SubMiner's source repository.
+
+The archive vendors the source repositories linked through Bun's CMake build. It preserves Bun's package-manager lockfiles and lol-html's `Cargo.lock`, but it does not vendor npm packages, crates.io packages, compilers, SDKs, or other build tools. Rebuilding needs network access for those package-manager and toolchain inputs. The archive's rebuild README records the known tool versions and the remaining unpinned Rust nightly input.
+
+Bun's own license overview is included as `Bun-LICENSE.md`. WebKit's JavaScriptCore copy of GNU Library General Public License version 2 is included as `LGPL-2.0.txt`. TinyCC's GNU Lesser General Public License version 2.1 is included as `LGPL-2.1.txt`. `THIRD-PARTY-NOTICES.md` collects license texts from Bun's other externally fetched linked dependencies and identifies the scope of the remaining per-file notices in the source archive.
+
+This notice describes the materials supplied with the release. It is not a legal-compliance or reproducible-build claim.
diff --git a/resources/bun/licenses/THIRD-PARTY-NOTICES.md b/resources/bun/licenses/THIRD-PARTY-NOTICES.md
new file mode 100644
index 00000000..d4a64575
--- /dev/null
+++ b/resources/bun/licenses/THIRD-PARTY-NOTICES.md
@@ -0,0 +1,2011 @@
+# Bun 1.3.5 third-party notices
+
+This file collects the license texts shipped by the external source repositories used by Bun 1.3.5 at the revisions in build/bun-source-manifest.json. The corresponding-source release asset also preserves license notices embedded in individual Bun and WebKit source files. Bun’s own LICENSE.md lists additional embedded libraries and JavaScript polyfills whose source and per-file notices are included in that asset.
+
+## BoringSSL
+
+Source revision: f1ffd9e83d4f5c28a9c70d73f9a4e6fcf310062f
+
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+
+
+Licenses for support code
+-------------------------
+
+Parts of the TLS test suite are under the Go license. This code is not included
+in BoringSSL (i.e. libcrypto and libssl) when compiled, however, so
+distributing code linked against BoringSSL does not trigger this license:
+
+Copyright (c) 2009 The Go Authors. All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+   * Redistributions of source code must retain the above copyright
+notice, this list of conditions and the following disclaimer.
+   * Redistributions in binary form must reproduce the above
+copyright notice, this list of conditions and the following disclaimer
+in the documentation and/or other materials provided with the
+distribution.
+   * Neither the name of Google Inc. nor the names of its
+contributors may be used to endorse or promote products derived from
+this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+The Apache License, Version 2.0 (Apache-2.0)
+
+Copyright 2015-2020 the fiat-crypto authors (see the AUTHORS file)
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+Copyright 2008, Google Inc.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+    * Redistributions of source code must retain the above copyright
+notice, this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above
+copyright notice, this list of conditions and the following disclaimer
+in the documentation and/or other materials provided with the
+distribution.
+    * Neither the name of Google Inc. nor the names of its
+contributors may be used to endorse or promote products derived from
+this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+## Brotli
+
+Source revision: ed738e842d2fbdf2d6459e39267a633c4a9b2f5d
+
+Copyright (c) 2009, 2010, 2013-2016 by the Brotli Authors.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+
+## c-ares
+
+Source revision: 3ac47ee46edd8ea40370222f91613fc16c434853
+
+MIT License
+
+Copyright (c) 1998 Massachusetts Institute of Technology  
+Copyright (c) 2007 - 2023 Daniel Stenberg with many contributors, see AUTHORS
+file.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice (including the next
+paragraph) shall be included in all copies or substantial portions of the
+Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+## HdrHistogram-CC0
+
+Source revision: be60a9987ee48d0abf0d7b6a175bad8d6c1585d1
+
+Creative Commons Legal Code
+
+CC0 1.0 Universal
+
+    CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE
+    LEGAL SERVICES. DISTRIBUTION OF THIS DOCUMENT DOES NOT CREATE AN
+    ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS
+    INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES
+    REGARDING THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS
+    PROVIDED HEREUNDER, AND DISCLAIMS LIABILITY FOR DAMAGES RESULTING FROM
+    THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS PROVIDED
+    HEREUNDER.
+
+Statement of Purpose
+
+The laws of most jurisdictions throughout the world automatically confer
+exclusive Copyright and Related Rights (defined below) upon the creator
+and subsequent owner(s) (each and all, an "owner") of an original work of
+authorship and/or a database (each, a "Work").
+
+Certain owners wish to permanently relinquish those rights to a Work for
+the purpose of contributing to a commons of creative, cultural and
+scientific works ("Commons") that the public can reliably and without fear
+of later claims of infringement build upon, modify, incorporate in other
+works, reuse and redistribute as freely as possible in any form whatsoever
+and for any purposes, including without limitation commercial purposes.
+These owners may contribute to the Commons to promote the ideal of a free
+culture and the further production of creative, cultural and scientific
+works, or to gain reputation or greater distribution for their Work in
+part through the use and efforts of others.
+
+For these and/or other purposes and motivations, and without any
+expectation of additional consideration or compensation, the person
+associating CC0 with a Work (the "Affirmer"), to the extent that he or she
+is an owner of Copyright and Related Rights in the Work, voluntarily
+elects to apply CC0 to the Work and publicly distribute the Work under its
+terms, with knowledge of his or her Copyright and Related Rights in the
+Work and the meaning and intended legal effect of CC0 on those rights.
+
+1. Copyright and Related Rights. A Work made available under CC0 may be
+protected by copyright and related or neighboring rights ("Copyright and
+Related Rights"). Copyright and Related Rights include, but are not
+limited to, the following:
+
+  i. the right to reproduce, adapt, distribute, perform, display,
+     communicate, and translate a Work;
+ ii. moral rights retained by the original author(s) and/or performer(s);
+iii. publicity and privacy rights pertaining to a person's image or
+     likeness depicted in a Work;
+ iv. rights protecting against unfair competition in regards to a Work,
+     subject to the limitations in paragraph 4(a), below;
+  v. rights protecting the extraction, dissemination, use and reuse of data
+     in a Work;
+ vi. database rights (such as those arising under Directive 96/9/EC of the
+     European Parliament and of the Council of 11 March 1996 on the legal
+     protection of databases, and under any national implementation
+     thereof, including any amended or successor version of such
+     directive); and
+vii. other similar, equivalent or corresponding rights throughout the
+     world based on applicable law or treaty, and any national
+     implementations thereof.
+
+2. Waiver. To the greatest extent permitted by, but not in contravention
+of, applicable law, Affirmer hereby overtly, fully, permanently,
+irrevocably and unconditionally waives, abandons, and surrenders all of
+Affirmer's Copyright and Related Rights and associated claims and causes
+of action, whether now known or unknown (including existing as well as
+future claims and causes of action), in the Work (i) in all territories
+worldwide, (ii) for the maximum duration provided by applicable law or
+treaty (including future time extensions), (iii) in any current or future
+medium and for any number of copies, and (iv) for any purpose whatsoever,
+including without limitation commercial, advertising or promotional
+purposes (the "Waiver"). Affirmer makes the Waiver for the benefit of each
+member of the public at large and to the detriment of Affirmer's heirs and
+successors, fully intending that such Waiver shall not be subject to
+revocation, rescission, cancellation, termination, or any other legal or
+equitable action to disrupt the quiet enjoyment of the Work by the public
+as contemplated by Affirmer's express Statement of Purpose.
+
+3. Public License Fallback. Should any part of the Waiver for any reason
+be judged legally invalid or ineffective under applicable law, then the
+Waiver shall be preserved to the maximum extent permitted taking into
+account Affirmer's express Statement of Purpose. In addition, to the
+extent the Waiver is so judged Affirmer hereby grants to each affected
+person a royalty-free, non transferable, non sublicensable, non exclusive,
+irrevocable and unconditional license to exercise Affirmer's Copyright and
+Related Rights in the Work (i) in all territories worldwide, (ii) for the
+maximum duration provided by applicable law or treaty (including future
+time extensions), (iii) in any current or future medium and for any number
+of copies, and (iv) for any purpose whatsoever, including without
+limitation commercial, advertising or promotional purposes (the
+"License"). The License shall be deemed effective as of the date CC0 was
+applied by Affirmer to the Work. Should any part of the License for any
+reason be judged legally invalid or ineffective under applicable law, such
+partial invalidity or ineffectiveness shall not invalidate the remainder
+of the License, and in such case Affirmer hereby affirms that he or she
+will not (i) exercise any of his or her remaining Copyright and Related
+Rights in the Work or (ii) assert any associated claims and causes of
+action with respect to the Work, in either case contrary to Affirmer's
+express Statement of Purpose.
+
+4. Limitations and Disclaimers.
+
+ a. No trademark or patent rights held by Affirmer are waived, abandoned,
+    surrendered, licensed or otherwise affected by this document.
+ b. Affirmer offers the Work as-is and makes no representations or
+    warranties of any kind concerning the Work, express, implied,
+    statutory or otherwise, including without limitation warranties of
+    title, merchantability, fitness for a particular purpose, non
+    infringement, or the absence of latent or other defects, accuracy, or
+    the present or absence of errors, whether or not discoverable, all to
+    the greatest extent permissible under applicable law.
+ c. Affirmer disclaims responsibility for clearing rights of other persons
+    that may apply to the Work or any use thereof, including without
+    limitation any person's Copyright and Related Rights in the Work.
+    Further, Affirmer disclaims responsibility for obtaining any necessary
+    consents, permissions or other rights required for any use of the
+    Work.
+ d. Affirmer understands and acknowledges that Creative Commons is not a
+    party to this document and has no duty or obligation with respect to
+    this CC0 or use of the Work.
+
+## HdrHistogram-BSD-2-Clause
+
+Source revision: be60a9987ee48d0abf0d7b6a175bad8d6c1585d1
+
+The code in this repository code was Written by Gil Tene, Michael Barker,
+Matt Warren, and Philip Orwig, and released to the public domain, as explained at
+http://creativecommons.org/publicdomain/zero/1.0/
+
+For users of this code who wish to consume it under the "BSD" license
+rather than under the public domain or CC0 contribution text mentioned
+above, the code found under this directory is *also* provided under the
+following license (commonly referred to as the BSD 2-Clause License). This
+license does not detract from the above stated release of the code into
+the public domain, and simply represents an additional license granted by
+the Author.
+
+-----------------------------------------------------------------------------
+** Beginning of "BSD 2-Clause License" text. **
+
+ Copyright (c) 2012, 2013, 2014 Gil Tene
+ Copyright (c) 2014 Michael Barker
+ Copyright (c) 2014 Matt Warren
+ Copyright (c) 2015 Philip Orwig
+ All rights reserved.
+
+ Redistribution and use in source and binary forms, with or without
+ modification, are permitted provided that the following conditions are met:
+
+ 1. Redistributions of source code must retain the above copyright notice,
+    this list of conditions and the following disclaimer.
+
+ 2. Redistributions in binary form must reproduce the above copyright notice,
+    this list of conditions and the following disclaimer in the documentation
+    and/or other materials provided with the distribution.
+
+ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
+ THE POSSIBILITY OF SUCH DAMAGE.
+
+## Highway
+
+Source revision: ac0d5d297b13ab1b89f48484fc7911082d76a93f
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+## libarchive
+
+Source revision: 9525f90ca4bd14c7b335e2f8c84a4607b0af6bdf
+
+The libarchive distribution as a whole is Copyright by Tim Kientzle
+and is subject to the copyright notice reproduced at the bottom of
+this file.
+
+Each individual file in this distribution should have a clear
+copyright/licensing statement at the beginning of the file.  If any do
+not, please let me know and I will rectify it.  The following is
+intended to summarize the copyright status of the individual files;
+the actual statements in the files are controlling.
+
+* Except as listed below, all C sources (including .c and .h files)
+  and documentation files are subject to the copyright notice reproduced
+  at the bottom of this file.
+
+* The following source files are also subject in whole or in part to
+  a 3-clause UC Regents copyright; please read the individual source
+  files for details:
+   libarchive/archive_read_support_filter_compress.c
+   libarchive/archive_write_add_filter_compress.c
+   libarchive/mtree.5
+
+* The following source files are in the public domain:
+   libarchive/archive_parse_date.c
+
+* The following source files are triple-licensed with the ability to choose
+  from CC0 1.0 Universal, OpenSSL or Apache 2.0 licenses:
+   libarchive/archive_blake2.h
+   libarchive/archive_blake2_impl.h
+   libarchive/archive_blake2s_ref.c
+   libarchive/archive_blake2sp_ref.c
+
+* The build files---including Makefiles, configure scripts,
+  and auxiliary scripts used as part of the compile process---have
+  widely varying licensing terms.  Please check individual files before
+  distributing them to see if those restrictions apply to you.
+
+I intend for all new source code to use the license below and hope over
+time to replace code with other licenses with new implementations that
+do use the license below.  The varying licensing of the build scripts
+seems to be an unavoidable mess.
+
+
+Copyright (c) 2003-2018 <author(s)>
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions
+are met:
+1. Redistributions of source code must retain the above copyright
+   notice, this list of conditions and the following disclaimer
+   in this position and unchanged.
+2. Redistributions in binary form must reproduce the above copyright
+   notice, this list of conditions and the following disclaimer in the
+   documentation and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE AUTHOR(S) ``AS IS'' AND ANY EXPRESS OR
+IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+IN NO EVENT SHALL THE AUTHOR(S) BE LIABLE FOR ANY DIRECT, INDIRECT,
+INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+## libdeflate
+
+Source revision: c8c56a20f8f621e6a966b716b31f1dedab6a41e3
+
+Copyright 2016 Eric Biggers
+Copyright 2024 Google LLC
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation files
+(the "Software"), to deal in the Software without restriction,
+including without limitation the rights to use, copy, modify, merge,
+publish, distribute, sublicense, and/or sell copies of the Software,
+and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
+BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
+ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+## libuv
+
+Source revision: f3ce527ea940d926c40878ba5de219640c362811
+
+Copyright (c) 2015-present libuv project contributors.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to
+deal in the Software without restriction, including without limitation the
+rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+sell copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+IN THE SOFTWARE.
+
+## lol-html
+
+Source revision: d64457d9ff0143deef025d5df7e8586092b9afb7
+
+Copyright (C) 2019, Cloudflare, Inc.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+this list of conditions and the following disclaimer in the documentation and/or
+other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors
+may be used to endorse or promote products derived from this software without
+specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+## ls-hpack
+
+Source revision: 8905c024b6d052f083a3d11d0a169b3c2735c8a1
+
+MIT License
+
+Copyright (c) 2018 - 2023 LiteSpeed Technologies Inc
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+## mimalloc
+
+Source revision: 1beadf9651a7bfdec6b5367c380ecc3fe1c40d1a
+
+MIT License
+
+Copyright (c) 2018-2021 Microsoft Corporation, Daan Leijen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+## zlib
+
+Source revision: 886098f3f339617b4243b286f5ed364b9989e245
+
+Copyright notice:
+
+ (C) 1995-2022 Jean-loup Gailly and Mark Adler
+
+  This software is provided 'as-is', without any express or implied
+  warranty.  In no event will the authors be held liable for any damages
+  arising from the use of this software.
+
+  Permission is granted to anyone to use this software for any purpose,
+  including commercial applications, and to alter it and redistribute it
+  freely, subject to the following restrictions:
+
+  1. The origin of this software must not be misrepresented; you must not
+     claim that you wrote the original software. If you use this software
+     in a product, an acknowledgment in the product documentation would be
+     appreciated but is not required.
+  2. Altered source versions must be plainly marked as such, and must not be
+     misrepresented as being the original software.
+  3. This notice may not be removed or altered from any source distribution.
+
+  Jean-loup Gailly        Mark Adler
+  jloup@gzip.org          madler@alumni.caltech.edu
+
+## zstd-BSD
+
+Source revision: f8745da6ff1ad1e7bab384bd1f9d742439278e99
+
+BSD License
+
+For Zstandard software
+
+Copyright (c) Meta Platforms, Inc. and affiliates. All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+ * Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+ * Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+ * Neither the name Facebook, nor Meta, nor the names of its contributors may
+   be used to endorse or promote products derived from this software without
+   specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+## zstd-GPLv2
+
+Source revision: f8745da6ff1ad1e7bab384bd1f9d742439278e99
+
+                    GNU GENERAL PUBLIC LICENSE
+                       Version 2, June 1991
+
+ Copyright (C) 1989, 1991 Free Software Foundation, Inc.,
+ 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+                            Preamble
+
+  The licenses for most software are designed to take away your
+freedom to share and change it.  By contrast, the GNU General Public
+License is intended to guarantee your freedom to share and change free
+software--to make sure the software is free for all its users.  This
+General Public License applies to most of the Free Software
+Foundation's software and to any other program whose authors commit to
+using it.  (Some other Free Software Foundation software is covered by
+the GNU Lesser General Public License instead.)  You can apply it to
+your programs, too.
+
+  When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+this service if you wish), that you receive source code or can get it
+if you want it, that you can change the software or use pieces of it
+in new free programs; and that you know you can do these things.
+
+  To protect your rights, we need to make restrictions that forbid
+anyone to deny you these rights or to ask you to surrender the rights.
+These restrictions translate to certain responsibilities for you if you
+distribute copies of the software, or if you modify it.
+
+  For example, if you distribute copies of such a program, whether
+gratis or for a fee, you must give the recipients all the rights that
+you have.  You must make sure that they, too, receive or can get the
+source code.  And you must show them these terms so they know their
+rights.
+
+  We protect your rights with two steps: (1) copyright the software, and
+(2) offer you this license which gives you legal permission to copy,
+distribute and/or modify the software.
+
+  Also, for each author's protection and ours, we want to make certain
+that everyone understands that there is no warranty for this free
+software.  If the software is modified by someone else and passed on, we
+want its recipients to know that what they have is not the original, so
+that any problems introduced by others will not reflect on the original
+authors' reputations.
+
+  Finally, any free program is threatened constantly by software
+patents.  We wish to avoid the danger that redistributors of a free
+program will individually obtain patent licenses, in effect making the
+program proprietary.  To prevent this, we have made it clear that any
+patent must be licensed for everyone's free use or not licensed at all.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.
+
+                    GNU GENERAL PUBLIC LICENSE
+   TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+
+  0. This License applies to any program or other work which contains
+a notice placed by the copyright holder saying it may be distributed
+under the terms of this General Public License.  The "Program", below,
+refers to any such program or work, and a "work based on the Program"
+means either the Program or any derivative work under copyright law:
+that is to say, a work containing the Program or a portion of it,
+either verbatim or with modifications and/or translated into another
+language.  (Hereinafter, translation is included without limitation in
+the term "modification".)  Each licensee is addressed as "you".
+
+Activities other than copying, distribution and modification are not
+covered by this License; they are outside its scope.  The act of
+running the Program is not restricted, and the output from the Program
+is covered only if its contents constitute a work based on the
+Program (independent of having been made by running the Program).
+Whether that is true depends on what the Program does.
+
+  1. You may copy and distribute verbatim copies of the Program's
+source code as you receive it, in any medium, provided that you
+conspicuously and appropriately publish on each copy an appropriate
+copyright notice and disclaimer of warranty; keep intact all the
+notices that refer to this License and to the absence of any warranty;
+and give any other recipients of the Program a copy of this License
+along with the Program.
+
+You may charge a fee for the physical act of transferring a copy, and
+you may at your option offer warranty protection in exchange for a fee.
+
+  2. You may modify your copy or copies of the Program or any portion
+of it, thus forming a work based on the Program, and copy and
+distribute such modifications or work under the terms of Section 1
+above, provided that you also meet all of these conditions:
+
+    a) You must cause the modified files to carry prominent notices
+    stating that you changed the files and the date of any change.
+
+    b) You must cause any work that you distribute or publish, that in
+    whole or in part contains or is derived from the Program or any
+    part thereof, to be licensed as a whole at no charge to all third
+    parties under the terms of this License.
+
+    c) If the modified program normally reads commands interactively
+    when run, you must cause it, when started running for such
+    interactive use in the most ordinary way, to print or display an
+    announcement including an appropriate copyright notice and a
+    notice that there is no warranty (or else, saying that you provide
+    a warranty) and that users may redistribute the program under
+    these conditions, and telling the user how to view a copy of this
+    License.  (Exception: if the Program itself is interactive but
+    does not normally print such an announcement, your work based on
+    the Program is not required to print an announcement.)
+
+These requirements apply to the modified work as a whole.  If
+identifiable sections of that work are not derived from the Program,
+and can be reasonably considered independent and separate works in
+themselves, then this License, and its terms, do not apply to those
+sections when you distribute them as separate works.  But when you
+distribute the same sections as part of a whole which is a work based
+on the Program, the distribution of the whole must be on the terms of
+this License, whose permissions for other licensees extend to the
+entire whole, and thus to each and every part regardless of who wrote it.
+
+Thus, it is not the intent of this section to claim rights or contest
+your rights to work written entirely by you; rather, the intent is to
+exercise the right to control the distribution of derivative or
+collective works based on the Program.
+
+In addition, mere aggregation of another work not based on the Program
+with the Program (or with a work based on the Program) on a volume of
+a storage or distribution medium does not bring the other work under
+the scope of this License.
+
+  3. You may copy and distribute the Program (or a work based on it,
+under Section 2) in object code or executable form under the terms of
+Sections 1 and 2 above provided that you also do one of the following:
+
+    a) Accompany it with the complete corresponding machine-readable
+    source code, which must be distributed under the terms of Sections
+    1 and 2 above on a medium customarily used for software interchange; or,
+
+    b) Accompany it with a written offer, valid for at least three
+    years, to give any third party, for a charge no more than your
+    cost of physically performing source distribution, a complete
+    machine-readable copy of the corresponding source code, to be
+    distributed under the terms of Sections 1 and 2 above on a medium
+    customarily used for software interchange; or,
+
+    c) Accompany it with the information you received as to the offer
+    to distribute corresponding source code.  (This alternative is
+    allowed only for noncommercial distribution and only if you
+    received the program in object code or executable form with such
+    an offer, in accord with Subsection b above.)
+
+The source code for a work means the preferred form of the work for
+making modifications to it.  For an executable work, complete source
+code means all the source code for all modules it contains, plus any
+associated interface definition files, plus the scripts used to
+control compilation and installation of the executable.  However, as a
+special exception, the source code distributed need not include
+anything that is normally distributed (in either source or binary
+form) with the major components (compiler, kernel, and so on) of the
+operating system on which the executable runs, unless that component
+itself accompanies the executable.
+
+If distribution of executable or object code is made by offering
+access to copy from a designated place, then offering equivalent
+access to copy the source code from the same place counts as
+distribution of the source code, even though third parties are not
+compelled to copy the source along with the object code.
+
+  4. You may not copy, modify, sublicense, or distribute the Program
+except as expressly provided under this License.  Any attempt
+otherwise to copy, modify, sublicense or distribute the Program is
+void, and will automatically terminate your rights under this License.
+However, parties who have received copies, or rights, from you under
+this License will not have their licenses terminated so long as such
+parties remain in full compliance.
+
+  5. You are not required to accept this License, since you have not
+signed it.  However, nothing else grants you permission to modify or
+distribute the Program or its derivative works.  These actions are
+prohibited by law if you do not accept this License.  Therefore, by
+modifying or distributing the Program (or any work based on the
+Program), you indicate your acceptance of this License to do so, and
+all its terms and conditions for copying, distributing or modifying
+the Program or works based on it.
+
+  6. Each time you redistribute the Program (or any work based on the
+Program), the recipient automatically receives a license from the
+original licensor to copy, distribute or modify the Program subject to
+these terms and conditions.  You may not impose any further
+restrictions on the recipients' exercise of the rights granted herein.
+You are not responsible for enforcing compliance by third parties to
+this License.
+
+  7. If, as a consequence of a court judgment or allegation of patent
+infringement or for any other reason (not limited to patent issues),
+conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot
+distribute so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you
+may not distribute the Program at all.  For example, if a patent
+license would not permit royalty-free redistribution of the Program by
+all those who receive copies directly or indirectly through you, then
+the only way you could satisfy both it and this License would be to
+refrain entirely from distribution of the Program.
+
+If any portion of this section is held invalid or unenforceable under
+any particular circumstance, the balance of the section is intended to
+apply and the section as a whole is intended to apply in other
+circumstances.
+
+It is not the purpose of this section to induce you to infringe any
+patents or other property right claims or to contest validity of any
+such claims; this section has the sole purpose of protecting the
+integrity of the free software distribution system, which is
+implemented by public license practices.  Many people have made
+generous contributions to the wide range of software distributed
+through that system in reliance on consistent application of that
+system; it is up to the author/donor to decide if he or she is willing
+to distribute software through any other system and a licensee cannot
+impose that choice.
+
+This section is intended to make thoroughly clear what is believed to
+be a consequence of the rest of this License.
+
+  8. If the distribution and/or use of the Program is restricted in
+certain countries either by patents or by copyrighted interfaces, the
+original copyright holder who places the Program under this License
+may add an explicit geographical distribution limitation excluding
+those countries, so that distribution is permitted only in or among
+countries not thus excluded.  In such case, this License incorporates
+the limitation as if written in the body of this License.
+
+  9. The Free Software Foundation may publish revised and/or new versions
+of the General Public License from time to time.  Such new versions will
+be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+Each version is given a distinguishing version number.  If the Program
+specifies a version number of this License which applies to it and "any
+later version", you have the option of following the terms and conditions
+either of that version or of any later version published by the Free
+Software Foundation.  If the Program does not specify a version number of
+this License, you may choose any version ever published by the Free Software
+Foundation.
+
+  10. If you wish to incorporate parts of the Program into other free
+programs whose distribution conditions are different, write to the author
+to ask for permission.  For software which is copyrighted by the Free
+Software Foundation, write to the Free Software Foundation; we sometimes
+make exceptions for this.  Our decision will be guided by the two goals
+of preserving the free status of all derivatives of our free software and
+of promoting the sharing and reuse of software generally.
+
+                            NO WARRANTY
+
+  11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
+FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW.  EXCEPT WHEN
+OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
+PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
+OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS
+TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE
+PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
+REPAIR OR CORRECTION.
+
+  12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
+REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
+INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
+OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
+TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
+YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
+PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGES.
+
+                     END OF TERMS AND CONDITIONS
+
+            How to Apply These Terms to Your New Programs
+
+  If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these terms.
+
+  To do so, attach the following notices to the program.  It is safest
+to attach them to the start of each source file to most effectively
+convey the exclusion of warranty; and each file should have at least
+the "copyright" line and a pointer to where the full notice is found.
+
+    <one line to give the program's name and a brief idea of what it does.>
+    Copyright (C) <year>  <name of author>
+
+    This program is free software; you can redistribute it and/or modify
+    it under the terms of the GNU General Public License as published by
+    the Free Software Foundation; either version 2 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+
+    You should have received a copy of the GNU General Public License along
+    with this program; if not, write to the Free Software Foundation, Inc.,
+    51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+
+Also add information on how to contact you by electronic and paper mail.
+
+If the program is interactive, make it output a short notice like this
+when it starts in an interactive mode:
+
+    Gnomovision version 69, Copyright (C) year name of author
+    Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
+    This is free software, and you are welcome to redistribute it
+    under certain conditions; type `show c' for details.
+
+The hypothetical commands `show w' and `show c' should show the appropriate
+parts of the General Public License.  Of course, the commands you use may
+be called something other than `show w' and `show c'; they could even be
+mouse-clicks or menu items--whatever suits your program.
+
+You should also get your employer (if you work as a programmer) or your
+school, if any, to sign a "copyright disclaimer" for the program, if
+necessary.  Here is a sample; alter the names:
+
+  Yoyodyne, Inc., hereby disclaims all copyright interest in the program
+  `Gnomovision' (which makes passes at compilers) written by James Hacker.
+
+  <signature of Ty Coon>, 1 April 1989
+  Ty Coon, President of Vice
+
+This General Public License does not permit incorporating your program into
+proprietary programs.  If your program is a subroutine library, you may
+consider it more useful to permit linking proprietary applications with the
+library.  If this is what you want to do, use the GNU Lesser General
+Public License instead of this License.
+## picohttpparser
+
+Source revision: 066d2b1e9ab820703db0837a7255d92d30f0c9f5
+
+/*
+ * Copyright (c) 2009-2014 Kazuho Oku, Tokuhiro Matsuno, Daisuke Murase,
+ *                         Shigeo Mitsunari
+ *
+ * The software is licensed under either the MIT License (below) or the Perl
+ * license.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ */
+
+## Bun uSockets fork
+
+
+
+Source: Bun source tree at packages/bun-usockets
+
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+
+## Bun uWebSockets fork
+
+
+
+Source: Bun source tree at packages/bun-uws
+
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+
+## zig-clap
+
+
+
+Source: Bun source tree at src/deps/zig-clap
+
+
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
+
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+
+For more information, please refer to <http://unlicense.org>
diff --git a/scripts/aur-release-download.test.ts b/scripts/aur-release-download.test.ts
new file mode 100644
index 00000000..4dfaa76a
--- /dev/null
+++ b/scripts/aur-release-download.test.ts
@@ -0,0 +1,93 @@
+import assert from 'node:assert/strict';
+import { mkdtemp, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { test } from 'bun:test';
+
+test.each([false, true])(
+  'AUR downloads handle empty release metadata, unavailable=%s',
+  async (unavailable) => {
+    const workflow = await readFile(
+      new URL('../.github/workflows/release.yml', import.meta.url),
+      'utf8',
+    );
+    const step = workflow
+      .split('      - name: Download release assets for AUR\n')[1]
+      ?.split('\n      - name:')[0];
+    const script = step?.split('        run: |\n')[1]?.replace(/^          /gm, '');
+    assert.ok(script, 'AUR download step must have a shell script');
+
+    const workspace = await mkdtemp(path.join(os.tmpdir(), 'subminer-aur-download-'));
+    const requests: string[] = [];
+    const files = new Map([
+      ['SubMiner-0.20.0.AppImage', 'appimage bytes'],
+      ['subminer', 'launcher bytes'],
+      ['subminer-assets.tar.gz', 'optional assets bytes'],
+    ]);
+    const server = Bun.serve({
+      hostname: '127.0.0.1',
+      port: 0,
+      fetch(request) {
+        const pathname = new URL(request.url).pathname;
+        requests.push(pathname);
+        if (unavailable || requests.length === 1) return new Response('try again', { status: 503 });
+        const name = pathname.split('/').at(-1);
+        const body = name ? files.get(name) : undefined;
+        return new Response(body ?? 'not found', { status: body ? 200 : 404 });
+      },
+    });
+
+    try {
+      const bin = path.join(workspace, 'bin');
+      await mkdir(bin);
+      await writeFile(
+        path.join(bin, 'gh'),
+        '#!/bin/sh\necho "no assets to download" >&2\nexit 1\n',
+        { mode: 0o755 },
+      );
+      const output = path.join(workspace, 'output');
+      const proc = Bun.spawn(['bash', '-c', script], {
+        cwd: workspace,
+        env: {
+          ...process.env,
+          PATH: `${bin}${path.delimiter}${process.env.PATH}`,
+          RELEASE_VERSION: 'v0.20.0',
+          GITHUB_SERVER_URL: server.url.origin,
+          GITHUB_REPOSITORY: 'ksyasuda/SubMiner',
+          GITHUB_OUTPUT: output,
+        },
+        stdout: 'pipe',
+        stderr: 'pipe',
+      });
+      const [status, stderr, stdout] = await Promise.all([
+        proc.exited,
+        new Response(proc.stderr).text(),
+        new Response(proc.stdout).text(),
+      ]);
+      assert.equal(status, 0, stderr);
+      if (unavailable) {
+        assert.equal(requests.length, 4, 'failed downloads stop after three retries');
+        assert.match(await readFile(output, 'utf8'), /^skip=true$/m);
+        assert.match(stdout, /::warning::Unable to download/);
+        await assert.rejects(
+          readFile(path.join(workspace, '.tmp/aur-release-assets/SubMiner-0.20.0.AppImage')),
+          { code: 'ENOENT' },
+        );
+        return;
+      }
+      for (const [name, body] of files) {
+        assert.equal(
+          await readFile(path.join(workspace, '.tmp/aur-release-assets', name), 'utf8'),
+          body,
+        );
+        assert.ok(requests.includes(`/ksyasuda/SubMiner/releases/download/v0.20.0/${name}`));
+      }
+      assert.equal(requests.length, 4, 'the first failed download must be retried');
+      assert.match(await readFile(output, 'utf8'), /^skip=false$/m);
+    } finally {
+      server.stop(true);
+      await rm(workspace, { recursive: true, force: true });
+    }
+  },
+  15_000,
+);
diff --git a/scripts/build-changelog.test.ts b/scripts/build-changelog.test.ts
index 807672f7..cfb2ef06 100644
--- a/scripts/build-changelog.test.ts
+++ b/scripts/build-changelog.test.ts
@@ -1,4 +1,5 @@
 import assert from 'node:assert/strict';
+import { execFileSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import test from 'node:test';
@@ -43,14 +44,22 @@ function fragmentTypesInPrompt(input: string): string[] {
     .map((line) => line.slice('type: '.length).trim());
 }
 
-function assertReleaseNotesPromptRequestsNestedBullets(input: string): void {
-  assert.match(input, /In MODE: release-notes, use short top-level change bullets/);
-  assert.match(input, /Nested bullets should cover the change, user benefit, and any user action/);
-  assert.match(input, /Do not require the exact nested labels/);
+function assertPromptRequestsNestedBullets(input: string): void {
+  assert.match(input, /In both modes, split every item into one nested bullet per distinct change/);
+  assert.match(input, /Never stack several distinct changes into one long paragraph-shaped bullet/);
   assert.match(input, /Keep nested bullets short, concrete, and readable by non-technical users/);
   assert.match(input, /Avoid paragraph-style release-note bullets/);
 }
 
+function assertReleaseNotesPromptRequestsNestedBullets(input: string): void {
+  assertPromptRequestsNestedBullets(input);
+  assert.match(
+    input,
+    /In MODE: release-notes, nested bullets should also cover user benefit and any user action/,
+  );
+  assert.match(input, /Do not require the exact nested labels/);
+}
+
 function defaultPolishedBody(input: string): string {
   const mode = modeFromPrompt(input);
   const types = fragmentTypesInPrompt(input);
@@ -445,6 +454,7 @@ test('writeChangelogArtifacts prompts Claude to summarize the final stable outco
         prompt,
         /Multiple fixes within the same prerelease cycle should collapse into one current-state bullet/,
       );
+      assertPromptRequestsNestedBullets(prompt);
     }
 
     const releaseNotesPrompt = stub.calls.find(
@@ -583,7 +593,7 @@ test('writePrereleaseNotesForVersion writes cumulative beta notes without mutati
     const outputPath = writePrereleaseNotesForVersion({
       cwd: projectRoot,
       version: '0.11.3-beta.1',
-      deps: { runClaude: stub.runClaude },
+      deps: { runClaude: stub.runClaude, listPrereleaseTags: () => [] },
     });
 
     assert.equal(outputPath, path.join(projectRoot, 'release', 'prerelease-notes.md'));
@@ -605,10 +615,15 @@ test('writePrereleaseNotesForVersion writes cumulative beta notes without mutati
 
     const prereleaseNotes = fs.readFileSync(outputPath, 'utf8');
     assert.match(prereleaseNotes, /^> This is a prerelease build for testing\./m);
-    assert.match(prereleaseNotes, /<!-- prerelease-base-version: 0\.11\.3 -->/);
+    assert.match(prereleaseNotes, /<!-- prerelease-version: 0\.11\.3-beta\.1 -->/);
+    assert.doesNotMatch(prereleaseNotes, /## Changes since /);
     assert.match(prereleaseNotes, /## Highlights\n### Added\n- Polished: added entry\./);
     assert.match(prereleaseNotes, /### Fixed\n- Polished: fixed entry\./);
     assert.match(prereleaseNotes, /## Installation\n\nSee the README and docs\/installation guide/);
+    assert.match(prereleaseNotes, /Windows `subminer\.cmd` launcher/);
+    assert.match(prereleaseNotes, /Both launcher downloads use Bun included with the SubMiner app/);
+    assert.match(prereleaseNotes, /Bun corresponding source: `bun-v1\.3\.5-source\.tar\.gz`/);
+    assert.match(prereleaseNotes, /statically links JavaScriptCore \(LGPL 2\.0\)/);
   } finally {
     fs.rmSync(workspace, { recursive: true, force: true });
   }
@@ -668,7 +683,7 @@ test('writePrereleaseNotesForVersion reuses existing prerelease notes when addin
     const outputPath = writePrereleaseNotesForVersion({
       cwd: projectRoot,
       version: '0.11.3-beta.2',
-      deps: { runClaude: stub.runClaude },
+      deps: { runClaude: stub.runClaude, listPrereleaseTags: () => [] },
     });
 
     assert.equal(stub.calls.length, 1, 'prerelease should issue exactly one Claude call');
@@ -723,7 +738,7 @@ test('writePrereleaseNotesForVersion ignores unmarked prerelease notes from an o
     const outputPath = writePrereleaseNotesForVersion({
       cwd: projectRoot,
       version: '0.17.0-beta.1',
-      deps: { runClaude: stub.runClaude },
+      deps: { runClaude: stub.runClaude, listPrereleaseTags: () => [] },
     });
 
     assert.equal(stub.calls.length, 1, 'prerelease should issue exactly one Claude call');
@@ -790,7 +805,7 @@ test('writePrereleaseNotesForVersion prompts Claude to revise stale prerelease b
     writePrereleaseNotesForVersion({
       cwd: projectRoot,
       version: '0.12.0-beta.2',
-      deps: { runClaude: stub.runClaude },
+      deps: { runClaude: stub.runClaude, listPrereleaseTags: () => [] },
     });
 
     assert.equal(stub.calls.length, 1, 'prerelease should issue exactly one Claude call');
@@ -830,7 +845,7 @@ test('writePrereleaseNotesForVersion supports rc prereleases', async () => {
     const outputPath = writePrereleaseNotesForVersion({
       cwd: projectRoot,
       version: '0.11.3-rc.1',
-      deps: { runClaude: stub.runClaude },
+      deps: { runClaude: stub.runClaude, listPrereleaseTags: () => [] },
     });
 
     const prereleaseNotes = fs.readFileSync(outputPath, 'utf8');
@@ -1447,3 +1462,373 @@ test('writeChangelogArtifacts strips <details> blocks from release notes when re
     fs.rmSync(workspace, { recursive: true, force: true });
   }
 });
+
+test('selectPreviousPrereleaseTag orders betas before rcs and filters other base versions', async () => {
+  const { selectPreviousPrereleaseTag } = await loadModule();
+
+  const tags = [
+    'v0.19.4-beta.1',
+    'v0.19.4-beta.3',
+    'v0.19.4-beta.2',
+    'v0.19.3-beta.9',
+    'v0.19.4-rc.1',
+    'not-a-tag',
+  ];
+
+  assert.equal(selectPreviousPrereleaseTag(tags, '0.19.4-beta.1'), null);
+  assert.equal(selectPreviousPrereleaseTag(tags, '0.19.4-beta.2'), 'v0.19.4-beta.1');
+  assert.equal(selectPreviousPrereleaseTag(tags, '0.19.4-beta.4'), 'v0.19.4-beta.3');
+  assert.equal(selectPreviousPrereleaseTag(tags, '0.19.4-rc.1'), 'v0.19.4-beta.3');
+  assert.equal(selectPreviousPrereleaseTag(tags, '0.19.4-rc.2'), 'v0.19.4-rc.1');
+  // Regenerating notes for an already-tagged version must not pick itself.
+  assert.equal(selectPreviousPrereleaseTag(tags, '0.19.4-beta.3'), 'v0.19.4-beta.2');
+  assert.equal(selectPreviousPrereleaseTag(['v0.19.3-beta.1'], '0.19.4-beta.2'), null);
+});
+
+test('writePrereleaseNotesForVersion adds a delta section generated from fragment diffs', async () => {
+  const { writePrereleaseNotesForVersion } = await loadModule();
+  const workspace = createWorkspace('prerelease-delta-section');
+  const projectRoot = path.join(workspace, 'SubMiner');
+
+  fs.mkdirSync(path.join(projectRoot, 'changes'), { recursive: true });
+  fs.writeFileSync(
+    path.join(projectRoot, 'package.json'),
+    JSON.stringify({ name: 'subminer', version: '0.12.0-beta.2' }, null, 2),
+    'utf8',
+  );
+  fs.writeFileSync(
+    path.join(projectRoot, 'changes', '001.md'),
+    ['type: fixed', 'area: overlay', '', '- Fixed overlay focus and macOS helper.'].join('\n'),
+    'utf8',
+  );
+
+  try {
+    const stub = recordingRunClaude((input) =>
+      input.includes('MODIFIED FRAGMENT')
+        ? '- Fixed the macOS helper deployment target for older systems.'
+        : '### Fixed\n- Overlay: cumulative fixed entry.',
+    );
+    const outputPath = writePrereleaseNotesForVersion({
+      cwd: projectRoot,
+      version: '0.12.0-beta.2',
+      deps: {
+        runClaude: stub.runClaude,
+        listPrereleaseTags: () => ['v0.12.0-beta.1'],
+        resolveFragmentDelta: (_cwd, previousTag) => {
+          assert.equal(previousTag, 'v0.12.0-beta.1');
+          return [
+            {
+              path: 'changes/002.md',
+              status: 'added',
+              after: 'type: fixed\narea: macos\n\n- Fixed helper deployment target.',
+            },
+            {
+              path: 'changes/001.md',
+              status: 'modified',
+              before: '- Fixed overlay focus.',
+              after: '- Fixed overlay focus and macOS helper.',
+            },
+            {
+              path: 'changes/003.md',
+              status: 'deleted',
+              before: 'type: added\narea: stats\n\n- Reverted experimental stats view.',
+            },
+          ];
+        },
+      },
+    });
+
+    assert.equal(stub.calls.length, 2, 'delta and cumulative polish are separate Claude calls');
+    const deltaPrompt = stub.calls[0]!.input;
+    assert.match(deltaPrompt, /ADDED FRAGMENT changes\/002\.md/);
+    assert.match(deltaPrompt, /MODIFIED FRAGMENT changes\/001\.md/);
+    assert.match(deltaPrompt, /BEFORE:\n- Fixed overlay focus\./);
+    assert.match(deltaPrompt, /AFTER:\n- Fixed overlay focus and macOS helper\./);
+    assert.match(deltaPrompt, /DELETED FRAGMENT changes\/003\.md/);
+    assert.match(deltaPrompt, /If the edit is editorial/);
+    assert.match(deltaPrompt, /removed or reverted/);
+    assert.match(deltaPrompt, /No user-facing changes since v0\.12\.0-beta\.1\./);
+    assert.equal(modeFromPrompt(stub.calls[1]!.input), 'release-notes');
+
+    const prereleaseNotes = fs.readFileSync(outputPath, 'utf8');
+    assert.match(
+      prereleaseNotes,
+      /<!-- prerelease-version: 0\.12\.0-beta\.2; since: v0\.12\.0-beta\.1 -->/,
+    );
+    const deltaIndex = prereleaseNotes.indexOf('## Changes since v0.12.0-beta.1');
+    const highlightsIndex = prereleaseNotes.indexOf('## Highlights');
+    assert.ok(deltaIndex !== -1, 'delta section heading should be present');
+    assert.ok(deltaIndex < highlightsIndex, 'delta section should precede Highlights');
+    assert.match(prereleaseNotes, /- Fixed the macOS helper deployment target for older systems\./);
+  } finally {
+    fs.rmSync(workspace, { recursive: true, force: true });
+  }
+});
+
+test('writePrereleaseNotesForVersion renders a fallback delta line when no fragments changed', async () => {
+  const { writePrereleaseNotesForVersion } = await loadModule();
+  const workspace = createWorkspace('prerelease-empty-delta');
+  const projectRoot = path.join(workspace, 'SubMiner');
+
+  fs.mkdirSync(path.join(projectRoot, 'changes'), { recursive: true });
+  fs.writeFileSync(
+    path.join(projectRoot, 'package.json'),
+    JSON.stringify({ name: 'subminer', version: '0.12.0-beta.3' }, null, 2),
+    'utf8',
+  );
+  fs.writeFileSync(
+    path.join(projectRoot, 'changes', '001.md'),
+    ['type: fixed', 'area: overlay', '', '- Fixed overlay focus.'].join('\n'),
+    'utf8',
+  );
+
+  try {
+    const stub = defaultStubClaude();
+    const outputPath = writePrereleaseNotesForVersion({
+      cwd: projectRoot,
+      version: '0.12.0-beta.3',
+      deps: {
+        runClaude: stub.runClaude,
+        listPrereleaseTags: () => ['v0.12.0-beta.1', 'v0.12.0-beta.2'],
+        resolveFragmentDelta: () => [],
+      },
+    });
+
+    assert.equal(stub.calls.length, 1, 'empty delta must not spend a Claude call');
+    const prereleaseNotes = fs.readFileSync(outputPath, 'utf8');
+    assert.match(
+      prereleaseNotes,
+      /## Changes since v0\.12\.0-beta\.2\n\n- No changelog fragment changes since v0\.12\.0-beta\.2; this build contains packaging or internal-only updates\./,
+    );
+  } finally {
+    fs.rmSync(workspace, { recursive: true, force: true });
+  }
+});
+
+test('writePrereleaseNotesForVersion rejects non-bullet delta output from Claude', async () => {
+  const { writePrereleaseNotesForVersion } = await loadModule();
+  const workspace = createWorkspace('prerelease-delta-invalid-output');
+  const projectRoot = path.join(workspace, 'SubMiner');
+
+  fs.mkdirSync(path.join(projectRoot, 'changes'), { recursive: true });
+  fs.writeFileSync(
+    path.join(projectRoot, 'package.json'),
+    JSON.stringify({ name: 'subminer', version: '0.12.0-beta.2' }, null, 2),
+    'utf8',
+  );
+  fs.writeFileSync(
+    path.join(projectRoot, 'changes', '001.md'),
+    ['type: fixed', 'area: overlay', '', '- Fixed overlay focus.'].join('\n'),
+    'utf8',
+  );
+
+  try {
+    const stub = recordingRunClaude(() => 'Here are the changes:\n- One change.');
+    assert.throws(
+      () =>
+        writePrereleaseNotesForVersion({
+          cwd: projectRoot,
+          version: '0.12.0-beta.2',
+          deps: {
+            runClaude: stub.runClaude,
+            listPrereleaseTags: () => ['v0.12.0-beta.1'],
+            resolveFragmentDelta: () => [
+              { path: 'changes/001.md', status: 'added', after: '- Fixed overlay focus.' },
+            ],
+          },
+        }),
+      /delta output must contain only Markdown bullets/,
+    );
+  } finally {
+    fs.rmSync(workspace, { recursive: true, force: true });
+  }
+});
+
+test('writePrereleaseNotesForVersion strips the stale delta section from the reused baseline', async () => {
+  const { writePrereleaseNotesForVersion } = await loadModule();
+  const workspace = createWorkspace('prerelease-reuse-strips-delta');
+  const projectRoot = path.join(workspace, 'SubMiner');
+  const existingNotes = [
+    '> This is a prerelease build for testing. Stable changelog and docs-site updates remain pending until the final stable release.',
+    '',
+    '<!-- prerelease-version: 0.12.0-beta.2; since: v0.12.0-beta.1 -->',
+    '',
+    '## Changes since v0.12.0-beta.1',
+    '',
+    '- Stale beta-to-beta delta bullet.',
+    '',
+    '## Highlights',
+    '### Added',
+    '- Overlay: Previous beta entry.',
+    '',
+    '## Installation',
+    '',
+    'See the README and docs/installation guide for full setup steps.',
+    '',
+  ].join('\n');
+
+  fs.mkdirSync(path.join(projectRoot, 'changes'), { recursive: true });
+  fs.mkdirSync(path.join(projectRoot, 'release'), { recursive: true });
+  fs.writeFileSync(
+    path.join(projectRoot, 'package.json'),
+    JSON.stringify({ name: 'subminer', version: '0.12.0-beta.3' }, null, 2),
+    'utf8',
+  );
+  fs.writeFileSync(path.join(projectRoot, 'release', 'prerelease-notes.md'), existingNotes, 'utf8');
+  fs.writeFileSync(
+    path.join(projectRoot, 'changes', '001.md'),
+    ['type: added', 'area: overlay', '', '- Added overlay coverage.'].join('\n'),
+    'utf8',
+  );
+
+  try {
+    const stub = defaultStubClaude();
+    writePrereleaseNotesForVersion({
+      cwd: projectRoot,
+      version: '0.12.0-beta.3',
+      deps: {
+        runClaude: stub.runClaude,
+        listPrereleaseTags: () => [],
+        resolveFragmentDelta: () => [],
+      },
+    });
+
+    assert.equal(stub.calls.length, 1);
+    const prompt = stub.calls[0]!.input;
+    assert.match(prompt, /EXISTING PRERELEASE NOTES/);
+    assert.match(prompt, /Overlay: Previous beta entry\./);
+    assert.doesNotMatch(prompt, /Stale beta-to-beta delta bullet\./);
+    assert.doesNotMatch(prompt, /## Changes since /);
+  } finally {
+    fs.rmSync(workspace, { recursive: true, force: true });
+  }
+});
+
+test('verifyPrereleaseNotesMatchVersion accepts matching notes and rejects stale or legacy markers', async () => {
+  const { verifyPrereleaseNotesMatchVersion } = await loadModule();
+  const workspace = createWorkspace('verify-prerelease-notes');
+  const projectRoot = path.join(workspace, 'SubMiner');
+  const notesPath = path.join(projectRoot, 'release', 'prerelease-notes.md');
+
+  fs.mkdirSync(path.join(projectRoot, 'release'), { recursive: true });
+  fs.writeFileSync(
+    path.join(projectRoot, 'package.json'),
+    JSON.stringify({ name: 'subminer', version: '0.12.0-beta.2' }, null, 2),
+    'utf8',
+  );
+
+  try {
+    assert.throws(
+      () => verifyPrereleaseNotesMatchVersion({ cwd: projectRoot, version: '0.12.0-beta.2' }),
+      /Missing .*prerelease-notes\.md/,
+    );
+
+    fs.writeFileSync(
+      notesPath,
+      '<!-- prerelease-version: 0.12.0-beta.2; since: v0.12.0-beta.1 -->\n\n## Highlights\n',
+      'utf8',
+    );
+    verifyPrereleaseNotesMatchVersion({ cwd: projectRoot, version: '0.12.0-beta.2' });
+    verifyPrereleaseNotesMatchVersion({ cwd: projectRoot, version: 'v0.12.0-beta.2' });
+
+    fs.writeFileSync(
+      notesPath,
+      '<!-- prerelease-version: 0.12.0-beta.1 -->\n\n## Highlights\n',
+      'utf8',
+    );
+    assert.throws(
+      () => verifyPrereleaseNotesMatchVersion({ cwd: projectRoot, version: '0.12.0-beta.2' }),
+      /generated for 0\.12\.0-beta\.1 but this release is 0\.12\.0-beta\.2/,
+    );
+
+    fs.writeFileSync(
+      notesPath,
+      '<!-- prerelease-base-version: 0.12.0 -->\n\n## Highlights\n',
+      'utf8',
+    );
+    assert.throws(
+      () => verifyPrereleaseNotesMatchVersion({ cwd: projectRoot, version: '0.12.0-beta.2' }),
+      /missing or legacy prerelease-version marker/,
+    );
+  } finally {
+    fs.rmSync(workspace, { recursive: true, force: true });
+  }
+});
+
+test('default git tag listing and fragment delta resolution work against a real repository', async () => {
+  const { writePrereleaseNotesForVersion } = await loadModule();
+  const workspace = createWorkspace('prerelease-git-defaults');
+  const projectRoot = path.join(workspace, 'SubMiner');
+  const git = (...args: string[]): void => {
+    execFileSync('git', args, { cwd: projectRoot, stdio: 'ignore' });
+  };
+
+  fs.mkdirSync(path.join(projectRoot, 'changes'), { recursive: true });
+  fs.writeFileSync(
+    path.join(projectRoot, 'package.json'),
+    JSON.stringify({ name: 'subminer', version: '0.11.3-beta.1' }, null, 2),
+    'utf8',
+  );
+  fs.writeFileSync(
+    path.join(projectRoot, 'changes', 'kept.md'),
+    ['type: added', 'area: overlay', '', '- Kept change.'].join('\n'),
+    'utf8',
+  );
+  fs.writeFileSync(
+    path.join(projectRoot, 'changes', 'edited.md'),
+    ['type: fixed', 'area: launcher', '', '- Original launcher fix.'].join('\n'),
+    'utf8',
+  );
+  fs.writeFileSync(
+    path.join(projectRoot, 'changes', 'removed.md'),
+    ['type: added', 'area: stats', '', '- Reverted stats change.'].join('\n'),
+    'utf8',
+  );
+
+  try {
+    git('init', '--quiet');
+    git('-c', 'user.email=test@example.com', '-c', 'user.name=Test', 'add', '.');
+    git('-c', 'user.email=test@example.com', '-c', 'user.name=Test', 'commit', '-m', 'beta.1');
+    git('tag', 'v0.11.3-beta.1');
+
+    fs.writeFileSync(
+      path.join(projectRoot, 'changes', 'edited.md'),
+      ['type: fixed', 'area: launcher', '', '- Broader launcher fix.'].join('\n'),
+      'utf8',
+    );
+    fs.rmSync(path.join(projectRoot, 'changes', 'removed.md'));
+    fs.writeFileSync(
+      path.join(projectRoot, 'changes', 'new.md'),
+      ['type: added', 'area: anki', '', '- New anki change.'].join('\n'),
+      'utf8',
+    );
+    fs.writeFileSync(
+      path.join(projectRoot, 'package.json'),
+      JSON.stringify({ name: 'subminer', version: '0.11.3-beta.2' }, null, 2),
+      'utf8',
+    );
+
+    const stub = recordingRunClaude((input) =>
+      input.includes('PREVIOUS_TAG:') ? '- Delta bullet.' : defaultPolishedBody(input),
+    );
+    writePrereleaseNotesForVersion({
+      cwd: projectRoot,
+      version: '0.11.3-beta.2',
+      deps: { runClaude: stub.runClaude },
+    });
+
+    assert.equal(stub.calls.length, 2);
+    const deltaPrompt = stub.calls[0]!.input;
+    assert.match(deltaPrompt, /PREVIOUS_TAG: v0\.11\.3-beta\.1/);
+    assert.match(deltaPrompt, /ADDED FRAGMENT changes\/new\.md/);
+    assert.match(deltaPrompt, /- New anki change\./);
+    assert.match(deltaPrompt, /MODIFIED FRAGMENT changes\/edited\.md/);
+    assert.match(deltaPrompt, /- Original launcher fix\./);
+    assert.match(deltaPrompt, /- Broader launcher fix\./);
+    assert.match(deltaPrompt, /DELETED FRAGMENT changes\/removed\.md/);
+    assert.match(deltaPrompt, /- Reverted stats change\./);
+    assert.doesNotMatch(deltaPrompt, /kept\.md/);
+  } finally {
+    fs.rmSync(workspace, { recursive: true, force: true });
+  }
+});
diff --git a/scripts/build-changelog.ts b/scripts/build-changelog.ts
index df6ca317..2eba9bf9 100644
--- a/scripts/build-changelog.ts
+++ b/scripts/build-changelog.ts
@@ -18,6 +18,15 @@ type Contribution = {
 // and the GitHub API.
 type ResolveContributions = (fragmentPaths: string[], cwd: string) => Contribution[];
 
+// One changelog fragment's change between the previous prerelease tag and the
+// working tree. `before` is the content at the tag, `after` the current content.
+export type FragmentDeltaEntry = {
+  path: string;
+  status: 'added' | 'modified' | 'deleted';
+  before?: string;
+  after?: string;
+};
+
 type ChangelogFsDeps = {
   existsSync?: (candidate: string) => boolean;
   mkdirSync?: (candidate: string, options: { recursive: true }) => void;
@@ -28,6 +37,8 @@ type ChangelogFsDeps = {
   log?: (message: string) => void;
   runClaude?: RunClaude;
   resolveContributions?: ResolveContributions;
+  listPrereleaseTags?: (cwd: string, baseVersion: string) => string[];
+  resolveFragmentDelta?: (cwd: string, previousTag: string) => FragmentDeltaEntry[];
 };
 
 type PolishMode = 'changelog' | 'release-notes';
@@ -103,16 +114,57 @@ function resolvePrereleaseBaseVersion(version: string): string {
   return match[1]!;
 }
 
-function renderPrereleaseBaseVersionMarker(version: string): string {
-  return `<!-- prerelease-base-version: ${resolvePrereleaseBaseVersion(version)} -->`;
+// The marker records which exact prerelease the committed notes were generated
+// for (and which prior tag the delta section compares against), so CI can
+// reject notes that were prepared for a different beta/RC.
+function renderPrereleaseVersionMarker(version: string, previousTag: string | null): string {
+  const since = previousTag ? `; since: ${previousTag}` : '';
+  return `<!-- prerelease-version: ${normalizeVersion(version)}${since} -->`;
 }
 
+export function extractPrereleaseVersionMarker(notes: string): string | null {
+  return (
+    /<!--\s*prerelease-version:\s*(\d+\.\d+\.\d+-(?:beta|rc)\.\d+)(?:;\s*since:\s*\S+)?\s*-->/u.exec(
+      notes,
+    )?.[1] ?? null
+  );
+}
+
+// Legacy marker written before the per-version marker existed. Still accepted
+// when deciding whether existing notes can seed the cumulative baseline.
 function extractPrereleaseBaseVersionMarker(notes: string): string | null {
+  const fullVersion = extractPrereleaseVersionMarker(notes);
+  if (fullVersion) {
+    return resolvePrereleaseBaseVersion(fullVersion);
+  }
   return /<!--\s*prerelease-base-version:\s*(\d+\.\d+\.\d+)\s*-->/u.exec(notes)?.[1] ?? null;
 }
 
+const DELTA_SECTION_HEADING_PREFIX = '## Changes since ';
+
+// Removes the previous run's "Changes since" section so the cumulative baseline
+// fed back to Claude never carries a stale beta-to-beta delta.
+function stripDeltaSection(notes: string): string {
+  const lines = notes.split(/\r?\n/);
+  const start = lines.findIndex((line) => line.startsWith(DELTA_SECTION_HEADING_PREFIX));
+  if (start === -1) {
+    return notes;
+  }
+  let end = lines.length;
+  for (let index = start + 1; index < lines.length; index += 1) {
+    if (lines[index]!.startsWith('## ')) {
+      end = index;
+      break;
+    }
+  }
+  return [...lines.slice(0, start), ...lines.slice(end)].join('\n');
+}
+
 function stripPrereleaseMetadata(notes: string): string {
-  return notes.replace(/<!--\s*prerelease-base-version:\s*\d+\.\d+\.\d+\s*-->\s*/u, '').trim();
+  return notes
+    .replace(/<!--\s*prerelease-version:[^>]*-->\s*/u, '')
+    .replace(/<!--\s*prerelease-base-version:\s*\d+\.\d+\.\d+\s*-->\s*/u, '')
+    .trim();
 }
 
 function resolveReusablePrereleaseNotes(notes: string, version: string): string | undefined {
@@ -120,7 +172,124 @@ function resolveReusablePrereleaseNotes(notes: string, version: string): string
   if (existingBaseVersion !== resolvePrereleaseBaseVersion(version)) {
     return undefined;
   }
-  return stripPrereleaseMetadata(notes);
+  return stripPrereleaseMetadata(stripDeltaSection(notes));
+}
+
+type ParsedPrereleaseTag = {
+  tag: string;
+  base: string;
+  channel: 'beta' | 'rc';
+  iteration: number;
+};
+
+function parsePrereleaseTag(tag: string): ParsedPrereleaseTag | null {
+  const match = /^v?(\d+\.\d+\.\d+)-(beta|rc)\.(\d+)$/u.exec(tag.trim());
+  if (!match) {
+    return null;
+  }
+  return {
+    tag: tag.trim(),
+    base: match[1]!,
+    channel: match[2] as 'beta' | 'rc',
+    iteration: Number.parseInt(match[3]!, 10),
+  };
+}
+
+// Semver prerelease order: every beta sorts before every rc, then numerically.
+function comparePrereleaseTags(a: ParsedPrereleaseTag, b: ParsedPrereleaseTag): number {
+  if (a.channel !== b.channel) {
+    return a.channel === 'beta' ? -1 : 1;
+  }
+  return a.iteration - b.iteration;
+}
+
+// Picks the newest prerelease tag for the same base version that strictly
+// precedes the version being released. Returns null for the first prerelease.
+export function selectPreviousPrereleaseTag(tags: string[], version: string): string | null {
+  const current = parsePrereleaseTag(normalizeVersion(version));
+  if (!current) {
+    return null;
+  }
+
+  const candidates = tags
+    .map(parsePrereleaseTag)
+    .filter((parsed): parsed is ParsedPrereleaseTag => parsed !== null)
+    .filter((parsed) => parsed.base === current.base)
+    .filter((parsed) => comparePrereleaseTags(parsed, current) < 0)
+    .sort(comparePrereleaseTags);
+
+  return candidates[candidates.length - 1]?.tag ?? null;
+}
+
+function defaultListPrereleaseTags(cwd: string, baseVersion: string): string[] {
+  return execFileSync('git', ['tag', '--list', `v${baseVersion}-beta.*`, `v${baseVersion}-rc.*`], {
+    cwd,
+    encoding: 'utf8',
+  })
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean);
+}
+
+// Diffs changes/*.md between the previous prerelease tag and the working tree.
+// Renamed fragments are treated as modifications of the new path.
+//
+// Like every other path in this script, git paths are resolved against `cwd`,
+// which is the project root and also the repository root. Callers that point
+// `cwd` elsewhere already fail earlier and loudly, when package.json and
+// changes/ come back missing.
+function defaultResolveFragmentDelta(cwd: string, previousTag: string): FragmentDeltaEntry[] {
+  const output = execFileSync(
+    'git',
+    ['diff', '--name-status', '--find-renames', previousTag, '--', 'changes'],
+    { cwd, encoding: 'utf8' },
+  );
+  const showAtTag = (fragmentPath: string): string =>
+    execFileSync('git', ['show', `${previousTag}:${fragmentPath}`], { cwd, encoding: 'utf8' });
+  const readCurrent = (fragmentPath: string): string =>
+    fs.readFileSync(path.join(cwd, fragmentPath), 'utf8');
+
+  const entries: FragmentDeltaEntry[] = [];
+  for (const line of output.split(/\r?\n/)) {
+    if (!line.trim()) {
+      continue;
+    }
+    const [status = '', ...paths] = line.split('\t');
+    const oldPath = paths[0] ?? '';
+    const newPath = paths[paths.length - 1] ?? '';
+    if (!isFragmentPath(newPath) && !isFragmentPath(oldPath)) {
+      continue;
+    }
+
+    if (status.startsWith('A')) {
+      entries.push({ path: newPath, status: 'added', after: readCurrent(newPath) });
+    } else if (status.startsWith('D')) {
+      entries.push({ path: oldPath, status: 'deleted', before: showAtTag(oldPath) });
+    } else if (status.startsWith('M') || status.startsWith('R')) {
+      entries.push({
+        path: newPath,
+        status: 'modified',
+        before: showAtTag(oldPath),
+        after: readCurrent(newPath),
+      });
+    }
+  }
+
+  // git diff misses fragments that exist only in the working tree; treat
+  // untracked fragments as additions so a pre-commit run still sees them.
+  const untracked = execFileSync(
+    'git',
+    ['ls-files', '--others', '--exclude-standard', '--', 'changes'],
+    { cwd, encoding: 'utf8' },
+  )
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter((candidate) => candidate && isFragmentPath(candidate));
+  for (const fragmentPath of untracked) {
+    entries.push({ path: fragmentPath, status: 'added', after: readCurrent(fragmentPath) });
+  }
+
+  return entries;
 }
 
 function verifyRequestedVersionMatchesPackageVersion(
@@ -267,7 +436,9 @@ function readChangeFragments(cwd: string, deps?: ChangelogFsDeps): ChangeFragmen
 const CLAUDE_CLI_ARGS = [
   '-p',
   '--model',
-  'sonnet',
+  'opus',
+  '--effort',
+  'medium',
   '--permission-mode',
   'bypassPermissions',
   '--output-format',
@@ -311,10 +482,15 @@ You will receive a list of FRAGMENT entries below. Each fragment has metadata (t
    - Be merged with related bullets when possible. If five fragments all touch Windows overlay z-order/focus/restore, write one or two bullets that summarize the overall improvement instead of five.
    - Drop bullets that only describe PR housekeeping, CodeRabbit follow-ups, or test-only changes that don't affect users.
    - Preserve the substance of breaking changes that remain breaking after applying the Release Outcome Rules. Do not soften or omit them.
-5. In MODE: changelog, each item may be a conventional single-level bullet, e.g. "- Playlist Browser: Adds faster saved-show browsing."
-6. In MODE: release-notes, use short top-level change bullets with two or three nested bullets when an item needs explanation.
-   Nested bullets should cover the change, user benefit, and any user action or compatibility note when useful. Do not require the exact nested labels; natural phrasing is fine. Omit the action bullet when no action is needed.
+5. In both modes, split every item into one nested bullet per distinct change. Write a short bold name on the top-level bullet, then indent the details two spaces:
+   - **Playlist Browser**:
+     - Saved shows now open without rescanning the library.
+     - The picker remembers the last folder you browsed between launches.
+   Each nested bullet covers exactly one change, behavior, or user-visible outcome. Never stack several distinct changes into one long paragraph-shaped bullet.
+   Aim for two to five nested bullets per item. When an item genuinely has only one thing to say, put it inline on the top-level bullet ("- **Playlist Browser**: Saved shows now open without rescanning the library.") instead of emitting a single nested bullet.
    Keep nested bullets short, concrete, and readable by non-technical users. Avoid paragraph-style release-note bullets.
+   Bullets inside the Internal section may stay single-level.
+6. In MODE: release-notes, nested bullets should also cover user benefit and any user action or compatibility note when useful. Do not require the exact nested labels; natural phrasing is fine. Omit the action bullet when no action is needed.
 7. Do not invent features. Every bullet must be grounded in the input fragments.
 8. Do not include the version heading (## v...) — that wrapper is added by the caller.
 
@@ -615,7 +791,7 @@ function polishFragmentsWithClaude(
     ? [
         '## Existing Prerelease Notes',
         '',
-        'The input includes EXISTING PRERELEASE NOTES before the fragment list. Existing prerelease notes are a baseline, not an immutable changelog. Reuse reviewed highlight bullets when they still describe the current outcome, but replace stale beta or RC wording when new fragments supersede it. Merge in only new or changed fragment material, and deduplicate instead of restating existing bullets. Output only the final highlights body using the section headings above; do not include the prerelease disclaimer, Installation, or Assets sections.',
+        'The input includes EXISTING PRERELEASE NOTES before the fragment list. Existing prerelease notes are a baseline, not an immutable changelog. Reuse reviewed highlight bullets when they still describe the current outcome, but replace stale beta or RC wording when new fragments supersede it. Merge in only new or changed fragment material, and deduplicate instead of restating existing bullets. Output only the final highlights body using the section headings above; do not include the prerelease disclaimer, any "Changes since" section, or the Installation or Assets sections.',
         '',
       ].join('\n')
     : '';
@@ -627,6 +803,75 @@ function polishFragmentsWithClaude(
   return validatePolishedOutput(output, mode, hasInternalFragments);
 }
 
+const DELTA_PROMPT_INSTRUCTIONS = `You are writing the "changes since the previous prerelease" section of a prerelease notes file for SubMiner, an Electron app for Japanese sentence mining.
+
+You will receive changelog fragment diffs between the previous prerelease tag and the current build. Fragments are engineer-written release-note sources; a fragment diff is a proxy for what changed, not proof of a behavior change.
+
+Rules:
+
+1. Output Markdown bullets ONLY. No headings, no preamble, no commentary. Every line must be a top-level "- " bullet or an indented nested bullet.
+2. Describe only what changed for users between the two prerelease builds, in user-facing language. Drop implementation jargon, file paths, and PR numbers.
+3. ADDED fragments describe changes that are new in this build; summarize them.
+4. MODIFIED fragments include BEFORE and AFTER content. Describe only the behavioral difference between them. If the edit is editorial (rewording, deduplication, reformatting, reconciling stale phrasing) with no user-visible behavior change, omit it entirely.
+5. DELETED fragments mean the described change was removed or reverted before this build; say so explicitly.
+6. Keep bullets short and concrete. Use nested bullets sparingly.
+7. Do not invent changes. Every bullet must be grounded in the diffs.
+8. If no bullet survives rules 2-5, output exactly this single line:
+   - No user-facing changes since PREVIOUS_TAG.
+
+The input begins below.
+
+`;
+
+function serializeFragmentDeltaForPrompt(
+  delta: FragmentDeltaEntry[],
+  version: string,
+  previousTag: string,
+): string {
+  const header = [`VERSION: ${version}`, `PREVIOUS_TAG: ${previousTag}`];
+  const blocks = delta.map((entry) => {
+    if (entry.status === 'added') {
+      return [`ADDED FRAGMENT ${entry.path}`, entry.after ?? ''].join('\n');
+    }
+    if (entry.status === 'deleted') {
+      return [`DELETED FRAGMENT ${entry.path}`, entry.before ?? ''].join('\n');
+    }
+    return [
+      `MODIFIED FRAGMENT ${entry.path}`,
+      'BEFORE:',
+      entry.before ?? '',
+      'AFTER:',
+      entry.after ?? '',
+    ].join('\n');
+  });
+  return [...header, '', ...blocks].join('\n\n');
+}
+
+function validateDeltaOutput(output: string): string {
+  const trimmed = output.trim();
+  if (!trimmed) {
+    throw new Error('claude returned empty output for the prerelease delta section.');
+  }
+  const invalidLine = trimmed.split(/\r?\n/).find((line) => line.trim() && !/^\s*- /.test(line));
+  if (invalidLine !== undefined) {
+    throw new Error(
+      `claude delta output must contain only Markdown bullets. Offending line:\n${invalidLine}`,
+    );
+  }
+  return trimmed;
+}
+
+function buildDeltaSectionWithClaude(
+  delta: FragmentDeltaEntry[],
+  options: { version: string; previousTag: string; deps?: ChangelogFsDeps },
+): string {
+  const runClaude = options.deps?.runClaude ?? defaultRunClaude;
+  const prompt =
+    DELTA_PROMPT_INSTRUCTIONS.replace('PREVIOUS_TAG', options.previousTag) +
+    serializeFragmentDeltaForPrompt(delta, options.version, options.previousTag);
+  return validateDeltaOutput(runClaude(prompt, CLAUDE_CLI_ARGS));
+}
+
 function stripDetailsBlocks(body: string): string {
   return body.replace(/<details>[\s\S]*?<\/details>\s*/gm, '').trim();
 }
@@ -709,15 +954,18 @@ function renderReleaseNotes(
     contributions?: Contribution[];
     contributorSections?: string[];
     metadata?: string[];
+    deltaSection?: string[];
   },
 ): string {
   const prefix = options?.disclaimer ? [options.disclaimer, ''] : [];
   const metadata = options?.metadata?.length ? [...options.metadata, ''] : [];
+  const deltaSection = options?.deltaSection?.length ? [...options.deltaSection, ''] : [];
   const contributorSections =
     options?.contributorSections ?? renderContributorsSections(options?.contributions ?? []);
   return [
     ...prefix,
     ...metadata,
+    ...deltaSection,
     '## Highlights',
     changes,
     '',
@@ -731,9 +979,12 @@ function renderReleaseNotes(
     '- Linux: `SubMiner.AppImage`',
     '- macOS: `SubMiner-*.dmg` and `SubMiner-*.zip`',
     '- Windows: `SubMiner-*.exe` and `SubMiner-*-win.zip`',
-    '- Optional extras: `subminer-assets.tar.gz` and the `subminer` launcher',
+    '- Optional extras: `subminer-assets.tar.gz`, the `subminer` launcher, and the Windows `subminer.cmd` launcher',
+    '- Bun corresponding source: `bun-v1.3.5-source.tar.gz` and its `.sha256` file',
     '',
-    'Note: the `subminer` wrapper script uses Bun (`#!/usr/bin/env bun`), so `bun` must be installed and on `PATH`.',
+    'Both launcher downloads use Bun included with the SubMiner app. Download `subminer` on Linux or macOS and `subminer.cmd` on Windows.',
+    '',
+    'The app bundles an unmodified Bun 1.3.5 runtime. Bun is MIT licensed and statically links JavaScriptCore (LGPL 2.0) and TinyCC (LGPL 2.1). License texts and third-party notices ship inside the app under `resources/bun/licenses`, and the source archive above contains the matching Bun, WebKit, and dependency sources for relinking.',
     '',
   ].join('\n');
 }
@@ -748,6 +999,7 @@ function writeReleaseNotesFile(
     contributions?: Contribution[];
     contributorSections?: string[];
     metadata?: string[];
+    deltaSection?: string[];
   },
 ): string {
   const mkdirSync = deps?.mkdirSync ?? fs.mkdirSync;
@@ -1079,6 +1331,26 @@ export function writePrereleaseNotesForVersion(options?: ChangelogOptions): stri
     throw new Error('No changelog fragments found in changes/.');
   }
 
+  const listPrereleaseTags = options?.deps?.listPrereleaseTags ?? defaultListPrereleaseTags;
+  const previousTag = selectPreviousPrereleaseTag(
+    listPrereleaseTags(cwd, resolvePrereleaseBaseVersion(version)),
+    version,
+  );
+
+  // Later betas/RCs get a "Changes since <previous tag>" section on top of the
+  // cumulative Highlights, generated from the fragment diff between the
+  // previous prerelease tag and the working tree.
+  let deltaSection: string[] = [];
+  if (previousTag) {
+    const resolveFragmentDelta = options?.deps?.resolveFragmentDelta ?? defaultResolveFragmentDelta;
+    const delta = resolveFragmentDelta(cwd, previousTag);
+    const deltaBody =
+      delta.length === 0
+        ? `- No changelog fragment changes since ${previousTag}; this build contains packaging or internal-only updates.`
+        : buildDeltaSectionWithClaude(delta, { version, previousTag, deps: options?.deps });
+    deltaSection = [`${DELTA_SECTION_HEADING_PREFIX}${previousTag}`, '', deltaBody];
+  }
+
   const prereleaseNotesPath = path.join(cwd, PRERELEASE_NOTES_PATH);
   const existingReleaseNotes = existsSync(prereleaseNotesPath)
     ? resolveReusablePrereleaseNotes(readFileSync(prereleaseNotesPath, 'utf8'), version)
@@ -1095,10 +1367,41 @@ export function writePrereleaseNotesForVersion(options?: ChangelogOptions): stri
       '> This is a prerelease build for testing. Stable changelog and docs-site updates remain pending until the final stable release.',
     outputPath: PRERELEASE_NOTES_PATH,
     contributions,
-    metadata: [renderPrereleaseBaseVersionMarker(version)],
+    metadata: [renderPrereleaseVersionMarker(version, previousTag)],
+    deltaSection,
   });
 }
 
+// CI gate: the committed prerelease notes must carry a marker generated for
+// exactly the version being tagged, so stale beta.N-1 notes can't ship.
+export function verifyPrereleaseNotesMatchVersion(options?: ChangelogOptions): void {
+  verifyRequestedVersionMatchesPackageVersion(options ?? {});
+
+  const cwd = options?.cwd ?? process.cwd();
+  const existsSync = options?.deps?.existsSync ?? fs.existsSync;
+  const readFileSync = options?.deps?.readFileSync ?? fs.readFileSync;
+  const version = resolveVersion(options ?? {});
+  if (!isSupportedPrereleaseVersion(version)) {
+    throw new Error(
+      `Unsupported prerelease version (${version}). Expected x.y.z-beta.N or x.y.z-rc.N.`,
+    );
+  }
+
+  const prereleaseNotesPath = path.join(cwd, PRERELEASE_NOTES_PATH);
+  if (!existsSync(prereleaseNotesPath)) {
+    throw new Error(
+      `Missing ${prereleaseNotesPath}. Run 'bun run changelog:prerelease-notes --version ${version}' and commit the file before tagging.`,
+    );
+  }
+
+  const markerVersion = extractPrereleaseVersionMarker(readFileSync(prereleaseNotesPath, 'utf8'));
+  if (markerVersion !== version) {
+    throw new Error(
+      `release/prerelease-notes.md was generated for ${markerVersion ?? 'an unknown version (missing or legacy prerelease-version marker)'} but this release is ${version}. Rerun 'bun run changelog:prerelease-notes --version ${version}' and commit the result.`,
+    );
+  }
+}
+
 function parseCliArgs(argv: string[]): {
   baseRef?: string;
   cwd?: string;
@@ -1206,6 +1509,11 @@ function main(): void {
     return;
   }
 
+  if (command === 'check-prerelease-notes') {
+    verifyPrereleaseNotesMatchVersion(options);
+    return;
+  }
+
   if (command === 'docs') {
     generateDocsChangelog(options);
     return;
diff --git a/scripts/build-launcher.ts b/scripts/build-launcher.ts
new file mode 100644
index 00000000..ff868a85
--- /dev/null
+++ b/scripts/build-launcher.ts
@@ -0,0 +1,54 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import packageJson from '../package.json';
+import { posixLauncherBootstrapContent } from '../src/main/runtime/posix-launcher-bootstrap';
+import { windowsLauncherBootstrapContent } from '../src/main/runtime/windows-launcher-bootstrap';
+
+const outputDirectory = path.join(process.cwd(), 'dist', 'launcher');
+
+function bundle(options: {
+  entrypoint: string;
+  outfile: string;
+  target: 'bun' | 'node';
+  format?: 'cjs';
+  banner?: string;
+}): void {
+  const args = [
+    'build',
+    options.entrypoint,
+    `--outfile=${options.outfile}`,
+    `--target=${options.target}`,
+    '--packages=bundle',
+  ];
+  if (options.format) args.push(`--format=${options.format}`);
+  if (options.banner) args.push(`--banner=${options.banner}`);
+  execFileSync(process.execPath, args, { stdio: 'inherit' });
+}
+
+fs.mkdirSync(outputDirectory, { recursive: true });
+
+bundle({
+  entrypoint: path.join(process.cwd(), 'launcher', 'main.ts'),
+  outfile: path.join(outputDirectory, 'subminer.js'),
+  target: 'bun',
+  banner: '#!/usr/bin/env bun',
+});
+bundle({
+  entrypoint: path.join(process.cwd(), 'src', 'main', 'runtime', 'prepare-launcher-runtime.ts'),
+  outfile: path.join(outputDirectory, 'prepare.cjs'),
+  target: 'node',
+  format: 'cjs',
+});
+
+const posixLauncherPath = path.join(outputDirectory, 'subminer');
+fs.writeFileSync(posixLauncherPath, posixLauncherBootstrapContent(), { mode: 0o755 });
+fs.chmodSync(posixLauncherPath, 0o755);
+fs.writeFileSync(
+  path.join(outputDirectory, 'subminer.cmd'),
+  windowsLauncherBootstrapContent(),
+  'utf8',
+);
+fs.writeFileSync(path.join(outputDirectory, 'version'), `${packageJson.version}\n`, 'utf8');
+
+console.log(`Built launcher runtime artifacts in ${outputDirectory}`);
diff --git a/scripts/build-macos-helper.sh b/scripts/build-macos-helper.sh
deleted file mode 100755
index 4f66a4b7..00000000
--- a/scripts/build-macos-helper.sh
+++ /dev/null
@@ -1,54 +0,0 @@
-#!/bin/bash
-# Build macOS window tracking helper binary
-
-set -e
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-SWIFT_SOURCE="$SCRIPT_DIR/get-mpv-window-macos.swift"
-OUTPUT_DIR="$SCRIPT_DIR/../dist/scripts"
-OUTPUT_BINARY="$OUTPUT_DIR/get-mpv-window-macos"
-OUTPUT_SOURCE_COPY="$OUTPUT_DIR/get-mpv-window-macos.swift"
-
-fallback_to_source() {
-  echo "Falling back to source fallback: $OUTPUT_SOURCE_COPY"
-  mkdir -p "$OUTPUT_DIR"
-  cp "$SWIFT_SOURCE" "$OUTPUT_SOURCE_COPY"
-}
-
-build_swift_helper() {
-  echo "Compiling macOS window tracking helper..."
-  if ! command -v swiftc >/dev/null 2>&1; then
-    echo "swiftc not found in PATH; skipping compilation."
-    return 1
-  fi
-
-  if ! swiftc -O "$SWIFT_SOURCE" -o "$OUTPUT_BINARY"; then
-    return 1
-  fi
-
-  chmod +x "$OUTPUT_BINARY"
-  echo "✓ Built $OUTPUT_BINARY"
-  return 0
-}
-
-# Optional skip flag for non-macOS CI/dev environments
-if [[ "${SUBMINER_SKIP_MACOS_HELPER_BUILD:-}" == "1" ]]; then
-  echo "Skipping macOS helper build (SUBMINER_SKIP_MACOS_HELPER_BUILD=1)"
-  fallback_to_source
-  exit 0
-fi
-
-# Only build on macOS
-if [[ "$(uname)" != "Darwin" ]]; then
-  echo "Skipping macOS helper build (not on macOS)"
-  fallback_to_source
-  exit 0
-fi
-
-# Create output directory
-mkdir -p "$OUTPUT_DIR"
-
-# Compile Swift script to binary, fallback to source if unavailable or compilation fails
-if ! build_swift_helper; then
-  fallback_to_source
-fi
diff --git a/scripts/build-versioned-docs.ts b/scripts/build-versioned-docs.ts
index 012de33f..a6bbf24f 100644
--- a/scripts/build-versioned-docs.ts
+++ b/scripts/build-versioned-docs.ts
@@ -1,49 +1,52 @@
 import { spawnSync } from 'node:child_process';
-import { createHash } from 'node:crypto';
 import {
   cpSync,
   existsSync,
   lstatSync,
   mkdirSync,
-  readFileSync,
   readdirSync,
-  readlinkSync,
   rmSync,
   symlinkSync,
   writeFileSync,
 } from 'node:fs';
 import { join, resolve } from 'node:path';
 import {
-  collectSharedAssetPaths,
-  dedupeVersionedPublicAssets,
-  pruneArchiveCacheGenerations,
-} from './docs-versioned-assets';
+  archiveStoreEnvFromProcess,
+  createArchiveStore,
+  type DocsArchiveStore,
+} from './docs-archive-store';
+import { collectSharedAssetPaths, dedupeVersionedPublicAssets } from './docs-versioned-assets';
 import {
   buildVersionManifest,
+  renderVersionsPage,
   stableTagsWithDocs,
-  versionArchiveCacheKey,
-  versionArchiveCacheName,
   versionOutputPath,
   versionPath,
 } from './docs-versioning';
 
+// Assembles the Cloudflare Pages deployment: latest stable at `/` and development docs
+// at `/main/`. Stable archives under `/v/<version>/` are built once, uploaded to R2, and
+// never rebuilt unless requested; this script only fills in archives R2 is missing.
+//
+// Flags:
+//   --require-archives           fail instead of skipping archive sync without R2 credentials
+//   --rebuild-archives=<list>    comma-separated tags (or `all`) to rebuild even if present
+
 const repoRoot = resolve(__dirname, '..');
 const currentDocsSite = join(repoRoot, 'docs-site');
 const buildRoot = join(repoRoot, '.tmp/docs-versioned-build');
 const aggregateOutDir = join(repoRoot, '.tmp/docs-versioned-site');
-const archiveCacheRoot = join(repoRoot, '.tmp/docs-versioned-archive-cache');
+const archiveOutRoot = join(repoRoot, '.tmp/docs-versioned-archives');
 const maxCloudflareFiles = 20_000;
 const maxCloudflareFileBytes = 25 * 1024 * 1024;
 
-// Cloudflare Pages header rules for the whole deployment. Mirrors the `noindex,follow`
-// meta tag the non-root channels emit, so the duplicate trees stay out of the index
-// even for responses a crawler takes without parsing the HTML.
+// Cloudflare Pages header rules for the static deployment. Mirrors the `noindex,follow`
+// meta tag the `main` channel emits, so the duplicate tree stays out of the index even
+// for responses a crawler takes without parsing the HTML. `/v/*` is served by the
+// archive Pages Function, which sets the same header itself.
 const deployHeaders = `# Generated by scripts/build-versioned-docs.ts. Do not edit by hand.
 /main/*
   X-Robots-Tag: noindex, follow
-
-/v/*
-  X-Robots-Tag: noindex, follow
 `;
 
 function run(
@@ -103,8 +106,7 @@ function copyCurrentDocsSite(targetDir: string) {
     recursive: true,
     dereference: false,
     filter: (source) =>
-      !/[\\/]node_modules([\\/]|$)/.test(source) &&
-      !/[\\/]\\.vitepress[\\/]dist([\\/]|$)/.test(source),
+      !/[\\/]node_modules([\\/]|$)/.test(source) && !isGeneratedVitePressPath(source),
   });
 }
 
@@ -173,8 +175,6 @@ function buildDocs(options: {
   outDir: string;
   channel: string;
   version?: string;
-  latestStable: string;
-  manifestJson: string;
 }) {
   console.info(`[docs] building ${options.version ?? options.channel} -> ${options.base}`);
   run('bun', ['run', '--cwd', currentDocsSite, 'vitepress', 'build', options.snapshotDocsSite], {
@@ -187,98 +187,13 @@ function buildDocs(options: {
       SUBMINER_DOCS_REPO_DIR: currentDocsSite,
       SUBMINER_DOCS_CHANNEL: options.channel,
       SUBMINER_DOCS_VERSION: options.version ?? '',
-      SUBMINER_DOCS_LATEST_STABLE: options.latestStable,
-      SUBMINER_DOCS_VERSION_MANIFEST: options.manifestJson,
       VITE_EXTRA_EXTENSIONS: 'jsonc',
     },
   });
 }
 
-function updateHashWithPath(hash: ReturnType<typeof createHash>, path: string) {
-  if (isSharedInternalsHashIgnoredPath(path)) {
-    return;
-  }
-
-  const stat = lstatSync(path);
-  const relativePath = path.replace(repoRoot, '');
-
-  if (stat.isSymbolicLink()) {
-    hash.update(`symlink:${relativePath}`);
-    hash.update(readlinkSync(path));
-    return;
-  }
-
-  if (stat.isDirectory()) {
-    hash.update(`dir:${relativePath}`);
-    for (const entry of readdirSync(path).sort()) {
-      updateHashWithPath(hash, join(path, entry));
-    }
-    return;
-  }
-
-  hash.update(`file:${relativePath}`);
-  hash.update(readFileSync(path));
-}
-
 function isGeneratedVitePressPath(path: string): boolean {
-  return /[\\/]\\.vitepress[\\/](cache|dist)([\\/]|$)/.test(path);
-}
-
-function isSharedInternalsHashIgnoredPath(path: string): boolean {
-  return isGeneratedVitePressPath(path) || /\.test\.[cm]?[jt]s$/.test(path);
-}
-
-function computeSharedInternalsHash(): string {
-  const hash = createHash('sha256');
-  hash.update(
-    `version-link-origin:${process.env.SUBMINER_DOCS_VERSION_LINK_ORIGIN === 'local' ? 'local' : 'production'}`,
-  );
-  const paths = [
-    join(currentDocsSite, '.vitepress'),
-    join(currentDocsSite, 'public/assets/fonts'),
-    join(currentDocsSite, 'package.json'),
-    join(currentDocsSite, 'bun.lock'),
-    join(repoRoot, 'scripts/build-versioned-docs.ts'),
-    join(repoRoot, 'scripts/docs-versioning.ts'),
-  ];
-
-  for (const path of paths) {
-    if (existsSync(path)) {
-      updateHashWithPath(hash, path);
-    }
-  }
-
-  return hash.digest('hex');
-}
-
-function archiveCachePath(version: string, sharedInternalsHash: string): string {
-  return join(archiveCacheRoot, versionArchiveCacheName(version, sharedInternalsHash));
-}
-
-function restoreCachedArchive(version: string, sharedInternalsHash: string): boolean {
-  const cachedArchive = archiveCachePath(version, sharedInternalsHash);
-  if (!existsSync(cachedArchive)) {
-    return false;
-  }
-
-  console.info(`[docs] cache hit ${version}`);
-  cpSync(cachedArchive, join(aggregateOutDir, versionOutputPath(version)), {
-    recursive: true,
-    force: true,
-  });
-  return true;
-}
-
-function saveArchiveCache(version: string, sharedInternalsHash: string) {
-  const outputPath = join(aggregateOutDir, versionOutputPath(version));
-  if (!existsSync(outputPath)) {
-    return;
-  }
-
-  const cachedArchive = archiveCachePath(version, sharedInternalsHash);
-  rmSync(cachedArchive, { recursive: true, force: true });
-  mkdirSync(archiveCacheRoot, { recursive: true });
-  cpSync(outputPath, cachedArchive, { recursive: true, force: true });
+  return /[\\/]\.vitepress[\\/](cache|dist)([\\/]|$)/.test(path);
 }
 
 function assertCloudflarePagesLimits(root: string) {
@@ -317,7 +232,66 @@ function assertCloudflarePagesLimits(root: string) {
   }
 }
 
+function currentCommit(): string {
+  return capture('git', ['rev-parse', 'HEAD']).trim();
+}
+
+function parseArgs(argv: string[]): { requireArchives: boolean; rebuild: Set<string> | 'all' } {
+  let requireArchives = false;
+  let rebuild: Set<string> | 'all' = new Set();
+  for (const arg of argv) {
+    if (arg === '--require-archives') {
+      requireArchives = true;
+    } else if (arg.startsWith('--rebuild-archives=')) {
+      const value = arg.slice('--rebuild-archives='.length).trim();
+      rebuild =
+        value === 'all'
+          ? 'all'
+          : new Set(
+              value
+                .split(',')
+                .map((tag) => tag.trim())
+                .filter(Boolean),
+            );
+    } else {
+      throw new Error(`Unknown argument: ${arg}`);
+    }
+  }
+  return { requireArchives, rebuild };
+}
+
+// Builds and uploads every stable archive that R2 does not already hold (or that was
+// explicitly requested). Old tags are rendered with the current `.vitepress` overlay.
+function syncArchives(options: {
+  store: DocsArchiveStore;
+  stableVersions: string[];
+  rebuild: Set<string> | 'all';
+}) {
+  const builtFrom = currentCommit();
+  for (const version of options.stableVersions) {
+    const forced = options.rebuild === 'all' || options.rebuild.has(version);
+    if (!forced && options.store.has(version)) {
+      continue;
+    }
+
+    console.info(`[docs] building archive ${version}`);
+    const outDir = join(archiveOutRoot, versionOutputPath(version));
+    rmSync(outDir, { recursive: true, force: true });
+    buildDocs({
+      snapshotDocsSite: prepareSnapshot(version, version),
+      base: versionPath(version),
+      outDir,
+      channel: 'stable-archive',
+      version,
+    });
+    console.info(`[docs] uploading archive ${version}`);
+    options.store.upload(version, outDir, builtFrom);
+    rmSync(outDir, { recursive: true, force: true });
+  }
+}
+
 function main() {
+  const { requireArchives, rebuild } = parseArgs(process.argv.slice(2));
   const stableVersions = getStableVersions();
   const latestStable = stableVersions[0];
 
@@ -325,54 +299,42 @@ function main() {
     throw new Error('No stable release tags with docs-site/package.json found.');
   }
 
+  if (rebuild !== 'all') {
+    const unknown = [...rebuild].filter((tag) => !stableVersions.includes(tag));
+    if (unknown.length > 0) {
+      throw new Error(`Cannot rebuild unknown stable docs versions: ${unknown.join(', ')}`);
+    }
+  }
+
   const manifest = buildVersionManifest({ latestStable, stableVersions });
-  const manifestJson = JSON.stringify(manifest);
-  const sharedInternalsHash = computeSharedInternalsHash();
-  const archiveCacheKey = versionArchiveCacheKey({ sharedInternalsHash, manifestJson });
   const sharedAssetPaths = collectSharedAssetPaths(join(currentDocsSite, 'public/assets'));
-  console.info(`[docs] archive cache key ${archiveCacheKey.slice(0, 12)}`);
 
   rmSync(buildRoot, { recursive: true, force: true });
   rmSync(aggregateOutDir, { recursive: true, force: true });
   mkdirSync(buildRoot, { recursive: true });
   mkdirSync(aggregateOutDir, { recursive: true });
 
+  const store = createArchiveStore(archiveStoreEnvFromProcess(process.env));
+  if (store) {
+    syncArchives({ store, stableVersions, rebuild });
+  } else if (requireArchives) {
+    throw new Error(
+      'Docs archive R2 credentials are missing (CLOUDFLARE_ACCOUNT_ID, DOCS_ARCHIVE_R2_ACCESS_KEY_ID, DOCS_ARCHIVE_R2_SECRET_ACCESS_KEY, DOCS_ARCHIVE_R2_BUCKET).',
+    );
+  } else {
+    console.warn('[docs] R2 credentials not set; skipping /v/<version>/ archive sync');
+  }
+
   const latestStableSnapshot = prepareSnapshot(latestStable, latestStable);
+  writeFileSync(join(latestStableSnapshot, 'versions.md'), renderVersionsPage(manifest));
   buildDocs({
     snapshotDocsSite: latestStableSnapshot,
     base: '/',
     outDir: aggregateOutDir,
     channel: 'stable-root',
     version: latestStable,
-    latestStable,
-    manifestJson,
   });
 
-  for (const version of stableVersions) {
-    if (restoreCachedArchive(version, archiveCacheKey)) {
-      continue;
-    }
-
-    console.info(`[docs] rebuilding archive ${version}`);
-    const snapshot =
-      version === latestStable ? latestStableSnapshot : prepareSnapshot(version, version);
-    buildDocs({
-      snapshotDocsSite: snapshot,
-      base: versionPath(version),
-      outDir: join(aggregateOutDir, versionOutputPath(version)),
-      channel: 'stable-archive',
-      version,
-      latestStable,
-      manifestJson,
-    });
-    dedupeVersionedPublicAssets({
-      outDir: join(aggregateOutDir, versionOutputPath(version)),
-      base: versionPath(version),
-      sharedAssetPaths,
-    });
-    saveArchiveCache(version, archiveCacheKey);
-  }
-
   const mainSnapshot = prepareSnapshot('main');
   buildDocs({
     snapshotDocsSite: mainSnapshot,
@@ -380,8 +342,6 @@ function main() {
     outDir: join(aggregateOutDir, 'main'),
     channel: 'main',
     version: 'main',
-    latestStable,
-    manifestJson,
   });
   dedupeVersionedPublicAssets({
     outDir: join(aggregateOutDir, 'main'),
@@ -392,13 +352,6 @@ function main() {
   writeFileSync(join(aggregateOutDir, 'versions.json'), `${JSON.stringify(manifest, null, 2)}\n`);
   writeFileSync(join(aggregateOutDir, '_headers'), deployHeaders);
   assertCloudflarePagesLimits(aggregateOutDir);
-  const prunedArchives = pruneArchiveCacheGenerations({
-    cacheRoot: archiveCacheRoot,
-    activeCacheKey: archiveCacheKey,
-  });
-  if (prunedArchives.length > 0) {
-    console.info(`[docs] pruned ${prunedArchives.length} stale archive cache directories`);
-  }
   rmSync(buildRoot, { recursive: true, force: true });
 }
 
diff --git a/scripts/bundled-integration-keys.mjs b/scripts/bundled-integration-keys.mjs
new file mode 100644
index 00000000..de82872b
--- /dev/null
+++ b/scripts/bundled-integration-keys.mjs
@@ -0,0 +1,29 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Release builds carry a project-owned TMDB key so live-action lookups work
+ * without user setup. The key is injected from the SUBMINER_TMDB_API_KEY
+ * environment variable at build time (a GitHub Actions secret in CI) and never
+ * lives in the repository. The runtime reader is
+ * src/core/services/tmdb/bundled-api-key.ts; keep the file name in sync.
+ */
+export const BUNDLED_INTEGRATION_KEYS_FILENAME = 'bundled-integration-keys.json';
+export const TMDB_API_KEY_ENV = 'SUBMINER_TMDB_API_KEY';
+
+/**
+ * Write the bundled keys file into `distDir`, or remove a stale one when no
+ * key is present so a keyless build never ships an older key by accident.
+ * Returns the names of the keys staged.
+ */
+export function stageBundledIntegrationKeys(distDir, env = process.env) {
+  const outputPath = path.join(distDir, BUNDLED_INTEGRATION_KEYS_FILENAME);
+  const tmdbApiKey = env[TMDB_API_KEY_ENV]?.trim() ?? '';
+  if (!tmdbApiKey) {
+    fs.rmSync(outputPath, { force: true });
+    return [];
+  }
+  fs.mkdirSync(distDir, { recursive: true });
+  fs.writeFileSync(outputPath, `${JSON.stringify({ tmdbApiKey })}\n`, { mode: 0o644 });
+  return ['tmdb'];
+}
diff --git a/scripts/bundled-integration-keys.test.ts b/scripts/bundled-integration-keys.test.ts
new file mode 100644
index 00000000..09d8283e
--- /dev/null
+++ b/scripts/bundled-integration-keys.test.ts
@@ -0,0 +1,39 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import test from 'node:test';
+import {
+  BUNDLED_INTEGRATION_KEYS_FILENAME,
+  stageBundledIntegrationKeys,
+} from './bundled-integration-keys.mjs';
+
+function withDistDir(work: (distDir: string) => void): void {
+  const distDir = fs.mkdtempSync(path.join(os.tmpdir(), 'subminer-bundled-keys-'));
+  try {
+    work(distDir);
+  } finally {
+    fs.rmSync(distDir, { recursive: true, force: true });
+  }
+}
+
+test('stageBundledIntegrationKeys writes the TMDB key from the environment', () => {
+  withDistDir((distDir) => {
+    const staged = stageBundledIntegrationKeys(distDir, { SUBMINER_TMDB_API_KEY: ' abc123 ' });
+    assert.deepEqual(staged, ['tmdb']);
+    const written = JSON.parse(
+      fs.readFileSync(path.join(distDir, BUNDLED_INTEGRATION_KEYS_FILENAME), 'utf8'),
+    );
+    assert.deepEqual(written, { tmdbApiKey: 'abc123' });
+  });
+});
+
+test('stageBundledIntegrationKeys removes a stale file when the variable is unset', () => {
+  withDistDir((distDir) => {
+    const outputPath = path.join(distDir, BUNDLED_INTEGRATION_KEYS_FILENAME);
+    fs.writeFileSync(outputPath, '{"tmdbApiKey":"old"}');
+    assert.deepEqual(stageBundledIntegrationKeys(distDir, {}), []);
+    assert.equal(fs.existsSync(outputPath), false);
+    assert.deepEqual(stageBundledIntegrationKeys(distDir, { SUBMINER_TMDB_API_KEY: '  ' }), []);
+  });
+});
diff --git a/scripts/compiled-runtime-smoke.mjs b/scripts/compiled-runtime-smoke.mjs
new file mode 100644
index 00000000..c0ae06cb
--- /dev/null
+++ b/scripts/compiled-runtime-smoke.mjs
@@ -0,0 +1,345 @@
+import assert from 'node:assert/strict';
+import { spawn } from 'node:child_process';
+import { existsSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { createServer } from 'node:net';
+import { request as httpRequest } from 'node:http';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const START_TIMEOUT_MS = 15_000;
+const STOP_TIMEOUT_MS = 5_000;
+const POLL_INTERVAL_MS = 25;
+const MAX_CHILD_OUTPUT_BYTES = 64 * 1024;
+
+const scriptDir = dirname(fileURLToPath(import.meta.url));
+const repoRootArgIndex = process.argv.indexOf('--repo-root');
+const repoRoot = resolve(
+  repoRootArgIndex === -1 ? join(scriptDir, '..') : (process.argv[repoRootArgIndex + 1] ?? ''),
+);
+const paths = {
+  mainEntry: join(repoRoot, 'dist', 'main-entry.js'),
+  daemonEntry: join(repoRoot, 'dist', 'stats-daemon-runner.js'),
+  statsServer: join(repoRoot, 'dist', 'core', 'services', 'stats-server.js'),
+  tracker: join(repoRoot, 'dist', 'core', 'services', 'immersion-tracker-service.js'),
+  statsIndex: join(repoRoot, 'stats', 'dist', 'index.html'),
+};
+
+function requireCompiledArtifacts() {
+  const missing = Object.values(paths).filter((artifactPath) => !existsSync(artifactPath));
+  if (missing.length > 0) {
+    throw new Error(
+      `Compiled runtime artifacts are missing. Run \`bun run build\` before this check:\n${missing
+        .map((artifactPath) => `  - ${artifactPath}`)
+        .join('\n')}`,
+    );
+  }
+}
+
+function requireElectronNodeRuntime() {
+  if (!process.versions.electron || process.env.ELECTRON_RUN_AS_NODE !== '1') {
+    throw new Error(
+      'This check must run with Electron in Node mode. Use `bun run test:smoke:dist`.',
+    );
+  }
+}
+
+function delay(ms) {
+  return new Promise((resolvePromise) => setTimeout(resolvePromise, ms));
+}
+
+function listen(server, port = 0) {
+  return new Promise((resolvePromise, reject) => {
+    const onError = (error) => {
+      server.off('listening', onListening);
+      reject(error);
+    };
+    const onListening = () => {
+      server.off('error', onError);
+      const address = server.address();
+      if (!address || typeof address === 'string') {
+        reject(new Error('Could not resolve the stats smoke port.'));
+        return;
+      }
+      resolvePromise(address.port);
+    };
+    server.once('error', onError);
+    server.once('listening', onListening);
+    server.listen(port, '127.0.0.1');
+  });
+}
+
+function closeServer(server) {
+  return new Promise((resolvePromise, reject) => {
+    server.close((error) => {
+      if (error) {
+        reject(error);
+        return;
+      }
+      resolvePromise();
+    });
+  });
+}
+
+async function findAvailablePort() {
+  const reservation = createServer();
+  const port = await listen(reservation);
+  await closeServer(reservation);
+  return port;
+}
+
+function writeSmokeConfig(userDataPath, port) {
+  writeFileSync(
+    join(userDataPath, 'config.json'),
+    `${JSON.stringify({ stats: { serverPort: port } })}\n`,
+  );
+}
+
+function spawnDaemon(userDataPath, responsePath) {
+  const child = spawn(
+    process.execPath,
+    [
+      paths.daemonEntry,
+      '--stats-user-data-path',
+      userDataPath,
+      '--stats-response-path',
+      responsePath,
+    ],
+    {
+      cwd: repoRoot,
+      env: { ...process.env, ELECTRON_RUN_AS_NODE: '1' },
+      stdio: ['ignore', 'pipe', 'pipe'],
+    },
+  );
+  let output = '';
+  const appendOutput = (chunk) => {
+    if (output.length >= MAX_CHILD_OUTPUT_BYTES) return;
+    output += String(chunk);
+    if (output.length > MAX_CHILD_OUTPUT_BYTES) {
+      output = `${output.slice(0, MAX_CHILD_OUTPUT_BYTES)}\n[child output truncated]\n`;
+    }
+  };
+  child.stdout.on('data', appendOutput);
+  child.stderr.on('data', appendOutput);
+  let exited = false;
+  const exit = new Promise((resolvePromise) => {
+    child.once('error', (error) => {
+      exited = true;
+      resolvePromise({ code: null, signal: null, error });
+    });
+    child.once('exit', (code, signal) => {
+      exited = true;
+      resolvePromise({ code, signal, error: null });
+    });
+  });
+  return { child, exit, hasExited: () => exited, getOutput: () => output };
+}
+
+async function waitForResponse(responsePath, daemon) {
+  const deadline = Date.now() + START_TIMEOUT_MS;
+  while (Date.now() < deadline) {
+    if (existsSync(responsePath)) {
+      try {
+        return JSON.parse(readFileSync(responsePath, 'utf8'));
+      } catch {
+        // The daemon may still be finishing the response file write.
+      }
+    }
+    if (daemon.hasExited()) {
+      const result = await daemon.exit;
+      throw new Error(
+        `Stats daemon exited before writing a startup response (${formatExit(result)}).\n${daemon.getOutput()}`,
+      );
+    }
+    await delay(POLL_INTERVAL_MS);
+  }
+  throw new Error(`Timed out waiting for stats daemon startup.\n${daemon.getOutput()}`);
+}
+
+function formatExit(result) {
+  if (result.error) return result.error.message;
+  if (result.signal) return `signal ${result.signal}`;
+  return `exit code ${result.code}`;
+}
+
+async function waitForExit(daemon, timeoutMs) {
+  return await Promise.race([daemon.exit, delay(timeoutMs).then(() => null)]);
+}
+
+async function stopDaemon(daemon) {
+  if (daemon.hasExited()) {
+    return await daemon.exit;
+  }
+  daemon.child.kill('SIGTERM');
+  const result = await waitForExit(daemon, STOP_TIMEOUT_MS);
+  if (result) return result;
+  daemon.child.kill('SIGKILL');
+  await daemon.exit;
+  throw new Error(`Stats daemon did not stop after SIGTERM.\n${daemon.getOutput()}`);
+}
+
+async function assertPortCanBind(port) {
+  const server = createServer();
+  try {
+    await listen(server, port);
+  } finally {
+    if (server.listening) await closeServer(server);
+  }
+}
+
+async function fetchOverview(url, daemon) {
+  const deadline = Date.now() + START_TIMEOUT_MS;
+  let lastError = null;
+  while (Date.now() < deadline) {
+    try {
+      return await fetch(`${url}/api/stats/overview`, {
+        signal: AbortSignal.timeout(START_TIMEOUT_MS),
+      });
+    } catch (error) {
+      lastError = error;
+    }
+    if (daemon.hasExited()) {
+      const result = await daemon.exit;
+      throw new Error(
+        `Stats daemon exited before accepting HTTP requests (${formatExit(result)}).\n${daemon.getOutput()}`,
+      );
+    }
+    await delay(POLL_INTERVAL_MS);
+  }
+  throw new Error(
+    `Timed out waiting for the stats HTTP server: ${lastError instanceof Error ? lastError.message : String(lastError)}\n${daemon.getOutput()}`,
+  );
+}
+
+async function runHealthyStartup(userDataPath, port, responseName) {
+  writeSmokeConfig(userDataPath, port);
+  const responsePath = join(userDataPath, responseName);
+  const statePath = join(userDataPath, 'stats-daemon.json');
+  const databasePath = join(userDataPath, 'immersion.sqlite');
+  const daemon = spawnDaemon(userDataPath, responsePath);
+  let shutdownResult;
+  let unfinishedRequest;
+
+  try {
+    const startup = await waitForResponse(responsePath, daemon);
+    assert.deepEqual(startup, { ok: true, url: `http://127.0.0.1:${port}` });
+
+    const response = await fetchOverview(startup.url, daemon);
+    assert.equal(response.status, 200);
+    assert.match(response.headers.get('content-type') ?? '', /^application\/json\b/);
+    const overview = await response.json();
+    assert.equal(typeof overview, 'object');
+    assert.ok(overview !== null);
+    assert.ok(Array.isArray(overview.sessions));
+    assert.ok(Array.isArray(overview.rollups));
+    assert.equal(typeof overview.hints, 'object');
+
+    const dashboard = await fetch(`${startup.url}/?overlay=1`, {
+      signal: AbortSignal.timeout(START_TIMEOUT_MS),
+    });
+    assert.equal(dashboard.status, 200);
+    assert.match(dashboard.headers.get('content-type') ?? '', /^text\/html\b/);
+    assert.match(await dashboard.text(), /id="root"/);
+
+    assert.ok(existsSync(databasePath), 'The compiled tracker did not create its SQLite database.');
+    assert.ok(
+      statSync(databasePath).size > 0,
+      'The compiled tracker created an empty SQLite file.',
+    );
+
+    // Leave a real request body unfinished so shutdown must bound its drain wait.
+    unfinishedRequest = httpRequest(new URL('/api/stats/anki/notesInfo', startup.url), {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Content-Length': '1000',
+        Expect: '100-continue',
+      },
+      signal: AbortSignal.timeout(START_TIMEOUT_MS),
+    });
+    await new Promise((resolvePromise, reject) => {
+      unfinishedRequest.on('error', reject);
+      unfinishedRequest.once('continue', () => {
+        unfinishedRequest.write('{');
+        resolvePromise();
+      });
+      unfinishedRequest.flushHeaders();
+    });
+  } finally {
+    try {
+      shutdownResult = await stopDaemon(daemon);
+    } finally {
+      unfinishedRequest?.destroy();
+    }
+  }
+
+  assert.equal(shutdownResult.code, 0, `Stats daemon shutdown failed.\n${daemon.getOutput()}`);
+  assert.equal(existsSync(statePath), false, 'Stats daemon state remained after shutdown.');
+  await assertPortCanBind(port);
+}
+
+async function runConflictRecovery() {
+  const userDataPath = mkdtempSync(join(tmpdir(), 'subminer-compiled-conflict-'));
+  const reservation = createServer();
+  const port = await listen(reservation);
+  const responsePath = join(userDataPath, 'conflict-response.json');
+  const statePath = join(userDataPath, 'stats-daemon.json');
+  writeSmokeConfig(userDataPath, port);
+  const daemon = spawnDaemon(userDataPath, responsePath);
+  const failures = [];
+
+  try {
+    const response = await waitForResponse(responsePath, daemon);
+    if (response.ok !== false) {
+      failures.push('The stats daemon reported success while its configured port was occupied.');
+    }
+    const result = await waitForExit(daemon, STOP_TIMEOUT_MS);
+    if (!result) {
+      failures.push('The stats daemon did not exit after its configured port failed to bind.');
+    } else if (result.code === 0) {
+      failures.push(
+        'The stats daemon exited successfully after its configured port failed to bind.',
+      );
+    }
+    if (existsSync(statePath)) {
+      failures.push(
+        'The stats daemon left ownership state behind after its configured port failed to bind.',
+      );
+    }
+  } finally {
+    await closeServer(reservation);
+    if (!daemon.hasExited()) {
+      await stopDaemon(daemon);
+    }
+  }
+
+  try {
+    await runHealthyStartup(userDataPath, port, 'recovery-response.json');
+  } finally {
+    rmSync(userDataPath, { recursive: true, force: true });
+  }
+
+  assert.deepEqual(failures, []);
+}
+
+async function main() {
+  requireCompiledArtifacts();
+  requireElectronNodeRuntime();
+
+  const userDataPath = mkdtempSync(join(tmpdir(), 'subminer-compiled-runtime-'));
+  try {
+    await runHealthyStartup(userDataPath, await findAvailablePort(), 'startup-response.json');
+  } finally {
+    rmSync(userDataPath, { recursive: true, force: true });
+  }
+  await runConflictRecovery();
+
+  process.stdout.write(
+    `Compiled runtime smoke passed with Electron ${process.versions.electron}, Node ${process.versions.node}, HTTP, and native SQLite.\n`,
+  );
+}
+
+main().catch((error) => {
+  process.stderr.write(`${error instanceof Error ? error.stack : String(error)}\n`);
+  process.exitCode = 1;
+});
diff --git a/scripts/compiled-runtime-smoke.test.ts b/scripts/compiled-runtime-smoke.test.ts
new file mode 100644
index 00000000..e732a1d8
--- /dev/null
+++ b/scripts/compiled-runtime-smoke.test.ts
@@ -0,0 +1,28 @@
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import test from 'node:test';
+
+test('compiled runtime smoke fails clearly when build artifacts are missing', () => {
+  const emptyRepo = fs.mkdtempSync(path.join(os.tmpdir(), 'subminer-compiled-missing-'));
+  try {
+    const result = spawnSync(
+      process.execPath,
+      ['scripts/compiled-runtime-smoke.mjs', '--repo-root', emptyRepo],
+      {
+        cwd: path.resolve(import.meta.dir, '..'),
+        encoding: 'utf8',
+      },
+    );
+
+    assert.equal(result.status, 1);
+    assert.match(result.stderr, /Compiled runtime artifacts are missing/);
+    assert.match(result.stderr, /dist\/main-entry\.js/);
+    assert.match(result.stderr, /dist\/stats-daemon-runner\.js/);
+    assert.doesNotMatch(result.stderr, /must run with Electron/);
+  } finally {
+    fs.rmSync(emptyRepo, { recursive: true, force: true });
+  }
+});
diff --git a/scripts/dev.sh b/scripts/dev.sh
new file mode 100644
index 00000000..36105f26
--- /dev/null
+++ b/scripts/dev.sh
@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+FILE="${1:-}"
+
+if [[ ! -f "$FILE" ]]; then
+	printf 'Not a file: %s\n' "${FILE:-<missing>}" >&2
+	exit 1
+fi
+
+if ! mpv --no-config --no-terminal --msg-level=all=no --vo=null --ao=null --frames=1 -- "$FILE"; then
+	printf 'Not playable by mpv: %s\n' "$FILE" >&2
+	exit 1
+fi
+
+exec subminer app --dev --launch-mpv "$FILE"
diff --git a/scripts/docs-archive-store.ts b/scripts/docs-archive-store.ts
new file mode 100644
index 00000000..bc8966f6
--- /dev/null
+++ b/scripts/docs-archive-store.ts
@@ -0,0 +1,107 @@
+import { spawnSync } from 'node:child_process';
+import { writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { versionOutputPath } from './docs-versioning';
+
+// Frozen `/v/<version>/` doc builds live in an R2 bucket and are served by the Pages
+// Function in `docs-site/functions/v/[[path]].ts`, so they never count toward the Pages
+// deployment. Transfers go through the AWS CLI's S3 API (preinstalled on GitHub runners).
+
+// Written last on upload; an archive without it is treated as missing and rebuilt.
+export const ARCHIVE_MARKER = '_archive.json';
+
+export type DocsArchiveStore = {
+  has(version: string): boolean;
+  upload(version: string, dir: string, builtFrom: string): void;
+};
+
+export type DocsArchiveStoreEnv = {
+  accountId?: string;
+  accessKeyId?: string;
+  secretAccessKey?: string;
+  bucket?: string;
+};
+
+export function archiveStoreEnvFromProcess(env: NodeJS.ProcessEnv): DocsArchiveStoreEnv {
+  return {
+    accountId: env.CLOUDFLARE_ACCOUNT_ID,
+    accessKeyId: env.DOCS_ARCHIVE_R2_ACCESS_KEY_ID,
+    secretAccessKey: env.DOCS_ARCHIVE_R2_SECRET_ACCESS_KEY,
+    bucket: env.DOCS_ARCHIVE_R2_BUCKET,
+  };
+}
+
+export function archiveKeyPrefix(version: string): string {
+  return `${versionOutputPath(version)}/`;
+}
+
+// Returns null when credentials are absent so local builds can skip archive sync.
+export function createArchiveStore(config: DocsArchiveStoreEnv): DocsArchiveStore | null {
+  const { accountId, accessKeyId, secretAccessKey, bucket } = config;
+  if (!accountId || !accessKeyId || !secretAccessKey || !bucket) {
+    return null;
+  }
+
+  const endpoint = `https://${accountId}.r2.cloudflarestorage.com`;
+  const env: NodeJS.ProcessEnv = {
+    ...process.env,
+    AWS_ACCESS_KEY_ID: accessKeyId,
+    AWS_SECRET_ACCESS_KEY: secretAccessKey,
+    AWS_DEFAULT_REGION: 'auto',
+    // AWS CLI >= 2.23 sends CRC checksums by default, which R2 does not fully support.
+    AWS_REQUEST_CHECKSUM_CALCULATION: 'when_required',
+    AWS_RESPONSE_CHECKSUM_VALIDATION: 'when_required',
+  };
+
+  function aws(args: string[]) {
+    return spawnSync('aws', [...args, '--endpoint-url', endpoint], {
+      env,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+  }
+
+  return {
+    has(version) {
+      const result = aws([
+        's3api',
+        'head-object',
+        '--bucket',
+        bucket,
+        '--key',
+        `${archiveKeyPrefix(version)}${ARCHIVE_MARKER}`,
+      ]);
+      if (result.error) throw result.error;
+      if (result.status === 0) return true;
+      if (/\b404\b|Not Found/i.test(result.stderr)) return false;
+      throw new Error(`Unable to check docs archive ${version}: ${result.stderr.trim()}`);
+    },
+
+    upload(version, dir, builtFrom) {
+      const target = `s3://${bucket}/${archiveKeyPrefix(version)}`;
+      // Unmark first so a rebuild that fails partway is retried by the next deploy
+      // instead of being skipped as complete. Deleting a missing key succeeds.
+      const unmark = aws(['s3', 'rm', `${target}${ARCHIVE_MARKER}`, '--only-show-errors']);
+      if (unmark.error) throw unmark.error;
+      if (unmark.status !== 0) {
+        throw new Error(`Unable to unmark docs archive ${version}: ${unmark.stderr.trim()}`);
+      }
+
+      const sync = aws(['s3', 'sync', dir, target, '--only-show-errors']);
+      if (sync.error) throw sync.error;
+      if (sync.status !== 0) {
+        throw new Error(`Unable to upload docs archive ${version}: ${sync.stderr.trim()}`);
+      }
+
+      const markerPath = join(dir, ARCHIVE_MARKER);
+      writeFileSync(
+        markerPath,
+        `${JSON.stringify({ version, builtFrom, builtAt: new Date().toISOString() }, null, 2)}\n`,
+      );
+      const marker = aws(['s3', 'cp', markerPath, `${target}${ARCHIVE_MARKER}`]);
+      if (marker.status !== 0) {
+        throw new Error(`Unable to mark docs archive ${version}: ${marker.stderr.trim()}`);
+      }
+    },
+  };
+}
diff --git a/scripts/docs-versioned-assets.test.ts b/scripts/docs-versioned-assets.test.ts
index 27e27c00..aa44b35a 100644
--- a/scripts/docs-versioned-assets.test.ts
+++ b/scripts/docs-versioned-assets.test.ts
@@ -3,11 +3,7 @@ import { existsSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from
 import { rm } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
-import {
-  dedupeVersionedPublicAssets,
-  pruneArchiveCacheGenerations,
-  rewriteSharedAssetReferences,
-} from './docs-versioned-assets';
+import { dedupeVersionedPublicAssets, rewriteSharedAssetReferences } from './docs-versioned-assets';
 
 function tempDir() {
   return mkdtempSync(join(tmpdir(), 'subminer-docs-versioned-assets-'));
@@ -97,28 +93,3 @@ describe('docs versioned asset dedupe', () => {
     }
   });
 });
-
-describe('docs archive cache pruning', () => {
-  test('removes stale cache generations while keeping the active generation', async () => {
-    const dir = tempDir();
-    try {
-      mkdirSync(join(dir, 'active123456-v0.14.0'), { recursive: true });
-      mkdirSync(join(dir, 'stale654321-v0.14.0'), { recursive: true });
-      mkdirSync(join(dir, 'stale654321-v0.13.0'), { recursive: true });
-
-      const removed = pruneArchiveCacheGenerations({
-        cacheRoot: dir,
-        activeCacheKey: 'active123456abcdef',
-      });
-
-      expect(removed.sort()).toEqual([
-        join(dir, 'stale654321-v0.13.0'),
-        join(dir, 'stale654321-v0.14.0'),
-      ]);
-      expect(existsSync(join(dir, 'active123456-v0.14.0'))).toBe(true);
-      expect(existsSync(join(dir, 'stale654321-v0.14.0'))).toBe(false);
-    } finally {
-      await rm(dir, { recursive: true, force: true });
-    }
-  });
-});
diff --git a/scripts/docs-versioned-assets.ts b/scripts/docs-versioned-assets.ts
index 38e1f988..da9f5deb 100644
--- a/scripts/docs-versioned-assets.ts
+++ b/scripts/docs-versioned-assets.ts
@@ -119,30 +119,3 @@ function removeEmptyDirectories(root: string) {
     rmSync(root, { recursive: true, force: true });
   }
 }
-
-export function pruneArchiveCacheGenerations(options: {
-  cacheRoot: string;
-  activeCacheKey: string;
-}): string[] {
-  if (!existsSync(options.cacheRoot)) {
-    return [];
-  }
-
-  const activePrefix = options.activeCacheKey.slice(0, 12);
-  const removed: string[] = [];
-
-  for (const entry of readdirSync(options.cacheRoot)) {
-    const path = join(options.cacheRoot, entry);
-    if (!lstatSync(path).isDirectory()) {
-      continue;
-    }
-    if (entry.startsWith(`${activePrefix}-`)) {
-      continue;
-    }
-
-    rmSync(path, { recursive: true, force: true });
-    removed.push(path);
-  }
-
-  return removed;
-}
diff --git a/scripts/docs-versioning.test.ts b/scripts/docs-versioning.test.ts
index 379f0b54..e9afdf5a 100644
--- a/scripts/docs-versioning.test.ts
+++ b/scripts/docs-versioning.test.ts
@@ -2,10 +2,9 @@ import { describe, expect, test } from 'bun:test';
 import {
   buildVersionManifest,
   compareStableVersionsDesc,
-  versionArchiveCacheKey,
   isStableReleaseTag,
+  renderVersionsPage,
   stableTagsWithDocs,
-  versionArchiveCacheName,
   versionOutputPath,
   versionPath,
 } from './docs-versioning';
@@ -47,21 +46,16 @@ describe('docs versioning helpers', () => {
     });
   });
 
-  test('archive cache names are normalized by version and shared internals hash', () => {
-    expect(versionArchiveCacheName('v0.14.0', 'abcdef1234567890')).toBe('abcdef123456-v0.14.0');
-  });
+  test('versions page links every build with full page loads', () => {
+    const page = renderVersionsPage(
+      buildVersionManifest({ latestStable: 'v0.14.0', stableVersions: ['v0.14.0', 'v0.13.0'] }),
+    );
 
-  test('archive cache keys change when manifest contents change', () => {
-    const firstKey = versionArchiveCacheKey({
-      sharedInternalsHash: 'abcdef1234567890',
-      manifestJson: '{"latestStable":"v0.14.0"}',
-    });
-    const secondKey = versionArchiveCacheKey({
-      sharedInternalsHash: 'abcdef1234567890',
-      manifestJson: '{"latestStable":"v0.15.0"}',
-    });
-
-    expect(firstKey).not.toBe(secondKey);
+    expect(page).toContain('<a href="/" target="_self">Latest stable (v0.14.0)</a>');
+    expect(page).toContain('<a href="/main/" target="_self">main</a>');
+    expect(page).toContain('<a href="/v/0.14.0/" target="_self">v0.14.0</a>');
+    expect(page.indexOf('/v/0.14.0/')).toBeLessThan(page.indexOf('/v/0.13.0/'));
+    expect(page).toContain('<a href="/v/0.13.0/" target="_self">v0.13.0</a>');
   });
 
   test('archive output paths stay relative for filesystem joins', () => {
diff --git a/scripts/docs-versioning.ts b/scripts/docs-versioning.ts
index 517871b2..c3a50627 100644
--- a/scripts/docs-versioning.ts
+++ b/scripts/docs-versioning.ts
@@ -1,5 +1,3 @@
-import { createHash } from 'node:crypto';
-
 export type DocsVersionEntry = {
   version: string;
   path: string;
@@ -55,22 +53,6 @@ export function versionOutputPath(version: string): string {
   return `v/${version.replace(/^v/, '')}`;
 }
 
-export function versionArchiveCacheName(version: string, sharedInternalsHash: string): string {
-  return `${sharedInternalsHash.slice(0, 12)}-${version}`;
-}
-
-export function versionArchiveCacheKey(options: {
-  sharedInternalsHash: string;
-  manifestJson: string;
-}): string {
-  const hash = createHash('sha256');
-  hash.update('shared-internals:');
-  hash.update(options.sharedInternalsHash);
-  hash.update('\nmanifest:');
-  hash.update(options.manifestJson);
-  return hash.digest('hex');
-}
-
 export function stableTagsWithDocs(
   tags: string[],
   hasDocsSite: (tag: string) => boolean,
@@ -94,3 +76,27 @@ export function buildVersionManifest(options: {
     })),
   };
 }
+
+// Markdown for the root-only `/versions` page. Archives link here instead of baking the
+// release list into their nav, so an archive never needs a rebuild when a new tag ships.
+// Raw anchors with `target="_self"` keep VitePress from treating the other builds as
+// dead links or routing to them client-side.
+export function renderVersionsPage(manifest: DocsVersionManifest): string {
+  const link = (path: string, text: string) => `<a href="${path}" target="_self">${text}</a>`;
+  return [
+    '---',
+    'title: Documentation versions',
+    'description: Every published version of the SubMiner documentation.',
+    '---',
+    '',
+    '# Documentation versions',
+    '',
+    `- ${link('/', `Latest stable (${manifest.latestStable})`)}`,
+    `- ${link('/main/', 'main')}: development docs, may describe unreleased behavior`,
+    '',
+    '## Stable releases',
+    '',
+    ...manifest.versions.map((entry) => `- ${link(entry.path, entry.version)}`),
+    '',
+  ].join('\n');
+}
diff --git a/scripts/electron-builder-after-pack.cjs b/scripts/electron-builder-after-pack.cjs
index 4153f760..52310ab2 100644
--- a/scripts/electron-builder-after-pack.cjs
+++ b/scripts/electron-builder-after-pack.cjs
@@ -86,15 +86,33 @@ async function verifyMacOSWindowHelper(
   return true;
 }
 
-async function afterPack(context) {
+async function stageBundledBunRuntime(context, deps = {}) {
+  const stageBunRuntime =
+    deps.stageBunRuntime ?? (await import('./stage-bun-runtime.mjs')).stageBunRuntime;
+  const productFilename = context.packager?.appInfo?.productFilename;
+  await stageBunRuntime({
+    appOutDir: context.appOutDir,
+    platform: context.electronPlatformName,
+    arch: context.arch,
+    productFilename:
+      typeof productFilename === 'string' && productFilename.trim()
+        ? productFilename.trim()
+        : 'SubMiner',
+  });
+}
+
+async function afterPack(context, deps = {}) {
   await stageLinuxAppImageSharedLibrary(context);
   await verifyMacOSWindowHelper(context);
+  await stageBundledBunRuntime(context, deps);
+  await (deps.auditPackage ?? require('./package-audit.cjs').auditPackage)(context);
 }
 
 module.exports = {
   LINUX_FFMPEG_LIBRARY,
   MACOS_WINDOW_HELPER,
   resolveMacOSAppBundlePath,
+  stageBundledBunRuntime,
   stageLinuxAppImageSharedLibrary,
   verifyMacOSWindowHelper,
   default: afterPack,
diff --git a/scripts/electron-builder-after-pack.test.ts b/scripts/electron-builder-after-pack.test.ts
index 5470b62c..d8cb3a36 100644
--- a/scripts/electron-builder-after-pack.test.ts
+++ b/scripts/electron-builder-after-pack.test.ts
@@ -13,7 +13,23 @@ const {
 } = require('./electron-builder-after-pack.cjs') as {
   LINUX_FFMPEG_LIBRARY: string;
   MACOS_WINDOW_HELPER: string;
-  default: (context: { appOutDir: string; electronPlatformName: string }) => Promise<void>;
+  default: (
+    context: {
+      appOutDir: string;
+      arch?: number;
+      electronPlatformName: string;
+      packager?: { appInfo?: { productFilename?: string } };
+    },
+    deps?: {
+      auditPackage?: (context: { appOutDir: string }) => Promise<void>;
+      stageBunRuntime?: (options: {
+        appOutDir: string;
+        platform: string;
+        arch: number | undefined;
+        productFilename: string;
+      }) => Promise<void>;
+    },
+  ) => Promise<void>;
   stageLinuxAppImageSharedLibrary: (context: {
     appOutDir: string;
     electronPlatformName: string;
@@ -156,3 +172,55 @@ test('afterPack propagates Linux staging failures', async () => {
     fs.rmSync(workspace, { recursive: true, force: true });
   }
 });
+
+test('afterPack stages Linux and Bun runtime assets before auditing the package', async () => {
+  const workspace = createWorkspace('subminer-after-pack-target');
+  const appOutDir = path.join(workspace, 'SubMiner-linux-arm64');
+  const sourceLibraryPath = path.join(appOutDir, LINUX_FFMPEG_LIBRARY);
+  const targetLibraryPath = path.join(appOutDir, 'usr', 'lib', LINUX_FFMPEG_LIBRARY);
+  const operations: string[] = [];
+  let stagedOptions:
+    | {
+        appOutDir: string;
+        platform: string;
+        arch: number | undefined;
+        productFilename: string;
+      }
+    | undefined;
+
+  fs.mkdirSync(appOutDir, { recursive: true });
+  fs.writeFileSync(sourceLibraryPath, 'bundled ffmpeg', 'utf8');
+
+  try {
+    await afterPack(
+      {
+        appOutDir,
+        arch: 3,
+        electronPlatformName: 'linux',
+        packager: { appInfo: { productFilename: 'SubMiner Preview' } },
+      },
+      {
+        stageBunRuntime: async (options) => {
+          stagedOptions = options;
+          operations.push('stage-bun');
+        },
+        auditPackage: async (context) => {
+          assert.equal(context.appOutDir, appOutDir);
+          assert.equal(fs.readFileSync(targetLibraryPath, 'utf8'), 'bundled ffmpeg');
+          operations.push('audit');
+        },
+      },
+    );
+
+    assert.deepEqual(operations, ['stage-bun', 'audit']);
+    assert.deepEqual(stagedOptions, {
+      appOutDir,
+      platform: 'linux',
+      arch: 3,
+      productFilename: 'SubMiner Preview',
+    });
+    assert.equal(fs.readFileSync(targetLibraryPath, 'utf8'), 'bundled ffmpeg');
+  } finally {
+    fs.rmSync(workspace, { recursive: true, force: true });
+  }
+});
diff --git a/scripts/mkv-to-readme-video.sh b/scripts/mkv-to-readme-video.sh
index faadd370..42963ebf 100755
--- a/scripts/mkv-to-readme-video.sh
+++ b/scripts/mkv-to-readme-video.sh
@@ -19,7 +19,8 @@ Options:
   -w, --webp   Generate animated WebP preview
 
 Encoding profile:
-  - Crop: 1920x1080 at x=760 y=200
+  - Crop: mpv region at 1920x1080, x=760 y=205 on a 3440x1440 canvas
+  - Output size: 1920x1080
   - MP4:  H.264 + AAC
   - WebM: AV1/VP9 + Opus at 30 fps
 USAGE
@@ -148,7 +149,8 @@ pick_webp_encoder() {
 	return 1
 }
 
-crop_vf="crop=1920:1080:760:205"
+# OBS may resize the 3440x1440 canvas, so scale the mpv bounds with the input.
+crop_vf="crop=1920*iw/3440:1080*ih/1440:760*iw/3440:205*ih/1440,scale=1920:1080:flags=lanczos"
 webm_vf="${crop_vf},fps=30"
 
 echo "Generating MP4: $mp4_out"
diff --git a/scripts/mkv-to-readme-video.test.ts b/scripts/mkv-to-readme-video.test.ts
index 5ff99b09..91c1b96b 100644
--- a/scripts/mkv-to-readme-video.test.ts
+++ b/scripts/mkv-to-readme-video.test.ts
@@ -40,7 +40,7 @@ function toBashPath(filePath: string): string {
   return `${drive.toUpperCase()}:/${rest}`;
 }
 
-test('mkv-to-readme-video accepts libwebp_anim when libwebp is unavailable', () => {
+test('mkv-to-readme-video builds every output with the scaled mpv crop', () => {
   withTempDir((root) => {
     const binDir = path.join(root, 'bin');
     const inputPath = path.join(root, 'sample.mkv');
@@ -104,5 +104,9 @@ touch "$output"
 
     const ffmpegLog = fs.readFileSync(ffmpegLogPath, 'utf8');
     assert.match(ffmpegLog, /-c:v libwebp_anim/);
+    const scaledCropUses = ffmpegLog.match(
+      /-vf crop=1920\*iw\/3440:1080\*ih\/1440:760\*iw\/3440:205\*ih\/1440,scale=1920:1080:flags=lanczos/g,
+    );
+    assert.equal(scaledCropUses?.length, 4);
   });
 });
diff --git a/scripts/package-audit.cjs b/scripts/package-audit.cjs
new file mode 100644
index 00000000..ad83e40a
--- /dev/null
+++ b/scripts/package-audit.cjs
@@ -0,0 +1,158 @@
+const fs = require('node:fs');
+const path = require('node:path');
+const assert = require('node:assert/strict');
+const asar = require('@electron/asar');
+const { Arch } = require('builder-util');
+
+const REQUIRED_APP_FILES = [
+  'package.json',
+  'LICENSE',
+  'config.example.jsonc',
+  'dist/main-entry.js',
+  'dist/main.js',
+  'dist/preload.js',
+  'dist/preload-settings.js',
+  'dist/preload-syncui.js',
+  'dist/preload-stats.js',
+  'dist/preload-jellyfin-setup.js',
+  'dist/fonts/MPLUS1[wght].ttf',
+  'stats/dist/index.html',
+  'vendor/texthooker-ui/docs/index.html',
+  ...['renderer', 'settings', 'syncui'].flatMap((ui) => [
+    `dist/${ui}/index.html`,
+    `dist/${ui}/style.css`,
+    `dist/${ui}/${ui}.js`,
+  ]),
+];
+const REQUIRED_RESOURCES = [
+  'yomitan/manifest.json',
+  'yomitan/data/fonts/kanji-stroke-orders.ttf',
+  'yomitan/fonts/NotoSansJP-Regular.ttf',
+  'yomitan/lib/resvg.wasm',
+  'launcher/subminer',
+  'plugin/subminer/main.lua',
+  'plugin/subminer.conf',
+  'assets/SubMiner.png',
+  'assets/SubMiner-square.png',
+  'assets/themes/subminer.rasi',
+  'assets/thumbnailers/subminer-ffmpegthumbnailer.thumbnailer',
+  'CHANGELOG.md',
+];
+
+// Skip symlinks when checking resource contents.
+function listFiles(root, prefix = '') {
+  return fs.readdirSync(path.join(root, prefix), { withFileTypes: true }).flatMap((entry) => {
+    const name = prefix ? `${prefix}/${entry.name}` : entry.name;
+    if (entry.isSymbolicLink()) return [];
+    if (entry.isDirectory()) return listFiles(root, name);
+    return [name];
+  });
+}
+
+// asar resolves lookups with the platform separator, so stat with the listed
+// native path and only normalize the reported name.
+function listAppFiles(archive) {
+  return asar.listPackage(archive).flatMap((entry) => {
+    const native = entry.replace(/^[\\/]/, '');
+    const stat = asar.statFile(archive, native);
+    const name = native.replaceAll('\\', '/');
+    return 'size' in stat ? [name] : [];
+  });
+}
+
+function verifyAppPath(name, platform, arch) {
+  const allowedRoots = new Set([
+    'dist',
+    'node_modules',
+    'stats',
+    'vendor',
+    'package.json',
+    'LICENSE',
+    'config.example.jsonc',
+  ]);
+  assert(allowedRoots.has(name.split('/')[0]), `Unexpected app file: ${name}`);
+  assert(!name.endsWith('.map'), `Packaged source map: ${name}`);
+  assert(!/\.(?:[cm]?ts|tsx)$/.test(name), `Packaged TypeScript: ${name}`);
+  assert(!/\.(?:test|spec)\./.test(name), `Packaged test: ${name}`);
+  assert(
+    !/(?:^|\/)(?:tests?|__tests__|fixtures?|__fixtures__)\//.test(name),
+    `Packaged test or fixture directory: ${name}`,
+  );
+  assert(!/^dist\/.*\.test\./.test(name), `Packaged test: ${name}`);
+  assert(!/^dist\/(launcher|scripts)\//.test(name), `Duplicate helper: ${name}`);
+  assert(!/^dist\/(renderer|settings|syncui)\/fonts\//.test(name), `Duplicate font: ${name}`);
+  assert(!name.startsWith('stats/') || name.startsWith('stats/dist/'), `Stats source: ${name}`);
+  assert(
+    !name.startsWith('vendor/') || name.startsWith('vendor/texthooker-ui/docs/'),
+    `Vendor source: ${name}`,
+  );
+  if (name.startsWith('node_modules/koffi/')) {
+    assert.equal(platform, 'win32', `Koffi shipped on ${platform}`);
+    assert(!/^node_modules\/koffi\/(src|vendor|doc)\//.test(name), `Koffi build files: ${name}`);
+    if (name.endsWith('.node')) {
+      assert.equal(name, `node_modules/koffi/build/koffi/win32_${arch}/koffi.node`);
+    }
+  }
+}
+
+function verifyContents(archive, resources, platform, arch) {
+  const entries = listAppFiles(archive);
+  const names = new Set(entries);
+  for (const name of REQUIRED_APP_FILES) assert(names.has(name), `Missing app file: ${name}`);
+  for (const name of REQUIRED_RESOURCES) {
+    assert(fs.statSync(path.join(resources, name)).size > 0, `Empty resource: ${name}`);
+  }
+  assert(listFiles(path.join(resources, 'yomitan-jlpt-vocab')).length > 0, 'Missing JLPT data');
+  for (const name of entries) verifyAppPath(name, platform, arch);
+  const libsqlPlatform = {
+    linux: `linux-${arch}-gnu`,
+    darwin: `darwin-${arch}`,
+    win32: `win32-${arch}-msvc`,
+  }[platform];
+  const libsqlBinary = `node_modules/@libsql/${libsqlPlatform}/index.node`;
+  assert(names.has(libsqlBinary), `Missing SQLite native binary: ${libsqlBinary}`);
+  for (const name of names) {
+    if (name.startsWith('node_modules/@libsql/') && name.endsWith('.node')) {
+      assert.equal(name, libsqlBinary, `Foreign SQLite binary: ${name}`);
+    }
+  }
+  if (platform === 'win32') {
+    for (const name of [
+      'index.js',
+      'package.json',
+      'LICENSE.txt',
+      `build/koffi/win32_${arch}/koffi.node`,
+    ]) {
+      assert(names.has(`node_modules/koffi/${name}`), `Missing Windows FFI file: ${name}`);
+    }
+  }
+  for (const name of listFiles(path.join(resources, 'assets'))) {
+    assert(!name.startsWith('minecard'), `Demo media shipped: ${name}`);
+  }
+  for (const ui of ['renderer', 'settings', 'syncui']) {
+    const css = asar.extractFile(archive, path.join('dist', ui, 'style.css')).toString();
+    assert(css.includes('../fonts/MPLUS1[wght].ttf'), `Shared font missing from ${ui} CSS`);
+  }
+  return entries;
+}
+
+async function auditPackage(context) {
+  const platform = context.electronPlatformName;
+  const arch = Arch[context.arch];
+  const key = `${platform}-${arch}`;
+  const appRoot =
+    platform === 'darwin'
+      ? path.join(context.appOutDir, `${context.packager.appInfo.productFilename}.app`)
+      : context.appOutDir;
+  const resources = path.join(appRoot, platform === 'darwin' ? 'Contents/Resources' : 'resources');
+  verifyContents(path.join(resources, 'app.asar'), resources, platform, arch);
+  console.log(`Package contents verified: ${key}`);
+}
+
+module.exports = {
+  auditPackage,
+  verifyContents,
+  verifyAppPath,
+  listFiles,
+  listAppFiles,
+};
diff --git a/scripts/package-audit.test.ts b/scripts/package-audit.test.ts
new file mode 100644
index 00000000..285ccd84
--- /dev/null
+++ b/scripts/package-audit.test.ts
@@ -0,0 +1,155 @@
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, writeFileSync, statSync, rmSync, createReadStream } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import test from 'node:test';
+import { createPackageFromStreams } from '@electron/asar';
+import { FileMatcher, getFileMatchers } from 'app-builder-lib/out/fileMatcher';
+import config from '../package.json';
+import { listAppFiles, listFiles, verifyAppPath } from './package-audit.cjs';
+
+test('platform packaging preserves the runtime allowlist after builder normalizes global filters', () => {
+  const root = process.cwd();
+  const fileStat = statSync('package.json');
+  for (const platform of ['linux', 'mac', 'win'] as const) {
+    const matchers = getFileMatchers(
+      { files: [{ filter: config.build.files }] },
+      'files',
+      '/tmp/subminer-filter-output',
+      {
+        defaultSrc: root,
+        globalOutDir: path.join(root, 'release'),
+        customBuildOptions: { files: config.build[platform].files },
+        macroExpander: (value) => value.replaceAll('${arch}', 'x64'),
+      },
+    );
+    assert(matchers);
+    // This is builder's default for an exclusion-only platform matcher.
+    for (const matcher of matchers) {
+      if (matcher.containsOnlyIgnore()) matcher.prependPattern('**/*');
+    }
+    const included = (name: string) =>
+      matchers.some((matcher) => matcher.createFilter()(path.join(root, name), fileStat));
+    for (const name of [
+      'dist/main-entry.js',
+      'dist/fonts/MPLUS1[wght].ttf',
+      'stats/dist/index.html',
+      'vendor/texthooker-ui/docs/index.html',
+      'package.json',
+    ]) {
+      assert(included(name), `${platform} must ship ${name}`);
+    }
+    for (const name of [
+      '.agents/skills/test.md',
+      'src/main.ts',
+      'scripts/build-yomitan.mjs',
+      'docs-site/index.md',
+      'dist/main.js.map',
+      'dist/main.test.js',
+      'dist/nested/source.ts',
+      'dist/nested/__tests__/helper.js',
+      'stats/dist/nested/fixtures/data.json',
+      'vendor/texthooker-ui/docs/nested/component.tsx',
+      'dist/launcher/subminer',
+      'dist/settings/fonts/MPLUS1[wght].ttf',
+      'vendor/subminer-yomitan/ext/manifest.json',
+    ]) {
+      assert(!included(name), `${platform} must exclude ${name}`);
+    }
+  }
+});
+
+test('dependency filters keep only the target Windows Koffi binary', () => {
+  const root = process.cwd();
+  for (const arch of ['x64', 'arm64']) {
+    for (const platform of ['linux', 'mac', 'win'] as const) {
+      const patterns = [
+        '**/*',
+        ...config.build.files.filter((name) => name.startsWith('!')),
+        ...config.build[platform].files.filter((name) => name.startsWith('!')),
+      ];
+      const filter = new FileMatcher(
+        root,
+        '/tmp/subminer-filter-output',
+        (value) => value.replaceAll('${arch}', arch),
+        patterns,
+      ).createFilter();
+      const included = (name: string) =>
+        filter(path.join(root, 'node_modules', name), statSync('package.json'));
+      assert(included('@libsql/win32-x64-msvc/index.node'));
+      assert(!included('axios/dist/axios.js.map'));
+      assert(!included('koffi/src/koffi/src/ffi.c'));
+      assert(!included('agent-base/src/index.ts'));
+      assert(!included('@discordjs/rest/dist/index.d.mts'));
+      assert(!included('example/lib/tests/helper.js'));
+      for (const target of [
+        'win32_x64',
+        'win32_arm64',
+        'linux_x64',
+        'darwin_arm64',
+        'openbsd_x64',
+      ]) {
+        assert.equal(
+          included(`koffi/build/koffi/${target}/koffi.node`),
+          platform === 'win' && target === `win32_${arch}`,
+          `${platform}/${arch}: ${target}`,
+        );
+      }
+      assert.equal(included('koffi/index.js'), platform === 'win');
+      assert.equal(included('koffi/LICENSE.txt'), platform === 'win');
+    }
+  }
+});
+
+test('content audit rejects development files beneath approved roots', () => {
+  for (const root of ['dist', 'stats/dist', 'vendor/texthooker-ui/docs', 'node_modules/example']) {
+    for (const suffix of [
+      'nested/source.ts',
+      'nested/component.tsx',
+      'nested/types.d.mts',
+      'nested/source.cts',
+      'nested/__tests__/helper.js',
+      'nested/tests/helper.js',
+      'nested/test/helper.js',
+      'nested/__fixtures__/data.json',
+      'nested/fixtures/data.json',
+      'nested/fixture/data.json',
+      'nested/component.spec.js',
+      'nested/component.test.cjs',
+    ]) {
+      assert.throws(() => verifyAppPath(`${root}/${suffix}`, 'linux', 'x64'), /Packaged/);
+    }
+    for (const suffix of ['nested/runtime.js', 'nested/style.css', 'nested/data.json']) {
+      assert.doesNotThrow(() => verifyAppPath(`${root}/${suffix}`, 'linux', 'x64'));
+    }
+  }
+});
+
+test('content inventory includes packed and unpacked native files', async () => {
+  const root = mkdtempSync(path.join(tmpdir(), 'subminer-audit-'));
+  try {
+    const input = path.join(root, 'input');
+    const output = path.join(root, 'output');
+    mkdirSync(input);
+    mkdirSync(output);
+    writeFileSync(path.join(input, 'main.js'), 'hello');
+    writeFileSync(path.join(input, 'native.node'), 'native');
+    mkdirSync(path.join(input, 'dist', 'ai'), { recursive: true });
+    writeFileSync(path.join(input, 'dist', 'ai', 'client.js'), 'nested');
+    const archive = path.join(output, 'app.asar');
+    await createPackageFromStreams(
+      archive,
+      ['main.js', 'native.node', 'dist/ai/client.js'].map((name) => ({
+        path: name,
+        type: 'file',
+        unpacked: name.endsWith('.node'),
+        stat: statSync(path.join(input, name)),
+        streamGenerator: () => createReadStream(path.join(input, name)),
+      })),
+    );
+    assert.deepEqual(listAppFiles(archive), ['main.js', 'native.node', 'dist/ai/client.js']);
+    assert.deepEqual(listFiles(output).sort(), ['app.asar', 'app.asar.unpacked/native.node']);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
diff --git a/scripts/package-bun-source.mjs b/scripts/package-bun-source.mjs
new file mode 100644
index 00000000..1d88d3c6
--- /dev/null
+++ b/scripts/package-bun-source.mjs
@@ -0,0 +1,456 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { createReadStream, createWriteStream } from 'node:fs';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { pipeline } from 'node:stream/promises';
+import { Readable } from 'node:stream';
+
+const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+const repoRoot = path.resolve(scriptDir, '..');
+
+export const DEFAULT_MANIFEST_PATH = path.join(repoRoot, 'build', 'bun-source-manifest.json');
+export const DEFAULT_RUNTIME_MANIFEST_PATH = path.join(
+  repoRoot,
+  'build',
+  'bun-runtime-manifest.json',
+);
+export const DEFAULT_PACKAGE_JSON_PATH = path.join(repoRoot, 'package.json');
+export const DEFAULT_OUTPUT_DIR = path.join(repoRoot, 'release');
+export const DEFAULT_CACHE_DIR = path.join(repoRoot, '.tmp', 'bun-corresponding-source');
+
+function isRecord(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function requiredString(record, key, source) {
+  const value = record[key];
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new Error(`${source} must contain a non-empty ${key} string.`);
+  }
+  return value;
+}
+
+function assertSafeRelativePath(value, source) {
+  if (path.isAbsolute(value) || value.split(/[\\/]/).includes('..')) {
+    throw new Error(`${source} contains an unsafe path: ${value}`);
+  }
+}
+
+export function parseSourceManifest(value) {
+  if (!isRecord(value) || value.schemaVersion !== 1) {
+    throw new Error('Bun source manifest must use schemaVersion 1.');
+  }
+  const version = requiredString(value, 'version', 'Bun source manifest');
+  const bunRevision = requiredString(value, 'bunRevision', 'Bun source manifest');
+  const archiveName = requiredString(value, 'archiveName', 'Bun source manifest');
+  if (!/^\d+\.\d+\.\d+$/.test(version) || !/^[a-f0-9]{40}$/.test(bunRevision)) {
+    throw new Error('Bun source manifest has an invalid version or bunRevision.');
+  }
+  if (path.basename(archiveName) !== archiveName || !archiveName.endsWith('.tar.gz')) {
+    throw new Error('Bun source manifest archiveName must be a safe .tar.gz filename.');
+  }
+  if (!Array.isArray(value.sources) || value.sources.length === 0) {
+    throw new Error('Bun source manifest must contain sources.');
+  }
+
+  const names = new Set();
+  const destinations = new Set();
+  const sources = value.sources.map((entry, index) => {
+    if (!isRecord(entry)) throw new Error(`Bun source ${index} must be an object.`);
+    const name = requiredString(entry, 'name', `Bun source ${index}`);
+    const repository = requiredString(entry, 'repository', `Bun source ${name}`);
+    const revision = requiredString(entry, 'revision', `Bun source ${name}`);
+    const destination = requiredString(entry, 'destination', `Bun source ${name}`);
+    if (!/^[\w.-]+\/[\w.-]+$/.test(repository) || !/^[a-f0-9]{40}$/.test(revision)) {
+      throw new Error(`Bun source ${name} has an invalid repository or revision.`);
+    }
+    assertSafeRelativePath(destination, `Bun source ${name}`);
+    if (names.has(name) || destinations.has(destination)) {
+      throw new Error(`Bun source manifest repeats ${name} or ${destination}.`);
+    }
+    names.add(name);
+    destinations.add(destination);
+
+    const transport = entry.transport ?? 'archive';
+    if (transport !== 'archive' && transport !== 'git-sparse') {
+      throw new Error(`Bun source ${name} has unsupported transport ${transport}.`);
+    }
+    const sha256 =
+      transport === 'archive' ? requiredString(entry, 'sha256', `Bun source ${name}`) : null;
+    if (sha256 !== null && !/^[a-f0-9]{64}$/.test(sha256)) {
+      throw new Error(`Bun source ${name} has an invalid SHA-256 digest.`);
+    }
+    if (!Array.isArray(entry.licensePaths) || entry.licensePaths.length === 0) {
+      throw new Error(`Bun source ${name} must declare licensePaths.`);
+    }
+    const licensePaths = entry.licensePaths.map((licensePath) => {
+      if (typeof licensePath !== 'string' || licensePath.length === 0) {
+        throw new Error(`Bun source ${name} has an invalid license path.`);
+      }
+      assertSafeRelativePath(licensePath, `Bun source ${name}`);
+      return licensePath;
+    });
+    const exclude = Array.isArray(entry.exclude) ? entry.exclude : [];
+    for (const excludedPath of exclude) assertSafeRelativePath(excludedPath, `Bun source ${name}`);
+    return {
+      ...entry,
+      name,
+      repository,
+      revision,
+      destination,
+      transport,
+      sha256,
+      licensePaths,
+      exclude,
+    };
+  });
+
+  const bun = sources.find((source) => source.name === 'bun');
+  if (!bun || bun.revision !== bunRevision || bun.destination !== 'bun') {
+    throw new Error('Bun source manifest must map bunRevision to the bun source at bun/.');
+  }
+  return { ...value, version, bunRevision, archiveName, sources };
+}
+
+export function parseRegisteredRepositories(cmakeText) {
+  const registrations = new Map();
+  const uncommented = cmakeText.replace(/#[^\n]*/g, '');
+  for (const match of uncommented.matchAll(/register_repository\(([\s\S]*?)\)/g)) {
+    const body = match[1];
+    const name = /\bNAME\s+([^\s#)]+)/.exec(body)?.[1];
+    const repository = /\bREPOSITORY\s+([^\s#)]+)/.exec(body)?.[1];
+    const reference = /\b(COMMIT|TAG)\s+(?:#[^\n]*\n\s*)?([^\s#)]+)/.exec(body);
+    if (name && repository && reference) {
+      registrations.set(name, {
+        repository,
+        kind: reference[1].toLowerCase(),
+        reference: reference[2],
+      });
+    }
+  }
+  return registrations;
+}
+
+export function validateRuntimeAlignment(manifest, packageJson, runtimeManifest) {
+  if (!isRecord(packageJson) || packageJson.packageManager !== `bun@${manifest.version}`) {
+    throw new Error(
+      `package.json must pin bun@${manifest.version} to match the Bun source manifest.`,
+    );
+  }
+  if (!isRecord(runtimeManifest)) throw new Error('Bun runtime manifest must be an object.');
+  for (const key of ['version', 'bunRevision']) {
+    if (runtimeManifest[key] !== manifest[key]) {
+      throw new Error(`Bun runtime manifest ${key} does not match the Bun source manifest.`);
+    }
+  }
+  if (runtimeManifest.correspondingSourceAsset !== manifest.archiveName) {
+    throw new Error(
+      'Bun runtime manifest correspondingSourceAsset does not match the Bun source manifest.',
+    );
+  }
+}
+
+export function validateBunPins(manifest, cmakeTexts, setupWebKitText) {
+  const actual = new Map();
+  for (const cmakeText of cmakeTexts) {
+    for (const [name, registration] of parseRegisteredRepositories(cmakeText)) {
+      if (actual.has(name)) throw new Error(`Bun registers ${name} more than once.`);
+      actual.set(name, registration);
+    }
+  }
+  const expected = new Map(
+    manifest.sources
+      .filter((source) => source.destination.startsWith('bun/vendor/') && source.name !== 'WebKit')
+      .map((source) => [source.name, source]),
+  );
+  for (const [name, registration] of actual) {
+    const source = expected.get(name);
+    if (!source) throw new Error(`Source manifest omits Bun dependency ${name}.`);
+    if (source.repository !== registration.repository) {
+      throw new Error(`Source manifest repository mismatch for ${name}.`);
+    }
+    const expectedReference = source.upstreamReference ?? source.revision;
+    if (expectedReference !== registration.reference) {
+      throw new Error(`Source manifest revision mismatch for ${name}.`);
+    }
+    expected.delete(name);
+  }
+  if (expected.size > 0) {
+    throw new Error(
+      `Source manifest has unregistered Bun dependencies: ${[...expected.keys()].join(', ')}.`,
+    );
+  }
+
+  const webKitPin = /set\(WEBKIT_VERSION\s+([a-f0-9]{40})\)/.exec(setupWebKitText)?.[1];
+  const webKit = manifest.sources.find((source) => source.name === 'WebKit');
+  if (!webKitPin || !webKit || webKit.revision !== webKitPin) {
+    throw new Error('Source manifest WebKit revision does not match SetupWebKit.cmake.');
+  }
+}
+
+async function sha256File(filePath) {
+  const hash = createHash('sha256');
+  for await (const chunk of createReadStream(filePath)) hash.update(chunk);
+  return hash.digest('hex');
+}
+
+async function run(command, args, options = {}) {
+  await new Promise((resolve, reject) => {
+    const child = spawn(command, args, { stdio: 'inherit', ...options });
+    child.once('error', reject);
+    child.once('close', (code) => {
+      if (code === 0) resolve();
+      else reject(new Error(`${command} exited with status ${code}.`));
+    });
+  });
+}
+
+export async function downloadArchive(source, cacheDir, fetchImpl) {
+  const archivePath = path.join(cacheDir, `${source.name}-${source.revision}.tar.gz`);
+  try {
+    if ((await sha256File(archivePath)) === source.sha256) return archivePath;
+    await fs.rm(archivePath, { force: true });
+  } catch (error) {
+    if (!isRecord(error) || error.code !== 'ENOENT') throw error;
+  }
+
+  const url = `https://codeload.github.com/${source.repository}/tar.gz/${source.revision}`;
+  const temporaryPath = `${archivePath}.download-${randomUUID()}`;
+  try {
+    const response = await fetchImpl(url);
+    if (!response.ok || !response.body)
+      throw new Error(`Unable to download ${url}: HTTP ${response.status}`);
+    await pipeline(
+      Readable.fromWeb(response.body),
+      createWriteStream(temporaryPath, { flags: 'wx' }),
+    );
+    const actualSha256 = await sha256File(temporaryPath);
+    if (actualSha256 !== source.sha256) {
+      throw new Error(
+        `Source checksum mismatch for ${source.name}: expected ${source.sha256}, received ${actualSha256}.`,
+      );
+    }
+    await fs.rename(temporaryPath, archivePath);
+    return archivePath;
+  } finally {
+    // Cleanup must not replace the original download, validation, or rename error.
+    await fs.rm(temporaryPath, { force: true }).catch(() => {});
+  }
+}
+
+async function materializeArchive(source, root, cacheDir, fetchImpl) {
+  const archivePath = await downloadArchive(source, cacheDir, fetchImpl);
+  const destination = path.join(root, source.destination);
+  await fs.mkdir(destination, { recursive: true });
+  await run('tar', ['-xzf', archivePath, '-C', destination, '--strip-components=1']);
+}
+
+async function materializeGitSparse(source, root, cacheDir) {
+  const checkout = path.join(cacheDir, `${source.name}-${source.revision}-git`);
+  await fs.rm(checkout, { recursive: true, force: true });
+  await run('git', [
+    'clone',
+    '--filter=blob:none',
+    '--no-checkout',
+    '--depth=1',
+    `https://github.com/${source.repository}.git`,
+    checkout,
+  ]);
+  await run('git', ['-C', checkout, 'fetch', '--depth=1', 'origin', source.revision]);
+  await run('git', ['-C', checkout, 'sparse-checkout', 'init', '--no-cone']);
+  const sparseRules = ['/*', ...source.exclude.map((entry) => `!/${entry}/`), ''];
+  await fs.writeFile(
+    path.join(checkout, '.git', 'info', 'sparse-checkout'),
+    sparseRules.join('\n'),
+  );
+  await run('git', ['-C', checkout, 'checkout', '--detach', source.revision]);
+  const actualRevision = (await fs.readFile(path.join(checkout, '.git', 'HEAD'), 'utf8')).trim();
+  if (actualRevision !== source.revision)
+    throw new Error(`Git checkout mismatch for ${source.name}.`);
+  await fs.rm(path.join(checkout, '.git'), { recursive: true, force: true });
+  await fs.mkdir(path.dirname(path.join(root, source.destination)), { recursive: true });
+  await fs.rename(checkout, path.join(root, source.destination));
+}
+
+async function applyBunDependencyPatches(root, manifest) {
+  const bunRoot = path.join(root, 'bun');
+  for (const source of manifest.sources) {
+    if (!source.destination.startsWith('bun/vendor/') || source.name === 'WebKit') continue;
+    const destination = path.join(root, source.destination);
+    const patchDirectory = path.join(bunRoot, 'patches', source.name);
+    let entries = [];
+    try {
+      entries = await fs.readdir(patchDirectory, { withFileTypes: true });
+    } catch (error) {
+      if (!isRecord(error) || error.code !== 'ENOENT') throw error;
+    }
+    for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
+      const patchPath = path.join(patchDirectory, entry.name);
+      if (entry.isFile() && entry.name.endsWith('.patch')) {
+        await run(
+          'git',
+          ['apply', '--ignore-whitespace', '--ignore-space-change', '--no-index', patchPath],
+          { cwd: destination },
+        );
+      } else if (entry.isFile()) {
+        await fs.copyFile(patchPath, path.join(destination, entry.name));
+      }
+    }
+    const cmakeReference = source.upstreamReference
+      ? `refs/tags/${source.upstreamReference}`
+      : source.revision;
+    await fs.writeFile(path.join(destination, '.ref'), `${cmakeReference}\n`);
+  }
+}
+
+async function validateAndCollectLicenses(root, manifest) {
+  const licensesRoot = path.join(root, 'THIRD-PARTY-LICENSES');
+  await fs.mkdir(licensesRoot, { recursive: true });
+  for (const source of manifest.sources) {
+    const target = path.join(licensesRoot, source.name);
+    await fs.mkdir(target, { recursive: true });
+    for (const licensePath of source.licensePaths) {
+      const sourcePath = path.join(root, source.destination, licensePath);
+      const stat = await fs.stat(sourcePath).catch(() => null);
+      if (!stat?.isFile() || stat.size === 0) {
+        throw new Error(`Missing required license material for ${source.name}: ${licensePath}`);
+      }
+      const safeName = licensePath.replaceAll('/', '__');
+      await fs.copyFile(sourcePath, path.join(target, safeName));
+    }
+  }
+}
+
+function rebuildReadme(manifest) {
+  const webKit = manifest.sources.find((source) => source.name === 'WebKit');
+  const tinycc = manifest.sources.find((source) => source.name === 'tinycc');
+  return `# Bun ${manifest.version} corresponding source and rebuild materials
+
+This archive matches the official Bun ${manifest.version} binaries whose \`bun --revision\` output names commit \`${manifest.bunRevision}\`. The GitHub release tag points to \`${manifest.releaseTagCommit}\`, one later commit, so this package intentionally uses the binary revision.
+
+The archive includes Bun's complete source tree, Bun's build scripts and dependency patches, every external repository registered by Bun's CMake build at its exact pin, and Oven's WebKit fork at \`${webKit.revision}\`. Large WebKit test-only trees are excluded. The JavaScriptCore, WTF, WebCore, build-tool, configuration, and resource trees used to build the library are included. TinyCC is \`${tinycc.revision}\`.
+
+## Rebuild with modified JavaScriptCore
+
+Install the prerequisites recorded in \`bun/.buildkite/Dockerfile\`, \`bun/scripts/bootstrap.sh\`, and the WebKit platform build scripts. Bun ${manifest.version} used LLVM 19.1.7, CMake 3.30.5 in its Linux build image, and Bun 1.1.38 as the bootstrap runtime. Its Rust input was nightly and was not pinned to a dated toolchain in the release source.
+
+From this archive root on Linux or macOS:
+
+\`\`\`sh
+cd bun
+bun install --frozen-lockfile
+bun run jsc:build
+bun run build:release:local -- -DVERSION=${manifest.version} -DREVISION=${manifest.bunRevision}
+\`\`\`
+
+The first command uses the bootstrap Bun. \`jsc:build\` builds the included \`vendor/WebKit\` checkout into \`vendor/WebKit/WebKitBuild/Release\`. \`build:release:local\` links Bun against that local JavaScriptCore build. The explicit version and revision replace metadata that Bun normally reads from its Git checkout. The included \`vendor/*/.ref\` files prevent Bun's CMake rules from replacing the packaged dependency sources, and this package has already applied the files under \`bun/patches/<dependency>/\` in the same order as \`bun/cmake/scripts/GitClone.cmake\`.
+
+The archive vendors the source repositories that Bun's CMake build links into the executable. It preserves Bun's \`bun.lock\` files and lol-html's \`Cargo.lock\`, but it does not vendor npm packages, crates.io packages used to build lol-html, compilers, SDKs, or other build tools. The rebuild therefore needs network access for those pinned package-manager inputs. License notices embedded in those downloaded packages are outside the collected \`THIRD-PARTY-LICENSES\` directory's scope.
+
+Windows uses the prerequisites in \`bun/docs/project/building-windows.mdx\` and WebKit's \`windows-release.ps1\`. The local-JavaScriptCore path above has not been verified on Windows.
+
+These instructions describe the source and build entry points. Toolchain and generated-output differences mean a rebuild is not expected to be byte-for-byte identical to Oven's release binary. No claim about legal compliance or reproducible builds is made here.
+`;
+}
+
+async function createDeterministicArchive(stagingParent, rootName, outputPath) {
+  const temporaryTar = `${outputPath}.tar-${randomUUID()}`;
+  const temporaryGzip = `${outputPath}.gzip-${randomUUID()}`;
+  try {
+    await run('tar', [
+      '--sort=name',
+      '--mtime=@0',
+      '--owner=0',
+      '--group=0',
+      '--numeric-owner',
+      '-cf',
+      temporaryTar,
+      '-C',
+      stagingParent,
+      rootName,
+    ]);
+    const gzip = spawn('gzip', ['-n', '-9', '-c', temporaryTar], {
+      stdio: ['ignore', 'pipe', 'inherit'],
+    });
+    const completion = new Promise((resolve, reject) => {
+      gzip.once('error', reject);
+      gzip.once('close', resolve);
+    });
+    const [, code] = await Promise.all([
+      pipeline(gzip.stdout, createWriteStream(temporaryGzip, { flags: 'wx' })),
+      completion,
+    ]);
+    if (code !== 0) throw new Error(`gzip exited with status ${code}.`);
+    await fs.rm(outputPath, { force: true });
+    await fs.rename(temporaryGzip, outputPath);
+  } finally {
+    await Promise.all([
+      fs.rm(temporaryTar, { force: true }),
+      fs.rm(temporaryGzip, { force: true }),
+    ]);
+  }
+}
+
+export async function packageBunSource({
+  manifestPath = DEFAULT_MANIFEST_PATH,
+  runtimeManifestPath = DEFAULT_RUNTIME_MANIFEST_PATH,
+  packageJsonPath = DEFAULT_PACKAGE_JSON_PATH,
+  outputDir = DEFAULT_OUTPUT_DIR,
+  cacheDir = DEFAULT_CACHE_DIR,
+  fetchImpl = globalThis.fetch,
+} = {}) {
+  const [manifestText, runtimeManifestText, packageJsonText] = await Promise.all([
+    fs.readFile(manifestPath, 'utf8'),
+    fs.readFile(runtimeManifestPath, 'utf8'),
+    fs.readFile(packageJsonPath, 'utf8'),
+  ]);
+  const manifest = parseSourceManifest(JSON.parse(manifestText));
+  validateRuntimeAlignment(manifest, JSON.parse(packageJsonText), JSON.parse(runtimeManifestText));
+  if (typeof fetchImpl !== 'function') throw new Error('No fetch implementation is available.');
+  await fs.mkdir(cacheDir, { recursive: true });
+  const stagingParent = await fs.mkdtemp(path.join(cacheDir, 'assemble-'));
+  const rootName = path.basename(manifest.archiveName, '.tar.gz');
+  const root = path.join(stagingParent, rootName);
+  await fs.mkdir(root);
+
+  try {
+    const bun = manifest.sources.find((source) => source.name === 'bun');
+    await materializeArchive(bun, root, cacheDir, fetchImpl);
+    const cmakeFiles = (await fs.readdir(path.join(root, 'bun', 'cmake', 'targets')))
+      .filter((name) => name.endsWith('.cmake'))
+      .map((name) => fs.readFile(path.join(root, 'bun', 'cmake', 'targets', name), 'utf8'));
+    validateBunPins(
+      manifest,
+      await Promise.all(cmakeFiles),
+      await fs.readFile(path.join(root, 'bun', 'cmake', 'tools', 'SetupWebKit.cmake'), 'utf8'),
+    );
+
+    for (const source of manifest.sources.filter((entry) => entry.name !== 'bun')) {
+      if (source.transport === 'git-sparse') await materializeGitSparse(source, root, cacheDir);
+      else await materializeArchive(source, root, cacheDir, fetchImpl);
+    }
+    await applyBunDependencyPatches(root, manifest);
+    await validateAndCollectLicenses(root, manifest);
+    await fs.writeFile(
+      path.join(root, 'SOURCE-INVENTORY.json'),
+      `${JSON.stringify(manifest, null, 2)}\n`,
+    );
+    await fs.writeFile(path.join(root, 'README-REBUILD.md'), rebuildReadme(manifest));
+
+    await fs.mkdir(outputDir, { recursive: true });
+    const outputPath = path.join(outputDir, manifest.archiveName);
+    await createDeterministicArchive(stagingParent, rootName, outputPath);
+    const digest = await sha256File(outputPath);
+    await fs.writeFile(`${outputPath}.sha256`, `${digest}  ${manifest.archiveName}\n`);
+    return { outputPath, sha256: digest };
+  } finally {
+    await fs.rm(stagingParent, { recursive: true, force: true });
+  }
+}
+
+if (import.meta.main) {
+  const result = await packageBunSource();
+  console.log(`${result.sha256}  ${path.basename(result.outputPath)}`);
+}
diff --git a/scripts/package-bun-source.test.ts b/scripts/package-bun-source.test.ts
new file mode 100644
index 00000000..d361523a
--- /dev/null
+++ b/scripts/package-bun-source.test.ts
@@ -0,0 +1,153 @@
+import { describe, expect, test } from 'bun:test';
+import { createHash } from 'node:crypto';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import {
+  downloadArchive,
+  parseRegisteredRepositories,
+  parseSourceManifest,
+  validateBunPins,
+  validateRuntimeAlignment,
+} from './package-bun-source.mjs';
+
+const projectRoot = path.resolve(import.meta.dir, '..');
+
+describe('Bun corresponding-source manifest', () => {
+  test('removes partial downloads when placing a valid archive fails', async () => {
+    const cacheDir = await fs.mkdtemp(path.join(os.tmpdir(), 'subminer-bun-source-test-'));
+    try {
+      const payload = new Uint8Array([1, 2, 3]);
+      const source = {
+        name: 'fixture',
+        repository: 'example/fixture',
+        revision: 'a'.repeat(40),
+        sha256: createHash('sha256').update(payload).digest('hex'),
+      };
+      const archivePath = path.join(cacheDir, `${source.name}-${source.revision}.tar.gz`);
+      await expect(
+        downloadArchive(source, cacheDir, async () => {
+          await fs.mkdir(archivePath);
+          return { ok: true, status: 200, body: new Response(payload).body };
+        }),
+      ).rejects.toMatchObject({ syscall: 'rename' });
+
+      const entries = await fs.readdir(cacheDir);
+      expect(entries.filter((entry) => entry.includes('.download-'))).toEqual([]);
+    } finally {
+      await fs.rm(cacheDir, { recursive: true, force: true });
+    }
+  });
+
+  test('pins the source to the revision reported by the distributed binary', async () => {
+    const manifest = parseSourceManifest(
+      JSON.parse(
+        await fs.readFile(path.join(projectRoot, 'build/bun-source-manifest.json'), 'utf8'),
+      ),
+    );
+
+    expect(manifest.version).toBe('1.3.5');
+    expect(manifest.bunRevision).toBe('1e86cebd74a5723e818b5c0555276b646bcf0e4c');
+    expect(manifest.releaseTagCommit).toBe('fa5a5bbe556a4bda5bde77b4013aa6c3bb4ec9ab');
+    expect(manifest.sources.find((source) => source.name === 'WebKit')?.revision).toBe(
+      '6d0f3aac0b817cc01a846b3754b21271adedac12',
+    );
+    expect(manifest.sources.find((source) => source.name === 'tinycc')?.revision).toBe(
+      '29985a3b59898861442fa3b43f663fc1af2591d7',
+    );
+  });
+
+  test('parses commit and tag registrations from Bun CMake', () => {
+    const registrations = parseRegisteredRepositories(`
+      register_repository(
+        NAME tinycc
+        REPOSITORY oven-sh/tinycc
+        COMMIT
+          # A comment between the field and its value is valid CMake.
+          29985a3b59898861442fa3b43f663fc1af2591d7
+      )
+      register_repository(
+        NAME brotli
+        REPOSITORY google/brotli
+        TAG v1.1.0
+      )
+    `);
+
+    expect(registrations.get('tinycc')).toEqual({
+      repository: 'oven-sh/tinycc',
+      kind: 'commit',
+      reference: '29985a3b59898861442fa3b43f663fc1af2591d7',
+    });
+    expect(registrations.get('brotli')).toEqual({
+      repository: 'google/brotli',
+      kind: 'tag',
+      reference: 'v1.1.0',
+    });
+  });
+
+  test('rejects stale runtime or package-manager pins', async () => {
+    const manifest = parseSourceManifest(
+      JSON.parse(
+        await fs.readFile(path.join(projectRoot, 'build/bun-source-manifest.json'), 'utf8'),
+      ),
+    );
+    const runtimeManifest = {
+      version: manifest.version,
+      bunRevision: manifest.bunRevision,
+      correspondingSourceAsset: manifest.archiveName,
+    };
+
+    expect(() =>
+      validateRuntimeAlignment(manifest, { packageManager: 'bun@1.3.5' }, runtimeManifest),
+    ).not.toThrow();
+    expect(() =>
+      validateRuntimeAlignment(manifest, { packageManager: 'bun@1.3.6' }, runtimeManifest),
+    ).toThrow('package.json must pin bun@1.3.5');
+    expect(() =>
+      validateRuntimeAlignment(
+        manifest,
+        { packageManager: 'bun@1.3.5' },
+        {
+          ...runtimeManifest,
+          correspondingSourceAsset: 'stale.tar.gz',
+        },
+      ),
+    ).toThrow('correspondingSourceAsset does not match');
+  });
+
+  test('rejects drift in CMake dependency and WebKit pins', async () => {
+    const manifest = parseSourceManifest(
+      JSON.parse(
+        await fs.readFile(path.join(projectRoot, 'build/bun-source-manifest.json'), 'utf8'),
+      ),
+    );
+    const registrations = manifest.sources
+      .filter((source) => source.destination.startsWith('bun/vendor/') && source.name !== 'WebKit')
+      .map(
+        (source) => `register_repository(
+          NAME ${source.name}
+          REPOSITORY ${source.repository}
+          ${source.upstreamReference ? 'TAG' : 'COMMIT'} ${source.upstreamReference ?? source.revision}
+        )`,
+      )
+      .join('\n');
+
+    expect(() =>
+      validateBunPins(
+        manifest,
+        [registrations],
+        'set(WEBKIT_VERSION 6d0f3aac0b817cc01a846b3754b21271adedac12)',
+      ),
+    ).not.toThrow();
+    expect(() =>
+      validateBunPins(
+        manifest,
+        [registrations.replace('29985a3b59898861442fa3b43f663fc1af2591d7', '0'.repeat(40))],
+        'set(WEBKIT_VERSION 6d0f3aac0b817cc01a846b3754b21271adedac12)',
+      ),
+    ).toThrow('revision mismatch for tinycc');
+    expect(() =>
+      validateBunPins(manifest, [registrations], `set(WEBKIT_VERSION ${'0'.repeat(40)})`),
+    ).toThrow('WebKit revision does not match');
+  });
+});
diff --git a/scripts/prepare-build-assets.mjs b/scripts/prepare-build-assets.mjs
index fad72b3c..652b7c4c 100644
--- a/scripts/prepare-build-assets.mjs
+++ b/scripts/prepare-build-assets.mjs
@@ -1,7 +1,9 @@
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import { execFileSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
+import { stageBundledIntegrationKeys, TMDB_API_KEY_ENV } from './bundled-integration-keys.mjs';
 
 const scriptDir = path.dirname(fileURLToPath(import.meta.url));
 const repoRoot = path.resolve(scriptDir, '..');
@@ -28,10 +30,6 @@ function copyFile(sourcePath, outputPath) {
 function copyAssets(sourceDir, outputDir, label) {
   copyFile(path.join(sourceDir, 'index.html'), path.join(outputDir, 'index.html'));
   copyFile(path.join(sourceDir, 'style.css'), path.join(outputDir, 'style.css'));
-  fs.cpSync(path.join(rendererSourceDir, 'fonts'), path.join(outputDir, 'fonts'), {
-    recursive: true,
-    force: true,
-  });
   process.stdout.write(`Staged ${label} assets in ${outputDir}\n`);
 }
 
@@ -52,6 +50,16 @@ function fallbackToMacosSource() {
   process.stdout.write(`Staged macOS helper source fallback: ${macosHelperSourceCopyPath}\n`);
 }
 
+// Pin the minimum macOS to the app's own floor (Electron's `minos`). Without an
+// explicit target, swiftc stamps the build machine's OS version as the binary's
+// minimum and the helper fails to load on older systems (#213). The arch stays
+// the host's, matching the single-arch app electron-builder packages here.
+const MACOS_HELPER_DEPLOYMENT_TARGET = '12.0';
+
+function macosHelperTarget() {
+  return `${os.arch() === 'x64' ? 'x86_64' : 'arm64'}-apple-macos${MACOS_HELPER_DEPLOYMENT_TARGET}`;
+}
+
 function shouldSkipMacosHelperBuild() {
   return process.env.SUBMINER_SKIP_MACOS_HELPER_BUILD === '1';
 }
@@ -72,9 +80,13 @@ function buildMacosHelper() {
   ensureDir(scriptsOutputDir);
 
   try {
-    execFileSync('swiftc', ['-O', macosHelperSourcePath, '-o', macosHelperBinaryPath], {
-      stdio: 'inherit',
-    });
+    execFileSync(
+      'swiftc',
+      ['-O', '-target', macosHelperTarget(), macosHelperSourcePath, '-o', macosHelperBinaryPath],
+      {
+        stdio: 'inherit',
+      },
+    );
     fs.chmodSync(macosHelperBinaryPath, 0o755);
     process.stdout.write(`Built macOS helper: ${macosHelperBinaryPath}\n`);
   } catch (error) {
@@ -86,11 +98,27 @@ function buildMacosHelper() {
   }
 }
 
+// Only the key names are logged, never the values: CI masks secrets, but a
+// stray echo would still leak them into local build logs.
+function stageIntegrationKeys() {
+  const staged = stageBundledIntegrationKeys(path.join(repoRoot, 'dist'));
+  process.stdout.write(
+    staged.length > 0
+      ? `Staged bundled integration keys: ${staged.join(', ')}\n`
+      : `No bundled integration keys (${TMDB_API_KEY_ENV} unset)\n`,
+  );
+}
+
 function main() {
+  fs.cpSync(path.join(rendererSourceDir, 'fonts'), path.join(repoRoot, 'dist', 'fonts'), {
+    recursive: true,
+    force: true,
+  });
   copyRendererAssets();
   copySettingsAssets();
   copySyncUiAssets();
   buildMacosHelper();
+  stageIntegrationKeys();
 }
 
 main();
diff --git a/scripts/prepare-build-assets.test.ts b/scripts/prepare-build-assets.test.ts
index 13f64fe2..d710f8b9 100644
--- a/scripts/prepare-build-assets.test.ts
+++ b/scripts/prepare-build-assets.test.ts
@@ -8,7 +8,7 @@ test('macOS helper build creates dist scripts directory before swiftc output', (
   const buildFunctionIndex = source.indexOf('function buildMacosHelper()');
   assert.notEqual(buildFunctionIndex, -1);
 
-  const swiftcIndex = source.indexOf("execFileSync('swiftc'", buildFunctionIndex);
+  const swiftcIndex = source.indexOf("'swiftc'", buildFunctionIndex);
   assert.notEqual(swiftcIndex, -1);
 
   const ensureDirIndex = source.lastIndexOf('ensureDir(scriptsOutputDir)', swiftcIndex);
@@ -18,3 +18,10 @@ test('macOS helper build creates dist scripts directory before swiftc output', (
     'buildMacosHelper must create dist/scripts before swiftc writes the helper binary',
   );
 });
+
+// Regression guard for #213: an untargeted swiftc stamps the build machine's OS
+// version as the helper's minimum, so released builds refuse to load on older macOS.
+test('macOS helper is compiled with an explicit deployment target', () => {
+  assert.match(source, /-target/);
+  assert.match(source, /apple-macos\$\{MACOS_HELPER_DEPLOYMENT_TARGET\}/);
+});
diff --git a/scripts/print-docs-version-manifest.ts b/scripts/print-docs-version-manifest.ts
deleted file mode 100644
index e6fc107e..00000000
--- a/scripts/print-docs-version-manifest.ts
+++ /dev/null
@@ -1,41 +0,0 @@
-import { spawnSync } from 'node:child_process';
-import { resolve } from 'node:path';
-import { buildVersionManifest, stableTagsWithDocs } from './docs-versioning';
-
-const repoRoot = resolve(__dirname, '..');
-
-function capture(command: string, args: string[]): string {
-  const result = spawnSync(command, args, {
-    cwd: repoRoot,
-    encoding: 'utf8',
-  });
-
-  if (result.status !== 0) {
-    throw new Error(result.stderr || `Command failed: ${command} ${args.join(' ')}`);
-  }
-
-  return result.stdout;
-}
-
-function tagHasDocsSite(tag: string): boolean {
-  const result = spawnSync('git', ['cat-file', '-e', `${tag}:docs-site/package.json`], {
-    cwd: repoRoot,
-  });
-  return result.status === 0;
-}
-
-const stableVersions = stableTagsWithDocs(
-  capture('git', ['tag', '--list', 'v*'])
-    .split('\n')
-    .map((tag) => tag.trim())
-    .filter(Boolean),
-  tagHasDocsSite,
-);
-
-const latestStable = stableVersions[0];
-
-if (!latestStable) {
-  throw new Error('No stable release tags with docs-site/package.json found.');
-}
-
-process.stdout.write(JSON.stringify(buildVersionManifest({ latestStable, stableVersions })));
diff --git a/scripts/run-coverage-lane.test.ts b/scripts/run-coverage-lane.test.ts
index 7c6f0c86..2a5fa2e7 100644
--- a/scripts/run-coverage-lane.test.ts
+++ b/scripts/run-coverage-lane.test.ts
@@ -1,8 +1,10 @@
 import assert from 'node:assert/strict';
-import { resolve } from 'node:path';
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
 import test from 'node:test';
 
-import { mergeLcovReports, resolveCoverageDir } from './run-coverage-lane';
+import { mergeLcovReports, resolveCoverageDir, runCoverageLane } from './run-coverage-lane';
 
 test('mergeLcovReports combines duplicate source-file counters across shard outputs', () => {
   const merged = mergeLcovReports([
@@ -72,3 +74,33 @@ test('resolveCoverageDir keeps coverage output inside the repository', () => {
   assert.throws(() => resolveCoverageDir(repoRoot, ['--coverage-dir', '../escape']));
   assert.throws(() => resolveCoverageDir(repoRoot, ['--coverage-dir', '/tmp/escape']));
 });
+
+test('runCoverageLane returns a failure when a discovered test fails', () => {
+  const repoRoot = mkdtempSync(join(tmpdir(), 'subminer-coverage-failure-'));
+  try {
+    mkdirSync(join(repoRoot, 'src'));
+    writeFileSync(
+      join(repoRoot, 'src', 'failure.test.ts'),
+      [
+        "import assert from 'node:assert/strict';",
+        "import test from 'node:test';",
+        '',
+        "test('intentional coverage failure', () => {",
+        "  assert.fail('coverage runner must propagate this failure');",
+        '});',
+        '',
+      ].join('\n'),
+    );
+
+    assert.notEqual(
+      runCoverageLane({
+        repoRootDir: repoRoot,
+        argv: ['bun-src-full', '--coverage-dir', 'coverage/test-src'],
+        stdio: 'pipe',
+      }),
+      0,
+    );
+  } finally {
+    rmSync(repoRoot, { recursive: true, force: true });
+  }
+});
diff --git a/scripts/run-coverage-lane.ts b/scripts/run-coverage-lane.ts
index 3140a623..5d567b40 100644
--- a/scripts/run-coverage-lane.ts
+++ b/scripts/run-coverage-lane.ts
@@ -201,14 +201,18 @@ export function mergeLcovReports(reports: string[]): string {
   return chunks.length > 0 ? `${chunks.join('\n')}\n` : '';
 }
 
-function runCoverageLane(): number {
-  const laneName = process.argv[2];
+export function runCoverageLane(
+  options: { repoRootDir?: string; argv?: string[]; stdio?: 'inherit' | 'pipe' } = {},
+): number {
+  const repoRootDir = options.repoRootDir ?? repoRoot;
+  const argv = options.argv ?? process.argv.slice(2);
+  const laneName = argv[0];
   if (laneName === undefined) {
     process.stderr.write('Missing coverage lane name\n');
     return 1;
   }
 
-  const coverageDir = resolveCoverageDir(repoRoot, process.argv.slice(3));
+  const coverageDir = resolveCoverageDir(repoRootDir, argv.slice(1));
   const shardRoot = join(coverageDir, '.shards');
   mkdirSync(coverageDir, { recursive: true });
   rmSync(shardRoot, { recursive: true, force: true });
@@ -216,7 +220,7 @@ function runCoverageLane(): number {
 
   let files: string[];
   try {
-    files = collectLaneFiles(repoRoot, laneName);
+    files = collectLaneFiles(repoRootDir, laneName);
   } catch (error) {
     process.stderr.write(`${error instanceof Error ? error.message : error}\n`);
     return 1;
@@ -230,8 +234,8 @@ function runCoverageLane(): number {
         'bun',
         ['test', '--coverage', '--coverage-reporter=lcov', '--coverage-dir', shardDir, `./${file}`],
         {
-          cwd: repoRoot,
-          stdio: 'inherit',
+          cwd: repoRootDir,
+          stdio: options.stdio ?? 'inherit',
         },
       );
 
@@ -253,7 +257,7 @@ function runCoverageLane(): number {
 
     writeFileSync(join(coverageDir, 'lcov.info'), mergeLcovReports(reports), 'utf8');
     process.stdout.write(
-      `Merged LCOV written to ${relative(repoRoot, join(coverageDir, 'lcov.info'))}\n`,
+      `Merged LCOV written to ${relative(repoRootDir, join(coverageDir, 'lcov.info'))}\n`,
     );
     return 0;
   } finally {
diff --git a/scripts/run-package-smoke.mjs b/scripts/run-package-smoke.mjs
new file mode 100644
index 00000000..6a44335e
--- /dev/null
+++ b/scripts/run-package-smoke.mjs
@@ -0,0 +1,29 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+
+const resources = process.argv[2];
+if (!resources) throw new Error('Usage: bun run test:package <resources-directory>');
+const require = createRequire(import.meta.url);
+const profile = fs.mkdtempSync(path.join(os.tmpdir(), 'subminer-package-smoke-'));
+const env = { ...process.env, SUBMINER_PACKAGE_SMOKE_DATA: profile };
+delete env.ELECTRON_RUN_AS_NODE;
+try {
+  const result = spawnSync(
+    require('electron'),
+    [
+      fileURLToPath(new URL('./smoke-package.cjs', import.meta.url)),
+      path.resolve(resources),
+      // CI runners lack a setuid chrome-sandbox; this harness never loads remote content.
+      ...(process.platform === 'linux' ? ['--no-sandbox'] : []),
+    ],
+    { env, stdio: 'inherit', timeout: 75_000 },
+  );
+  if (result.error) throw result.error;
+  process.exitCode = result.status ?? 1;
+} finally {
+  fs.rmSync(profile, { recursive: true, force: true, maxRetries: 3 });
+}
diff --git a/scripts/smoke-package.cjs b/scripts/smoke-package.cjs
new file mode 100644
index 00000000..8eb49fb4
--- /dev/null
+++ b/scripts/smoke-package.cjs
@@ -0,0 +1,138 @@
+// Run with the pinned Electron runtime against a finished app's resources folder.
+const { app, BrowserWindow, session } = require('electron');
+const fs = require('node:fs');
+const http = require('node:http');
+const path = require('node:path');
+const { createRequire } = require('node:module');
+const assert = require('node:assert/strict');
+const { once } = require('node:events');
+
+const resources = path.resolve(process.argv[2]);
+const archive = path.join(resources, 'app.asar');
+const isolatedData = process.env.SUBMINER_PACKAGE_SMOKE_DATA;
+assert(
+  isolatedData && fs.existsSync(isolatedData),
+  'Use bun run test:package to create an isolated profile',
+);
+app.setPath('userData', isolatedData);
+app.disableHardwareAcceleration();
+app.on('window-all-closed', () => {});
+const timeout = setTimeout(() => {
+  console.error('Package smoke timed out');
+  app.exit(1);
+}, 60_000);
+
+const STATIC_TYPES = {
+  '.html': 'text/html',
+  '.js': 'text/javascript',
+  '.css': 'text/css',
+  '.png': 'image/png',
+  '.svg': 'image/svg+xml',
+  '.woff2': 'font/woff2',
+  '.ttf': 'font/ttf',
+  '.json': 'application/json',
+};
+
+// The stats dashboard is served by the stats HTTP server in the app, so load it
+// over loopback HTTP from the packaged stats/dist and treat missing static
+// assets as failures. API routes are not part of this smoke and may 404.
+function serveStatsDist(root, failedRequests) {
+  const server = http.createServer((req, res) => {
+    const pathname = new URL(req.url, 'http://127.0.0.1').pathname;
+    const relative = pathname === '/' ? 'index.html' : pathname.slice(1);
+    try {
+      const body = fs.readFileSync(path.join(root, relative));
+      res.writeHead(200, {
+        'Content-Type': STATIC_TYPES[path.extname(relative)] ?? 'application/octet-stream',
+      });
+      res.end(body);
+    } catch {
+      if (!pathname.startsWith('/api/')) failedRequests.push(`${req.url}: missing static asset`);
+      res.writeHead(404).end();
+    }
+  });
+  server.listen(0, '127.0.0.1');
+  return server;
+}
+
+async function smoke() {
+  await app.whenReady();
+  const packagedRequire = createRequire(path.join(archive, 'package.json'));
+  const Database = packagedRequire('libsql');
+  const database = new Database(':memory:');
+  assert.equal(database.prepare('select 42 as answer').get().answer, 42);
+  database.close();
+  if (process.platform === 'win32') {
+    const win32 = packagedRequire('./dist/window-trackers/win32.js');
+    assert(Array.isArray(win32.findMpvWindows().matches));
+  }
+  const { Texthooker } = packagedRequire('./dist/core/services/texthooker.js');
+  const texthooker = new Texthooker();
+  const server = texthooker.start(0);
+  assert(server, 'Packaged texthooker assets could not be found');
+  try {
+    await once(server, 'listening');
+    const response = await fetch(`http://127.0.0.1:${server.address().port}/`);
+    assert.equal(response.status, 200);
+    assert((await response.text()).includes('<html'));
+  } finally {
+    texthooker.stop();
+  }
+  const extension = await session.defaultSession.extensions.loadExtension(
+    path.join(resources, 'yomitan'),
+    { allowFileAccess: true },
+  );
+  assert(extension.id, 'Yomitan extension failed to load');
+  const failedRequests = [];
+  session.defaultSession.webRequest.onErrorOccurred(
+    { urls: ['file://*/*', 'http://127.0.0.1/*'] },
+    (details) => {
+      // Chromium probes the cache before fetching @font-face fonts; an uncached
+      // font reports ERR_CACHE_MISS and is then fetched normally.
+      if (!['net::ERR_ABORTED', 'net::ERR_CACHE_MISS'].includes(details.error))
+        failedRequests.push(`${details.url}: ${details.error}`);
+    },
+  );
+  const statsServer = serveStatsDist(path.join(archive, 'stats', 'dist'), failedRequests);
+  await once(statsServer, 'listening');
+  for (const ui of ['renderer', 'settings', 'syncui', 'stats']) {
+    const win = new BrowserWindow({
+      show: false,
+      webPreferences: {
+        sandbox: false,
+        preload: path.join(archive, 'dist', ui === 'renderer' ? 'preload.js' : `preload-${ui}.js`),
+      },
+    });
+    try {
+      if (ui === 'stats') {
+        await win.loadURL(`http://127.0.0.1:${statsServer.address().port}/`);
+        // Let in-flight font requests settle before the window goes away.
+        await win.webContents.executeJavaScript('document.fonts.ready.then(() => true)');
+      } else {
+        await win.loadFile(path.join(archive, `dist/${ui}/index.html`));
+        const loaded = await win.webContents.executeJavaScript(
+          `document.fonts.load('400 16px "M PLUS 1"', '日本語').then(fonts => fonts.length > 0 && fonts.every(font => font.status === 'loaded'))`,
+        );
+        assert(loaded, `${ui}: shared Japanese font failed to load`);
+      }
+    } finally {
+      win.destroy();
+    }
+  }
+  statsServer.close();
+  assert.deepEqual(failedRequests, [], 'Packaged UI resources failed to load');
+  console.log(
+    'Package smoke passed: SQLite, platform FFI, texthooker, Yomitan loading, UI pages, shared Japanese font.',
+  );
+}
+
+smoke()
+  .then(() => {
+    clearTimeout(timeout);
+    app.exit(0);
+  })
+  .catch((error) => {
+    console.error(error);
+    clearTimeout(timeout);
+    app.exit(1);
+  });
diff --git a/scripts/stage-bun-runtime.mjs b/scripts/stage-bun-runtime.mjs
new file mode 100644
index 00000000..e18ce7ec
--- /dev/null
+++ b/scripts/stage-bun-runtime.mjs
@@ -0,0 +1,389 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { createReadStream, createWriteStream } from 'node:fs';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { pipeline } from 'node:stream/promises';
+import { Readable } from 'node:stream';
+import { promisify } from 'node:util';
+import { execFile } from 'node:child_process';
+
+const execFileAsync = promisify(execFile);
+const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+const repoRoot = path.resolve(scriptDir, '..');
+
+export const DEFAULT_PACKAGE_JSON_PATH = path.join(repoRoot, 'package.json');
+export const DEFAULT_MANIFEST_PATH = path.join(repoRoot, 'build', 'bun-runtime-manifest.json');
+export const DEFAULT_CACHE_DIR = path.join(repoRoot, '.tmp', 'bun-runtime');
+export const DEFAULT_LICENSES_SOURCE_DIR = path.join(repoRoot, 'resources', 'bun', 'licenses');
+export const STAGED_METADATA_FILE = 'metadata.json';
+export const REQUIRED_LICENSE_FILES = [
+  'Bun-LICENSE.md',
+  'LGPL-2.0.txt',
+  'LGPL-2.1.txt',
+  'SOURCE.md',
+  'THIRD-PARTY-NOTICES.md',
+];
+
+const RELEASE_BASE_URL = 'https://github.com/oven-sh/bun/releases/download';
+const SUPPORTED_PLATFORMS = new Set(['darwin', 'linux', 'win32']);
+const ARCH_BY_BUILDER_VALUE = new Map([
+  [1, 'x64'],
+  [3, 'arm64'],
+  ['x64', 'x64'],
+  ['arm64', 'arm64'],
+]);
+
+function isRecord(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function readRequiredString(record, key, source) {
+  const value = record[key];
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new Error(`${source} must contain a non-empty ${key} string.`);
+  }
+  return value;
+}
+
+function readCommit(record, key, source) {
+  const value = readRequiredString(record, key, source);
+  if (!/^[a-f0-9]{40}$/.test(value)) {
+    throw new Error(`${source} must contain a 40-character ${key} commit.`);
+  }
+  return value;
+}
+
+export function normalizeTarget(platform, arch) {
+  if (!SUPPORTED_PLATFORMS.has(platform)) {
+    throw new Error(`Unsupported Bun runtime target platform: ${platform}`);
+  }
+
+  const normalizedArch = ARCH_BY_BUILDER_VALUE.get(arch);
+  if (!normalizedArch) {
+    throw new Error(`Unsupported Bun runtime target architecture for ${platform}: ${String(arch)}`);
+  }
+  if (platform === 'win32' && normalizedArch !== 'x64') {
+    throw new Error(`Unsupported Bun runtime target: ${platform}-${normalizedArch}`);
+  }
+
+  return {
+    platform,
+    arch: normalizedArch,
+    key: `${platform}-${normalizedArch}`,
+    executableName: platform === 'win32' ? 'bun.exe' : 'bun',
+  };
+}
+
+export function parsePackageManagerVersion(packageJson) {
+  if (!isRecord(packageJson)) {
+    throw new Error('package.json must contain a JSON object.');
+  }
+  const packageManager = readRequiredString(packageJson, 'packageManager', 'package.json');
+  const match = /^bun@(\d+\.\d+\.\d+)$/.exec(packageManager);
+  if (!match) {
+    throw new Error(
+      `package.json packageManager must pin Bun exactly, received ${packageManager}.`,
+    );
+  }
+  return match[1];
+}
+
+function parseArtifact(value, key) {
+  if (!isRecord(value)) {
+    throw new Error(`Bun runtime manifest artifact ${key} must be an object.`);
+  }
+  const file = readRequiredString(value, 'file', `Bun runtime manifest artifact ${key}`);
+  const sha256 = readRequiredString(value, 'sha256', `Bun runtime manifest artifact ${key}`);
+  if (!/^[a-f0-9]{64}$/.test(sha256)) {
+    throw new Error(`Bun runtime manifest artifact ${key} has an invalid SHA-256 digest.`);
+  }
+  if (path.basename(file) !== file || !file.endsWith('.zip')) {
+    throw new Error(`Bun runtime manifest artifact ${key} has an unsafe file name.`);
+  }
+  return { file, sha256 };
+}
+
+export function parseRuntimeManifest(manifest, version) {
+  if (!isRecord(manifest) || manifest.schemaVersion !== 1) {
+    throw new Error('Bun runtime manifest must use schemaVersion 1.');
+  }
+  const manifestVersion = readRequiredString(manifest, 'version', 'Bun runtime manifest');
+  if (manifestVersion !== version) {
+    throw new Error(
+      `Bun runtime manifest version ${manifestVersion} does not match packageManager bun@${version}.`,
+    );
+  }
+  if (!isRecord(manifest.artifacts)) {
+    throw new Error('Bun runtime manifest must contain an artifacts object.');
+  }
+  return {
+    version,
+    bunRevision: readCommit(manifest, 'bunRevision', 'Bun runtime manifest'),
+    releaseTagCommit: readCommit(manifest, 'releaseTagCommit', 'Bun runtime manifest'),
+    artifacts: manifest.artifacts,
+    licenseInventoryStatus: readRequiredString(
+      manifest,
+      'licenseInventoryStatus',
+      'Bun runtime manifest',
+    ),
+    sourceManifest: readRequiredString(manifest, 'sourceManifest', 'Bun runtime manifest'),
+    correspondingSourceAsset: readRequiredString(
+      manifest,
+      'correspondingSourceAsset',
+      'Bun runtime manifest',
+    ),
+  };
+}
+
+export async function loadRuntimeConfig({
+  packageJsonPath = DEFAULT_PACKAGE_JSON_PATH,
+  manifestPath = DEFAULT_MANIFEST_PATH,
+} = {}) {
+  const [packageJsonText, manifestText] = await Promise.all([
+    fs.readFile(packageJsonPath, 'utf8'),
+    fs.readFile(manifestPath, 'utf8'),
+  ]);
+  const version = parsePackageManagerVersion(JSON.parse(packageJsonText));
+  return parseRuntimeManifest(JSON.parse(manifestText), version);
+}
+
+export function resolveArtifact(config, platform, arch) {
+  const target = normalizeTarget(platform, arch);
+  const artifactValue = config.artifacts[target.key];
+  if (artifactValue === undefined) {
+    throw new Error(`Bun runtime manifest has no artifact for ${target.key}.`);
+  }
+  const artifact = parseArtifact(artifactValue, target.key);
+  return {
+    ...target,
+    ...artifact,
+    version: config.version,
+    url: `${RELEASE_BASE_URL}/bun-v${config.version}/${artifact.file}`,
+  };
+}
+
+export async function sha256File(filePath) {
+  const hash = createHash('sha256');
+  for await (const chunk of createReadStream(filePath)) {
+    hash.update(chunk);
+  }
+  return hash.digest('hex');
+}
+
+export async function ensureCachedArchive(
+  artifact,
+  { cacheDir = DEFAULT_CACHE_DIR, fetchImpl = globalThis.fetch } = {},
+) {
+  if (typeof fetchImpl !== 'function') {
+    throw new Error('No fetch implementation is available to download Bun.');
+  }
+  const versionCacheDir = path.join(cacheDir, artifact.version);
+  const archivePath = path.join(versionCacheDir, artifact.file);
+  await fs.mkdir(versionCacheDir, { recursive: true });
+
+  try {
+    if ((await sha256File(archivePath)) === artifact.sha256) return archivePath;
+    await fs.unlink(archivePath);
+  } catch (error) {
+    if (!isRecord(error) || error.code !== 'ENOENT') throw error;
+  }
+
+  const temporaryPath = `${archivePath}.download-${randomUUID()}`;
+  try {
+    const response = await fetchImpl(artifact.url);
+    if (!response.ok || !response.body) {
+      throw new Error(`Unable to download ${artifact.url}: HTTP ${response.status}`);
+    }
+    await pipeline(
+      Readable.fromWeb(response.body),
+      createWriteStream(temporaryPath, { flags: 'wx' }),
+    );
+    const actualSha256 = await sha256File(temporaryPath);
+    if (actualSha256 !== artifact.sha256) {
+      throw new Error(
+        `Bun archive checksum mismatch for ${artifact.file}: expected ${artifact.sha256}, received ${actualSha256}.`,
+      );
+    }
+    await fs.rename(temporaryPath, archivePath);
+    return archivePath;
+  } catch (error) {
+    await fs.rm(temporaryPath, { force: true });
+    throw error;
+  }
+}
+
+function isSafeZipEntry(entry) {
+  if (entry.startsWith('/') || /^[A-Za-z]:/.test(entry)) return false;
+  return !entry.replaceAll('\\', '/').split('/').includes('..');
+}
+
+function waitForProcess(child, description) {
+  let stderr = '';
+  child.stderr.setEncoding('utf8');
+  child.stderr.on('data', (chunk) => {
+    stderr += chunk;
+  });
+  return new Promise((resolve, reject) => {
+    child.once('error', reject);
+    child.once('close', (code) => {
+      if (code === 0) resolve();
+      else reject(new Error(`${description}: ${stderr.trim() || `process exited ${code}`}`));
+    });
+  });
+}
+
+export function buildWindowsExtractionCommand(archivePath, member, outputPath) {
+  const script = [
+    'Add-Type -AssemblyName System.IO.Compression.FileSystem',
+    '$archive = [IO.Compression.ZipFile]::OpenRead($env:SUBMINER_BUN_ARCHIVE_PATH)',
+    'try {',
+    '  $entry = $archive.Entries | Where-Object { $_.FullName -ceq $env:SUBMINER_BUN_ARCHIVE_MEMBER }',
+    '  if ($null -eq $entry) { throw "Archive member not found: $env:SUBMINER_BUN_ARCHIVE_MEMBER" }',
+    '  $inputStream = $entry.Open()',
+    '  $outputStream = [IO.File]::Create($env:SUBMINER_BUN_OUTPUT_PATH)',
+    '  try { $inputStream.CopyTo($outputStream) } finally { $outputStream.Dispose(); $inputStream.Dispose() }',
+    '} finally { $archive.Dispose() }',
+  ].join('; ');
+  return {
+    command: 'powershell.exe',
+    args: [
+      '-NoLogo',
+      '-NoProfile',
+      '-NonInteractive',
+      '-EncodedCommand',
+      Buffer.from(script, 'utf16le').toString('base64'),
+    ],
+    environment: {
+      SUBMINER_BUN_ARCHIVE_PATH: archivePath,
+      SUBMINER_BUN_ARCHIVE_MEMBER: member,
+      SUBMINER_BUN_OUTPUT_PATH: outputPath,
+    },
+  };
+}
+
+async function extractZipMemberOnWindows(archivePath, member, outputPath) {
+  const command = buildWindowsExtractionCommand(archivePath, member, outputPath);
+  const powershell = spawn(command.command, command.args, {
+    env: { ...process.env, ...command.environment },
+    stdio: ['ignore', 'ignore', 'pipe'],
+  });
+  await waitForProcess(powershell, `Unable to extract ${member}`);
+}
+
+export async function extractZipMember(archivePath, member, outputPath) {
+  if (!isSafeZipEntry(member)) {
+    throw new Error(`Refusing to extract unsafe Bun archive member ${member}.`);
+  }
+  await fs.mkdir(path.dirname(outputPath), { recursive: true });
+  const temporaryPath = `${outputPath}.extract-${randomUUID()}`;
+
+  if (process.platform === 'win32') {
+    try {
+      await extractZipMemberOnWindows(archivePath, member, temporaryPath);
+      await fs.chmod(temporaryPath, 0o755);
+      await fs.rename(temporaryPath, outputPath);
+    } catch (error) {
+      await fs.rm(temporaryPath, { force: true });
+      throw error;
+    }
+    return;
+  }
+
+  const { stdout } = await execFileAsync('unzip', ['-Z1', archivePath], {
+    encoding: 'utf8',
+    maxBuffer: 1024 * 1024,
+  });
+  const entries = stdout.split(/\r?\n/).filter(Boolean);
+  if (entries.some((entry) => !isSafeZipEntry(entry))) {
+    throw new Error(`Bun archive ${archivePath} contains an unsafe path.`);
+  }
+  if (!entries.includes(member)) {
+    throw new Error(`Bun archive ${archivePath} does not contain ${member}.`);
+  }
+
+  const output = createWriteStream(temporaryPath, { flags: 'wx', mode: 0o755 });
+  const unzip = spawn('unzip', ['-p', archivePath, member], { stdio: ['ignore', 'pipe', 'pipe'] });
+
+  try {
+    await Promise.all([
+      pipeline(unzip.stdout, output),
+      waitForProcess(unzip, `Unable to extract ${member}`),
+    ]);
+    await fs.chmod(temporaryPath, 0o755);
+    await fs.rename(temporaryPath, outputPath);
+  } catch (error) {
+    await fs.rm(temporaryPath, { force: true });
+    throw error;
+  }
+}
+
+export function resolveResourcesDirectory(appOutDir, platform, productFilename = 'SubMiner') {
+  if (platform !== 'darwin') return path.join(appOutDir, 'resources');
+  const appBundlePath = appOutDir.endsWith('.app')
+    ? appOutDir
+    : path.join(appOutDir, `${productFilename}.app`);
+  return path.join(appBundlePath, 'Contents', 'Resources');
+}
+
+export async function stageBunLicenses(
+  runtimeDirectory,
+  licensesSourceDir = DEFAULT_LICENSES_SOURCE_DIR,
+) {
+  const licensesDirectory = path.join(runtimeDirectory, 'licenses');
+  await Promise.all(
+    REQUIRED_LICENSE_FILES.map((fileName) => fs.access(path.join(licensesSourceDir, fileName))),
+  );
+  await fs.cp(licensesSourceDir, licensesDirectory, { recursive: true, force: true });
+  return licensesDirectory;
+}
+
+export async function stageBunRuntime(
+  { appOutDir, platform, arch, productFilename = 'SubMiner' },
+  {
+    configLoader = loadRuntimeConfig,
+    archiveLoader = ensureCachedArchive,
+    extractor = extractZipMember,
+    licenseStager = stageBunLicenses,
+  } = {},
+) {
+  const config = await configLoader();
+  const artifact = resolveArtifact(config, platform, arch);
+  const archivePath = await archiveLoader(artifact);
+  const archiveDirectory = path.basename(artifact.file, '.zip');
+  const archiveExecutableName = platform === 'win32' ? 'bun.exe' : 'bun';
+  const member = `${archiveDirectory}/${archiveExecutableName}`;
+  const runtimeDirectory = path.join(
+    resolveResourcesDirectory(appOutDir, platform, productFilename),
+    'bun',
+  );
+  const executablePath = path.join(runtimeDirectory, artifact.executableName);
+  await extractor(archivePath, member, executablePath);
+  await licenseStager(runtimeDirectory);
+
+  const metadata = {
+    name: 'Bun',
+    version: config.version,
+    bunRevision: config.bunRevision,
+    releaseTagCommit: config.releaseTagCommit,
+    target: artifact.key,
+    artifact: artifact.file,
+    artifactSha256: artifact.sha256,
+    sourceUrl: artifact.url,
+    licenseInventoryStatus: config.licenseInventoryStatus,
+    correspondingSourceAsset: config.correspondingSourceAsset,
+    sourceInstructions: 'licenses/SOURCE.md',
+    thirdPartyNotices: 'licenses/THIRD-PARTY-NOTICES.md',
+  };
+  await fs.writeFile(
+    path.join(runtimeDirectory, STAGED_METADATA_FILE),
+    `${JSON.stringify(metadata, null, 2)}\n`,
+    { mode: 0o644 },
+  );
+  return {
+    executablePath,
+    metadataPath: path.join(runtimeDirectory, STAGED_METADATA_FILE),
+    artifact,
+  };
+}
diff --git a/scripts/stage-bun-runtime.test.ts b/scripts/stage-bun-runtime.test.ts
new file mode 100644
index 00000000..56f1c255
--- /dev/null
+++ b/scripts/stage-bun-runtime.test.ts
@@ -0,0 +1,307 @@
+import assert from 'node:assert/strict';
+import { createHash } from 'node:crypto';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import test from 'node:test';
+
+import {
+  buildWindowsExtractionCommand,
+  ensureCachedArchive,
+  extractZipMember,
+  loadRuntimeConfig,
+  normalizeTarget,
+  parsePackageManagerVersion,
+  parseRuntimeManifest,
+  resolveArtifact,
+  stageBunLicenses,
+  stageBunRuntime,
+} from './stage-bun-runtime.mjs';
+
+function sha256(content: Uint8Array): string {
+  return createHash('sha256').update(content).digest('hex');
+}
+
+function runtimeConfig() {
+  return {
+    version: '1.3.5',
+    bunRevision: '1e86cebd74a5723e818b5c0555276b646bcf0e4c',
+    releaseTagCommit: 'fa5a5bbe556a4bda5bde77b4013aa6c3bb4ec9ab',
+    artifacts: {
+      'darwin-arm64': { file: 'bun-darwin-aarch64.zip', sha256: '1'.repeat(64) },
+      'darwin-x64': { file: 'bun-darwin-x64-baseline.zip', sha256: '2'.repeat(64) },
+      'linux-arm64': { file: 'bun-linux-aarch64.zip', sha256: '3'.repeat(64) },
+      'linux-x64': { file: 'bun-linux-x64-baseline.zip', sha256: '4'.repeat(64) },
+      'win32-x64': { file: 'bun-windows-x64-baseline.zip', sha256: '5'.repeat(64) },
+    },
+    licenseInventoryStatus: 'complete-for-bun-1.3.5-declared-linked-libraries',
+    sourceManifest: 'build/bun-source-manifest.json',
+    correspondingSourceAsset: 'bun-v1.3.5-source.tar.gz',
+  };
+}
+
+test('normalizeTarget maps each supported electron-builder target without using the host', () => {
+  assert.deepEqual(normalizeTarget('linux', 1), {
+    platform: 'linux',
+    arch: 'x64',
+    key: 'linux-x64',
+    executableName: 'bun',
+  });
+  assert.equal(normalizeTarget('linux', 3).key, 'linux-arm64');
+  assert.equal(normalizeTarget('darwin', 'x64').key, 'darwin-x64');
+  assert.equal(normalizeTarget('darwin', 'arm64').key, 'darwin-arm64');
+  assert.deepEqual(normalizeTarget('win32', 1), {
+    platform: 'win32',
+    arch: 'x64',
+    key: 'win32-x64',
+    executableName: 'bun.exe',
+  });
+  assert.throws(() => normalizeTarget('freebsd', 'x64'), /Unsupported Bun runtime target platform/);
+  assert.throws(() => normalizeTarget('win32', 'arm64'), /Unsupported Bun runtime target/);
+  assert.throws(() => normalizeTarget('linux', 0), /Unsupported Bun runtime target architecture/);
+});
+
+test('resolveArtifact chooses baseline x64 builds and standard arm64 builds', () => {
+  const config = runtimeConfig();
+  assert.equal(resolveArtifact(config, 'linux', 'x64').file, 'bun-linux-x64-baseline.zip');
+  assert.equal(resolveArtifact(config, 'darwin', 'x64').file, 'bun-darwin-x64-baseline.zip');
+  assert.equal(resolveArtifact(config, 'win32', 'x64').file, 'bun-windows-x64-baseline.zip');
+  assert.equal(resolveArtifact(config, 'linux', 'arm64').file, 'bun-linux-aarch64.zip');
+  assert.equal(resolveArtifact(config, 'darwin', 'arm64').file, 'bun-darwin-aarch64.zip');
+});
+
+test('tracked runtime manifest covers every supported target at the packageManager version', async () => {
+  const config = await loadRuntimeConfig();
+  assert.equal(config.version, '1.3.5');
+  for (const [platform, arch] of [
+    ['linux', 'x64'],
+    ['linux', 'arm64'],
+    ['darwin', 'x64'],
+    ['darwin', 'arm64'],
+    ['win32', 'x64'],
+  ]) {
+    const artifact = resolveArtifact(config, platform, arch);
+    assert.match(artifact.sha256, /^[a-f0-9]{64}$/);
+    assert.equal(
+      artifact.url,
+      `https://github.com/oven-sh/bun/releases/download/bun-v1.3.5/${artifact.file}`,
+    );
+  }
+});
+
+test('manifest version must match the exact packageManager Bun pin', () => {
+  assert.equal(parsePackageManagerVersion({ packageManager: 'bun@1.3.5' }), '1.3.5');
+  assert.throws(
+    () => parsePackageManagerVersion({ packageManager: 'bun@^1.3.5' }),
+    /must pin Bun exactly/,
+  );
+  assert.throws(
+    () =>
+      parseRuntimeManifest(
+        {
+          schemaVersion: 1,
+          version: '1.3.6',
+          bunRevision: '1e86cebd74a5723e818b5c0555276b646bcf0e4c',
+          releaseTagCommit: 'fa5a5bbe556a4bda5bde77b4013aa6c3bb4ec9ab',
+          artifacts: {},
+          licenseInventoryStatus: 'partial',
+          sourceManifest: 'build/bun-source-manifest.json',
+          correspondingSourceAsset: 'bun-v1.3.5-source.tar.gz',
+        },
+        '1.3.5',
+      ),
+    /does not match packageManager bun@1\.3\.5/,
+  );
+});
+
+test('ensureCachedArchive verifies downloads and reuses a verified cache entry offline', async () => {
+  const workspace = await fs.mkdtemp(path.join(os.tmpdir(), 'subminer-bun-cache-'));
+  const bytes = new TextEncoder().encode('verified Bun archive fixture');
+  const artifact = {
+    version: '1.3.5',
+    file: 'bun-linux-x64-baseline.zip',
+    sha256: sha256(bytes),
+    url: 'https://example.invalid/bun.zip',
+  };
+  let downloads = 0;
+  const fetchImpl = async () => {
+    downloads += 1;
+    return new Response(bytes);
+  };
+
+  try {
+    const firstPath = await ensureCachedArchive(artifact, { cacheDir: workspace, fetchImpl });
+    const secondPath = await ensureCachedArchive(artifact, {
+      cacheDir: workspace,
+      fetchImpl: async () => {
+        throw new Error('verified cache should not fetch');
+      },
+    });
+    assert.equal(firstPath, secondPath);
+    assert.equal(downloads, 1);
+    assert.deepEqual(await fs.readFile(firstPath), Buffer.from(bytes));
+  } finally {
+    await fs.rm(workspace, { recursive: true, force: true });
+  }
+});
+
+test('ensureCachedArchive rejects a checksum mismatch without caching the download', async () => {
+  const workspace = await fs.mkdtemp(path.join(os.tmpdir(), 'subminer-bun-cache-mismatch-'));
+  const artifact = {
+    version: '1.3.5',
+    file: 'bun-linux-x64-baseline.zip',
+    sha256: '0'.repeat(64),
+    url: 'https://example.invalid/bun.zip',
+  };
+
+  try {
+    await assert.rejects(
+      ensureCachedArchive(artifact, {
+        cacheDir: workspace,
+        fetchImpl: async () => new Response('tampered'),
+      }),
+      /checksum mismatch/,
+    );
+    const cacheEntries = await fs.readdir(path.join(workspace, '1.3.5'));
+    assert.deepEqual(cacheEntries, []);
+  } finally {
+    await fs.rm(workspace, { recursive: true, force: true });
+  }
+});
+
+test('extractZipMember extracts only the requested path and makes the runtime executable', async () => {
+  const workspace = await fs.mkdtemp(path.join(os.tmpdir(), 'subminer-bun-extract-'));
+  const archivePath = path.join(workspace, 'fixture.zip');
+  const outputPath = path.join(workspace, 'output', 'bun');
+  const archiveBase64 =
+    'UEsDBAoAAAAAAMxcKl3rs337EgAAABIAAAAaABwAYnVuLWxpbnV4LXg2NC1iYXNlbGluZS9idW5VVAkAAyD5omog+aJqdXgLAAEE6AMAAAToAwAAYnVuIGZpeHR1cmUgYmluYXJ5UEsBAh4DCgAAAAAAzFwqXeuzffsSAAAAEgAAABoAGAAAAAAAAQAAAKSBAAAAAGJ1bi1saW51eC14NjQtYmFzZWxpbmUvYnVuVVQFAAMg+aJqdXgLAAEE6AMAAAToAwAAUEsFBgAAAAABAAEAYAAAAGYAAAAAAA==';
+
+  try {
+    await fs.writeFile(archivePath, Buffer.from(archiveBase64, 'base64'));
+    await extractZipMember(archivePath, 'bun-linux-x64-baseline/bun', outputPath);
+    assert.equal(await fs.readFile(outputPath, 'utf8'), 'bun fixture binary');
+    assert.equal((await fs.stat(outputPath)).mode & 0o777, 0o755);
+    await assert.rejects(
+      extractZipMember(archivePath, '../bun', path.join(workspace, 'unsafe')),
+      /unsafe Bun archive member/,
+    );
+  } finally {
+    await fs.rm(workspace, { recursive: true, force: true });
+  }
+});
+
+test('Windows extraction keeps paths and archive members out of PowerShell command text', () => {
+  const archivePath = String.raw`C:\Release Builds\bun $(archive) '1.3.5'.zip`;
+  const member = 'bun-windows-x64-baseline/bun.exe';
+  const outputPath = String.raw`C:\Staged App & Tools\resources\bun\bun.exe`;
+  const command = buildWindowsExtractionCommand(archivePath, member, outputPath);
+  const encodedCommand = command.args.at(-1);
+
+  assert.equal(command.command, 'powershell.exe');
+  assert.equal(command.args.at(-2), '-EncodedCommand');
+  assert.ok(encodedCommand);
+  const script = Buffer.from(encodedCommand, 'base64').toString('utf16le');
+  assert.match(script, /\$env:SUBMINER_BUN_ARCHIVE_PATH/);
+  assert.match(script, /\$env:SUBMINER_BUN_ARCHIVE_MEMBER/);
+  assert.match(script, /\$env:SUBMINER_BUN_OUTPUT_PATH/);
+  assert.doesNotMatch(script, /Release Builds|Staged App|bun-windows-x64-baseline/);
+  assert.deepEqual(command.environment, {
+    SUBMINER_BUN_ARCHIVE_PATH: archivePath,
+    SUBMINER_BUN_ARCHIVE_MEMBER: member,
+    SUBMINER_BUN_OUTPUT_PATH: outputPath,
+  });
+});
+
+test('stageBunLicenses copies the tracked inventory into resources/bun/licenses', async () => {
+  const workspace = await fs.mkdtemp(path.join(os.tmpdir(), 'subminer-bun-licenses-'));
+  const sourceDirectory = path.join(workspace, 'tracked-licenses');
+  const runtimeDirectory = path.join(workspace, 'resources', 'bun');
+
+  try {
+    await fs.mkdir(sourceDirectory, { recursive: true });
+    for (const fileName of [
+      'Bun-LICENSE.md',
+      'LGPL-2.0.txt',
+      'LGPL-2.1.txt',
+      'SOURCE.md',
+      'THIRD-PARTY-NOTICES.md',
+    ]) {
+      await fs.writeFile(path.join(sourceDirectory, fileName), `${fileName}\n`);
+    }
+    const licensesDirectory = await stageBunLicenses(runtimeDirectory, sourceDirectory);
+    assert.equal(licensesDirectory, path.join(runtimeDirectory, 'licenses'));
+    assert.equal(
+      await fs.readFile(path.join(licensesDirectory, 'THIRD-PARTY-NOTICES.md'), 'utf8'),
+      'THIRD-PARTY-NOTICES.md\n',
+    );
+  } finally {
+    await fs.rm(workspace, { recursive: true, force: true });
+  }
+});
+
+test('stageBunRuntime places target executables and metadata in app resources with safe modes', async () => {
+  const workspace = await fs.mkdtemp(path.join(os.tmpdir(), 'subminer-bun-stage-'));
+  const cases = [
+    {
+      platform: 'linux',
+      arch: 'x64',
+      appOutDir: path.join(workspace, 'linux'),
+      relativeExecutable: path.join('resources', 'bun', 'bun'),
+      member: 'bun-linux-x64-baseline/bun',
+    },
+    {
+      platform: 'darwin',
+      arch: 'arm64',
+      appOutDir: path.join(workspace, 'darwin'),
+      relativeExecutable: path.join('SubMiner.app', 'Contents', 'Resources', 'bun', 'bun'),
+      member: 'bun-darwin-aarch64/bun',
+    },
+    {
+      platform: 'win32',
+      arch: 'x64',
+      appOutDir: path.join(workspace, 'windows'),
+      relativeExecutable: path.join('resources', 'bun', 'bun.exe'),
+      member: 'bun-windows-x64-baseline/bun.exe',
+    },
+  ] as const;
+
+  try {
+    for (const targetCase of cases) {
+      let extractedMember = '';
+      const result = await stageBunRuntime(targetCase, {
+        configLoader: async () => runtimeConfig(),
+        archiveLoader: async () => path.join(workspace, 'fixture.zip'),
+        extractor: async (_archivePath: string, member: string, outputPath: string) => {
+          extractedMember = member;
+          await fs.mkdir(path.dirname(outputPath), { recursive: true });
+          await fs.writeFile(outputPath, 'bun fixture', { mode: 0o755 });
+        },
+        licenseStager: async (runtimeDirectory: string) => {
+          const licensesDirectory = path.join(runtimeDirectory, 'licenses');
+          await fs.mkdir(licensesDirectory, { recursive: true });
+          await fs.writeFile(path.join(licensesDirectory, 'Bun-LICENSE.md'), 'MIT fixture');
+          return licensesDirectory;
+        },
+      });
+      const expectedExecutable = path.join(targetCase.appOutDir, targetCase.relativeExecutable);
+      assert.equal(result.executablePath, expectedExecutable);
+      assert.equal(extractedMember, targetCase.member);
+      assert.equal((await fs.stat(expectedExecutable)).mode & 0o777, 0o755);
+      assert.equal((await fs.stat(result.metadataPath)).mode & 0o777, 0o644);
+      const metadata = JSON.parse(await fs.readFile(result.metadataPath, 'utf8'));
+      assert.equal(metadata.version, '1.3.5');
+      assert.equal(metadata.bunRevision, '1e86cebd74a5723e818b5c0555276b646bcf0e4c');
+      assert.equal(metadata.artifactSha256, result.artifact.sha256);
+      assert.equal(metadata.target, result.artifact.key);
+      assert.equal(
+        await fs.readFile(
+          path.join(path.dirname(expectedExecutable), 'licenses', 'Bun-LICENSE.md'),
+          'utf8',
+        ),
+        'MIT fixture',
+      );
+    }
+  } finally {
+    await fs.rm(workspace, { recursive: true, force: true });
+  }
+});
diff --git a/scripts/test-plugin-session-bindings.lua b/scripts/test-plugin-session-bindings.lua
index 482941f6..7a117d59 100644
--- a/scripts/test-plugin-session-bindings.lua
+++ b/scripts/test-plugin-session-bindings.lua
@@ -69,6 +69,12 @@ local ctx = {
 			return {
 				numericSelectionTimeoutMs = 3000,
 				bindings = {
+					{
+						key = { code = "KeyG-KeyS", modifiers = {} },
+						actionType = "session-action",
+						actionId = "openSubtitleSelection",
+						cliArgs = { "--session-action", '{"actionId":"openSubtitleSelection"}' },
+					},
 					{
 						key = {
 							code = "KeyO",
@@ -312,7 +318,8 @@ local ctx = {
 						cliArgs = { "--session-action", '{"actionId":"openFuturePanel"}' },
 					},
 				},
-			}, nil
+			},
+				nil
 		end,
 	},
 	state = {
@@ -430,17 +437,11 @@ assert_true(play_next_call ~= nil, "play-next binding should invoke CLI action")
 assert_true(play_next_call[2] == "--play-next-subtitle", "play-next binding should pass CLI flag")
 
 local character_dictionary_manager = find_binding("Ctrl+d")
-assert_true(
-	character_dictionary_manager ~= nil,
-	"character dictionary manager binding should be registered"
-)
+assert_true(character_dictionary_manager ~= nil, "character dictionary manager binding should be registered")
 
 character_dictionary_manager.fn()
 local character_dictionary_manager_call = recorded.async_calls[#recorded.async_calls]
-assert_true(
-	character_dictionary_manager_call ~= nil,
-	"character dictionary manager binding should invoke CLI action"
-)
+assert_true(character_dictionary_manager_call ~= nil, "character dictionary manager binding should invoke CLI action")
 assert_true(
 	character_dictionary_manager_call[2] == "--session-action",
 	"character dictionary manager binding should use generic session action CLI flag"
@@ -474,3 +475,35 @@ assert_true(call[2] == "--mine-sentence-multiple", "CLI action should enter mine
 assert_true(call[3] == nil, "CLI action should not bind a plugin-side digit count")
 
 print("plugin session binding regression tests: OK")
+
+local selector = find_binding("g-s")
+assert_true(selector ~= nil, "subtitle selection should override mpv g-s with a forced sequence")
+selector.fn()
+local selection_call = recorded.async_calls[#recorded.async_calls]
+assert_true(
+	selection_call[3] == '{"actionId":"openSubtitleSelection"}',
+	"subtitle selection should dispatch its session action"
+)
+
+local native_bindings = {}
+function mp.get_property_native(name)
+	assert_true(name == "input-bindings", "only native input bindings should be queried")
+	return native_bindings
+end
+
+for _, case in ipairs({
+	{ key = "g", priority = 1, enabled = false },
+	{ key = "G", priority = 1, enabled = true },
+	{ key = "Shift+g", priority = 1, enabled = true },
+	{ key = "Ctrl+g", priority = 1, enabled = true },
+	{ key = "g", priority = -1, enabled = true },
+	{ key = "g", priority = 1, cmd = "ignore", enabled = true },
+	{ key = "g", priority = 1, cmd = "no-osd ignore", enabled = true },
+}) do
+	native_bindings = { { key = case.key, cmd = case.cmd or "show-text single", priority = case.priority } }
+	recorded.bindings = {}
+	assert_true(bindings.reload_bindings(), "binding reload should succeed")
+	assert_true((find_binding("g-s") ~= nil) == case.enabled, "sequence prefix conflict: " .. case.key)
+end
+assert_true(#recorded.osd > 0, "native prefix conflicts should be visible")
+print("plugin sequence conflict tests: OK")
diff --git a/scripts/update-aur-package.test.ts b/scripts/update-aur-package.test.ts
index d8320d64..c1b8187a 100644
--- a/scripts/update-aur-package.test.ts
+++ b/scripts/update-aur-package.test.ts
@@ -70,6 +70,7 @@ test('update-aur-package updates PKGBUILD and .SRCINFO without makepkg', () => {
     );
 
     assert.match(pkgbuild, /^pkgver=0\.6\.3$/m);
+    assert.doesNotMatch(pkgbuild, /^\s*'bun'$/m);
     assert.match(
       pkgbuild,
       /^\s*"subminer-\$\{pkgver\}::https:\/\/github\.com\/ksyasuda\/SubMiner\/releases\/download\/v\$\{pkgver\}\/subminer"$/m,
@@ -82,7 +83,9 @@ test('update-aur-package updates PKGBUILD and .SRCINFO without makepkg', () => {
       pkgbuild,
       /^\s*install -Dm755 "\$\{srcdir\}\/subminer-\$\{pkgver\}" "\$\{pkgdir\}\/usr\/bin\/subminer"$/m,
     );
+    assert.match(pkgbuild, /assets\/thumbnailers\/subminer-ffmpegthumbnailer\.thumbnailer/);
     assert.match(srcinfo, /^\tpkgver = 0\.6\.3$/m);
+    assert.doesNotMatch(srcinfo, /^\tdepends = bun$/m);
     assert.match(srcinfo, /^\tprovides = subminer=0\.6\.3$/m);
     assert.match(
       srcinfo,
diff --git a/scripts/verify-generated-launcher.sh b/scripts/verify-generated-launcher.sh
index aab1494d..4ce7c1be 100755
--- a/scripts/verify-generated-launcher.sh
+++ b/scripts/verify-generated-launcher.sh
@@ -2,23 +2,38 @@
 set -euo pipefail
 
 REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
-LAUNCHER_OUT="$REPO_ROOT/dist/launcher/subminer"
+LAUNCHER_DIR="$REPO_ROOT/dist/launcher"
+LAUNCHER_OUT="$LAUNCHER_DIR/subminer"
+EXPECTED_ARTIFACTS=(prepare.cjs subminer subminer.cmd subminer.js version)
 
 if [[ ! -f "$REPO_ROOT/launcher/main.ts" ]]; then
 	echo "[FAIL] launcher source missing: launcher/main.ts"
 	exit 1
 fi
 
-if ! grep -Fn -- "--outfile=\"\$(LAUNCHER_OUT)\"" "$REPO_ROOT/Makefile" >/dev/null; then
-	echo "[FAIL] Makefile build-launcher target is not writing to dist/launcher/subminer"
+if ! grep -F -- "bun run build:launcher" "$REPO_ROOT/Makefile" >/dev/null; then
+	echo "[FAIL] Makefile build-launcher target does not call the canonical package script"
 	exit 1
 fi
 
-if [[ ! -f "$LAUNCHER_OUT" ]]; then
-	echo "[FAIL] generated launcher not found at dist/launcher/subminer"
-	echo "       run: make build-launcher"
-	exit 1
-fi
+for artifact in "${EXPECTED_ARTIFACTS[@]}"; do
+	if [[ ! -f "$LAUNCHER_DIR/$artifact" ]]; then
+		echo "[FAIL] generated launcher artifact missing: dist/launcher/$artifact"
+		echo "       run: make build-launcher"
+		exit 1
+	fi
+done
+
+for artifact_path in "$LAUNCHER_DIR"/*; do
+	artifact="${artifact_path##*/}"
+	case "$artifact" in
+		prepare.cjs | subminer | subminer.cmd | subminer.js | version) ;;
+		*)
+			echo "[FAIL] dist/launcher contains an unexpected runtime artifact: $artifact"
+			exit 1
+			;;
+	esac
+done
 
 if [[ ! -x "$LAUNCHER_OUT" ]]; then
 	echo "[FAIL] generated launcher is not executable: dist/launcher/subminer"
@@ -32,11 +47,11 @@ if [[ -f "$REPO_ROOT/subminer" ]]; then
 	exit 1
 fi
 
-if git -C "$REPO_ROOT" ls-files --error-unmatch dist/launcher/subminer >/dev/null 2>&1; then
-	echo "[FAIL] dist/launcher/subminer is tracked by git; generated artifacts must remain untracked"
+if git -C "$REPO_ROOT" ls-files --error-unmatch dist/launcher >/dev/null 2>&1; then
+	echo "[FAIL] dist/launcher contains tracked files; generated artifacts must remain untracked"
 	exit 1
 fi
 
 echo "[OK] launcher workflow verified"
 echo "     source: launcher/*.ts"
-echo "     generated artifact: dist/launcher/subminer"
+echo "     generated artifacts: ${EXPECTED_ARTIFACTS[*]}"
diff --git a/src/anki-integration.test.ts b/src/anki-integration.test.ts
index b4bf358d..4370446d 100644
--- a/src/anki-integration.test.ts
+++ b/src/anki-integration.test.ts
@@ -11,10 +11,12 @@ import type { MediaInput } from './media-input';
 import { AnkiConnectConfig } from './types';
 
 type TestOverlayNotificationPayload = {
+  id?: string;
   title: string;
   body?: string;
   image?: string;
   variant?: string;
+  persistent?: boolean;
   actions?: Array<{ id: string; label: string; noteId?: number }>;
 };
 
@@ -153,6 +155,7 @@ function createFieldGroupingMergeCollaborator(options?: {
     getEffectiveSentenceCardConfig: () => ({
       sentenceField: 'Sentence',
       audioField: 'SentenceAudio',
+      fieldGroupingProvider: 'kiku' as const,
     }),
     getCurrentSubtitleText: () => options?.currentSubtitleText,
     resolveFieldName,
@@ -606,6 +609,7 @@ test('AnkiIntegration applies ready YouTube cache media to every queued note id'
   const integration = new AnkiIntegration(
     {
       fields: {
+        audio: 'ExpressionAudio',
         image: 'Picture',
       },
       media: {
@@ -659,7 +663,7 @@ test('AnkiIntegration applies ready YouTube cache media to every queued note id'
       noteIds.map((noteId) => ({
         noteId,
         fields: {
-          SentenceAudio: { value: '' },
+          ExpressionAudio: { value: '' },
           Picture: { value: '' },
         },
       })),
@@ -944,7 +948,7 @@ test('AnkiIntegration queues YouTube media updates against recovered source URLs
     noteInfo: {
       noteId: 404,
       fields: {
-        SentenceAudio: { value: '' },
+        ExpressionAudio: { value: '' },
         Picture: { value: '' },
       },
     },
@@ -956,7 +960,8 @@ test('AnkiIntegration queues YouTube media updates against recovered source URLs
   assert.equal(queued, true);
   assert.equal(updatedNotes.length, 1);
   assert.equal(updatedNotes[0]?.noteId, 404);
-  assert.match(updatedNotes[0]?.fields.SentenceAudio ?? '', /^\[sound:audio_/);
+  assert.match(updatedNotes[0]?.fields.ExpressionAudio ?? '', /^\[sound:audio_/);
+  assert.equal(updatedNotes[0]?.fields.SentenceAudio, undefined);
   assert.match(updatedNotes[0]?.fields.Picture ?? '', /^<img src="image_/);
   assert.equal(storedMedia.length, 2);
   assert.deepEqual(audioVolumeScales, [0.3 ** 3]);
@@ -1182,6 +1187,117 @@ test('AnkiIntegration embeds generated notification image on overlay mined-card
   assert.deepEqual(cleanupPaths, [notificationIconPath]);
 });
 
+test('AnkiIntegration keeps overlay card-update progress visible until the terminal notification', async () => {
+  const overlayNotifications: TestOverlayNotificationPayload[] = [];
+  const integration = new AnkiIntegration(
+    {
+      behavior: {
+        notificationType: 'overlay',
+      },
+    },
+    {} as never,
+    {} as never,
+    undefined,
+    undefined,
+    undefined,
+    undefined,
+    {},
+    undefined,
+    (payload) => {
+      overlayNotifications.push(payload);
+    },
+  );
+  const updateNotifications = integration as unknown as {
+    beginUpdateProgress: (message: string) => void;
+    showNotification: (noteId: number, label: string | number) => Promise<void>;
+  };
+
+  updateNotifications.beginUpdateProgress('Updating card');
+  await updateNotifications.showNotification(42, '食べる');
+
+  assert.deepEqual(
+    overlayNotifications.map(({ id, variant, persistent }) => ({ id, variant, persistent })),
+    [
+      { id: 'anki-update-progress', variant: 'progress', persistent: true },
+      { id: 'anki-update-progress', variant: 'success', persistent: false },
+    ],
+  );
+});
+
+test('AnkiIntegration dismisses persistent overlay update progress when no terminal notification replaces it', () => {
+  const overlayNotifications: TestOverlayNotificationPayload[] = [];
+  const dismissedIds: string[] = [];
+  const integration = new AnkiIntegration(
+    {
+      behavior: {
+        notificationType: 'overlay',
+      },
+    },
+    {} as never,
+    {} as never,
+    undefined,
+    undefined,
+    undefined,
+    undefined,
+    {},
+    undefined,
+    (payload) => {
+      overlayNotifications.push(payload);
+    },
+    undefined,
+    undefined,
+    undefined,
+    (id) => {
+      dismissedIds.push(id);
+    },
+  );
+  const updateNotifications = integration as unknown as {
+    beginUpdateProgress: (message: string) => void;
+    endUpdateProgress: () => void;
+  };
+
+  updateNotifications.beginUpdateProgress('Updating card');
+  updateNotifications.endUpdateProgress();
+
+  assert.equal(overlayNotifications[0]?.persistent, true);
+  assert.deepEqual(dismissedIds, ['anki-update-progress']);
+});
+
+test('AnkiIntegration dismisses overlay update progress after notifications switch to OSD', () => {
+  const behavior: NonNullable<AnkiConnectConfig['behavior']> = {
+    notificationType: 'overlay',
+  };
+  const dismissedIds: string[] = [];
+  const integration = new AnkiIntegration(
+    { behavior },
+    {} as never,
+    {} as never,
+    undefined,
+    undefined,
+    undefined,
+    undefined,
+    {},
+    undefined,
+    () => {},
+    undefined,
+    undefined,
+    undefined,
+    (id) => {
+      dismissedIds.push(id);
+    },
+  );
+  const updateNotifications = integration as unknown as {
+    beginUpdateProgress: (message: string) => void;
+    endUpdateProgress: () => void;
+  };
+
+  updateNotifications.beginUpdateProgress('Updating card');
+  behavior.notificationType = 'osd';
+  updateNotifications.endUpdateProgress();
+
+  assert.deepEqual(dismissedIds, ['anki-update-progress']);
+});
+
 test('AnkiIntegration keeps overlay notification image when temp icon write fails', async () => {
   const desktopNotifications: Array<{ title: string; body?: string; icon?: string }> = [];
   const overlayNotifications: TestOverlayNotificationPayload[] = [];
@@ -1411,3 +1527,43 @@ test('AnkiIntegration.formatMiscInfoPattern avoids leaking Jellyfin api_key quer
   assert.equal(result, '[SubMiner] [Jellyfin/direct] Bocchi the Rock! - S01E02 (00:07:06)');
   assert.equal(result.includes('api_key='), false);
 });
+
+test('Anki metadata rejects a credential-bearing media title before metadata arrives', () => {
+  const integration = new AnkiIntegration(
+    { metadata: { pattern: '[SubMiner] %f | %F (%t)' } } as never,
+    {} as never,
+    {
+      currentVideoPath: 'https://jellyfin.example/Videos/item/stream?api_key=test-secret',
+      currentMediaTitle: 'stream?static=true&api_key=test-secret',
+      currentTimePos: 426,
+      send: () => true,
+    } as never,
+  );
+  const privateApi = integration as unknown as {
+    formatMiscInfoPattern: (fallbackFilename: string, startTimeSeconds?: number) => string;
+  };
+  const result = privateApi.formatMiscInfoPattern('stream?api_key=test-secret', 426);
+  assert.equal(result, '[SubMiner] Unknown media | Unknown media (00:07:06)');
+});
+
+test('AnkiIntegration.formatMiscInfoPattern treats ApiKey stream paths like legacy api_key ones', () => {
+  const integration = new AnkiIntegration(
+    { metadata: { pattern: '[SubMiner] %f (%t)' } } as never,
+    {} as never,
+    {
+      currentSubText: '',
+      currentVideoPath: 'stream?static=true&ApiKey=secret-token&MediaSourceId=ms-1',
+      currentTimePos: 426,
+      currentSubStart: 426,
+      currentSubEnd: 428,
+      currentMediaTitle: '[Jellyfin/direct] Bocchi the Rock! - S01E02',
+      send: () => true,
+    } as unknown as never,
+  );
+  const privateApi = integration as unknown as {
+    formatMiscInfoPattern: (fallbackFilename: string, startTimeSeconds?: number) => string;
+  };
+  const result = privateApi.formatMiscInfoPattern('audio_123.mp3', 426);
+  assert.equal(result, '[SubMiner] [Jellyfin/direct] Bocchi the Rock! - S01E02 (00:07:06)');
+  assert.equal(result.includes('ApiKey='), false);
+});
diff --git a/src/anki-integration.ts b/src/anki-integration.ts
index fcc118e1..495539b2 100644
--- a/src/anki-integration.ts
+++ b/src/anki-integration.ts
@@ -28,8 +28,11 @@ import {
   KikuMergePreviewResponse,
   NotificationOptions,
   type WordCardKind,
+  type MediaTimingReviewDecision,
+  type MediaTimingReviewRequest,
 } from './types/anki';
 import { AiConfig } from './types/integrations';
+import { sanitizeMediaTitle } from './shared/media-identity';
 import type { KnownWordMaturityTier } from './types/subtitle';
 import { MpvClient } from './types/runtime';
 import { OPEN_ANKI_CARD_ACTION_ID } from './types/notification';
@@ -182,7 +185,7 @@ function extractFilenameFromMediaPath(rawPath: string): string {
 function shouldPreferMediaTitleForMiscInfo(rawPath: string, filename: string): boolean {
   const loweredPath = rawPath.toLowerCase();
   const loweredFilename = filename.toLowerCase();
-  if (loweredPath.includes('api_key=')) {
+  if (loweredPath.includes('api_key=') || loweredPath.includes('apikey=')) {
     return true;
   }
   if (loweredPath.startsWith('http://') || loweredPath.startsWith('https://')) {
@@ -218,6 +221,8 @@ export class AnkiIntegration {
     null;
   private overlayNotificationCallback: ((payload: OverlayNotificationPayload) => void) | null =
     null;
+  private overlayNotificationDismissCallback: ((id: string) => void) | null = null;
+  private overlayUpdateProgressActive = false;
   private updateInProgress = false;
   private uiFeedbackState: UiFeedbackState = createUiFeedbackState();
   private parseWarningKeys = new Set<string>();
@@ -238,6 +243,12 @@ export class AnkiIntegration {
   private recordCardsMinedCallback: ((count: number, noteIds?: number[]) => void) | null = null;
   private knownWordCacheUpdatedCallback: (() => void) | null = null;
   private consumeSubtitleMiningContextCallback: (() => SubtitleMiningContext | null) | null = null;
+  private generateSentenceFuriganaCallback:
+    | ((text: string, highlightedText?: string) => Promise<string | null>)
+    | null = null;
+  private mediaTimingReviewCallback:
+    | ((request: MediaTimingReviewRequest) => Promise<MediaTimingReviewDecision>)
+    | null = null;
   private noteIdRedirects = new Map<number, number>();
   private trackedDuplicateNoteIds = new Map<number, number[]>();
   private getCachedMediaPath: MediaGenerationInputResolverOptions['getCachedMediaPath'] | null =
@@ -265,6 +276,7 @@ export class AnkiIntegration {
     getCachedMediaPath?: MediaGenerationInputResolverOptions['getCachedMediaPath'],
     shouldRequireRemoteMediaCache?: () => boolean,
     getYoutubeMediaSourceUrl?: () => Promise<string | null | undefined> | string | null | undefined,
+    overlayNotificationDismissCallback?: (id: string) => void,
   ) {
     this.config = normalizeAnkiIntegrationConfig(config);
     this.aiConfig = { ...aiConfig };
@@ -280,6 +292,7 @@ export class AnkiIntegration {
     this.getCachedMediaPath = getCachedMediaPath ?? null;
     this.shouldRequireRemoteMediaCache = shouldRequireRemoteMediaCache ?? null;
     this.getYoutubeMediaSourceUrl = getYoutubeMediaSourceUrl ?? null;
+    this.overlayNotificationDismissCallback = overlayNotificationDismissCallback ?? null;
     this.pendingYoutubeMediaQueue = this.createPendingYoutubeMediaQueue();
     this.knownWordCache = this.createKnownWordCache(knownWordCacheStatePath);
     this.pollingRunner = this.createPollingRunner();
@@ -379,8 +392,6 @@ export class AnkiIntegration {
       getCachedMediaPath: this.getCachedMediaPath,
       shouldRequireRemoteMediaCache: () => this.shouldRequireRemoteMediaCache?.() === true,
       getSubtitleMediaRange: (context) => this.getSubtitleMediaRange(context),
-      getResolvedSentenceAudioFieldName: (noteInfo) =>
-        this.getResolvedSentenceAudioFieldName(noteInfo),
       resolveConfiguredFieldName: (noteInfo, ...preferredNames) =>
         this.resolveConfiguredFieldName(noteInfo, ...preferredNames),
       mergeFieldValue: (existing, newValue, overwrite) =>
@@ -509,6 +520,7 @@ export class AnkiIntegration {
         findNotes: async (query, options) =>
           (await this.client.findNotes(query, options)) as number[],
         retrieveMediaFile: (filename) => this.client.retrieveMediaFile(filename),
+        deleteNotes: (noteIds) => this.client.deleteNotes(noteIds),
       },
       mediaGenerator: {
         generateAudio: (
@@ -566,6 +578,7 @@ export class AnkiIntegration {
       getEffectiveSentenceCardConfig: () => this.getEffectiveSentenceCardConfig(),
       getFallbackDurationSeconds: () => this.getFallbackDurationSeconds(),
       appendKnownWordsFromNoteInfo: (noteInfo) => this.appendKnownWordsFromNoteInfo(noteInfo),
+      removeKnownWordNote: (noteId) => this.removeKnownWordNote(noteId),
       isUpdateInProgress: () => this.updateInProgress,
       setUpdateInProgress: (value) => {
         this.updateInProgress = value;
@@ -581,6 +594,7 @@ export class AnkiIntegration {
       recordCardsMinedCallback: (count, noteIds) => {
         this.recordCardsMinedSafely(count, noteIds, 'card creation');
       },
+      reviewMediaTiming: (request) => this.reviewMediaTiming(request),
     });
   }
 
@@ -637,12 +651,14 @@ export class AnkiIntegration {
         notesInfo: async (noteIds) => (await this.client.notesInfo(noteIds)) as unknown,
         updateNoteFields: (noteId, fields) => this.client.updateNoteFields(noteId, fields),
         storeMediaFile: (filename, data) => this.client.storeMediaFile(filename, data),
+        deleteNotes: (noteIds) => this.client.deleteNotes(noteIds),
       },
       getConfig: () => this.config,
       getCurrentSubtitleText: () => this.mpvClient.currentSubText,
       getCurrentSubtitleStart: () => this.mpvClient.currentSubStart,
       getEffectiveSentenceCardConfig: () => this.getEffectiveSentenceCardConfig(),
       appendKnownWordsFromNoteInfo: (noteInfo) => this.appendKnownWordsFromNoteInfo(noteInfo),
+      removeKnownWordNote: (noteId) => this.removeKnownWordNote(noteId),
       extractFields: (fields) => this.extractFields(fields),
       findDuplicateNote: (expression, excludeNoteId, noteInfo) =>
         this.findDuplicateNote(expression, excludeNoteId, noteInfo),
@@ -653,12 +669,17 @@ export class AnkiIntegration {
       processSentence: (mpvSentence, noteFields) => this.processSentence(mpvSentence, noteFields),
       processSentenceFurigana: (sentenceFurigana, noteFields) =>
         this.processSentenceFurigana(sentenceFurigana, noteFields),
+      generateSentenceFurigana: async (text, noteFields) =>
+        this.generateSentenceFuriganaCallback?.(
+          text,
+          this.config.behavior?.highlightWord === false
+            ? undefined
+            : this.getSentenceHighlightText(noteFields),
+        ) ?? null,
       setCardTypeFields: (updatedFields, availableFieldNames, cardKind) =>
         this.setCardTypeFields(updatedFields, availableFieldNames, cardKind),
       resolveConfiguredFieldName: (noteInfo, ...preferredNames) =>
         this.resolveConfiguredFieldName(noteInfo, ...preferredNames),
-      getResolvedSentenceAudioFieldName: (noteInfo) =>
-        this.getResolvedSentenceAudioFieldName(noteInfo),
       getAnimatedImageLeadInSeconds: (noteInfo) => this.getAnimatedImageLeadInSeconds(noteInfo),
       mergeFieldValue: (existing, newValue, overwrite) =>
         this.mergeFieldValue(existing, newValue, overwrite),
@@ -680,6 +701,7 @@ export class AnkiIntegration {
       logWarn: (...args) => log.warn(args[0] as string, ...args.slice(1)),
       logInfo: (...args) => log.info(args[0] as string, ...args.slice(1)),
       logError: (...args) => log.error(args[0] as string, ...args.slice(1)),
+      reviewMediaTiming: (request) => this.reviewMediaTiming(request),
     });
   }
 
@@ -799,6 +821,12 @@ export class AnkiIntegration {
     }
   }
 
+  private removeKnownWordNote(noteId: number): void {
+    if (this.knownWordCache.removeNote(noteId)) {
+      this.notifyKnownWordCacheUpdated();
+    }
+  }
+
   private notifyKnownWordCacheUpdated(): void {
     if (!this.knownWordCacheUpdatedCallback) {
       return;
@@ -835,6 +863,19 @@ export class AnkiIntegration {
     };
   }
 
+  private getSenrenConfig(): {
+    enabled: boolean;
+    fieldGrouping?: 'auto' | 'manual' | 'disabled';
+    deleteDuplicateInAuto?: boolean;
+  } {
+    const senren = this.config.isSenren;
+    return {
+      enabled: senren?.enabled === true,
+      fieldGrouping: senren?.fieldGrouping,
+      deleteDuplicateInAuto: senren?.deleteDuplicateInAuto,
+    };
+  }
+
   private getEffectiveSentenceCardConfig(): {
     model?: string;
     sentenceField: string;
@@ -843,10 +884,27 @@ export class AnkiIntegration {
     kikuEnabled: boolean;
     kikuFieldGrouping: 'auto' | 'manual' | 'disabled';
     kikuDeleteDuplicateInAuto: boolean;
+    senrenEnabled: boolean;
+    fieldGroupingProvider: 'kiku' | 'senren' | null;
+    fieldGroupingMode: 'auto' | 'manual' | 'disabled';
+    fieldGroupingDeleteDuplicateInAuto: boolean;
     wordCardKind: WordCardKind;
   } {
     const lapis = this.getLapisConfig();
     const kiku = this.getKikuConfig();
+    const senren = this.getSenrenConfig();
+
+    const kikuFieldGrouping = (kiku.fieldGrouping || 'disabled') as 'auto' | 'manual' | 'disabled';
+    const senrenFieldGrouping = (senren.fieldGrouping || 'auto') as 'auto' | 'manual' | 'disabled';
+    // Kiku and Senren are mutually exclusive; config resolution enforces it, and
+    // Kiku wins here too in case a runtime patch re-enables both.
+    const fieldGroupingProvider = kiku.enabled ? 'kiku' : senren.enabled ? 'senren' : null;
+    const fieldGroupingMode =
+      fieldGroupingProvider === 'kiku'
+        ? kikuFieldGrouping
+        : fieldGroupingProvider === 'senren'
+          ? senrenFieldGrouping
+          : 'disabled';
 
     return {
       model: lapis.sentenceCardModel,
@@ -854,8 +912,15 @@ export class AnkiIntegration {
       audioField: 'SentenceAudio',
       lapisEnabled: lapis.enabled,
       kikuEnabled: kiku.enabled,
-      kikuFieldGrouping: (kiku.fieldGrouping || 'disabled') as 'auto' | 'manual' | 'disabled',
+      kikuFieldGrouping,
       kikuDeleteDuplicateInAuto: kiku.deleteDuplicateInAuto !== false,
+      senrenEnabled: senren.enabled,
+      fieldGroupingProvider,
+      fieldGroupingMode,
+      fieldGroupingDeleteDuplicateInAuto:
+        fieldGroupingProvider === 'senren'
+          ? senren.deleteDuplicateInAuto !== false
+          : kiku.deleteDuplicateInAuto !== false,
       wordCardKind: resolveWordCardKindSetting(this.config.lapisKiku?.wordCardKind),
     };
   }
@@ -874,7 +939,7 @@ export class AnkiIntegration {
 
   private async processNewCard(
     noteId: number,
-    options?: { skipKikuFieldGrouping?: boolean },
+    options?: { skipFieldGrouping?: boolean },
   ): Promise<void> {
     await this.noteUpdateWorkflow.execute(noteId, options);
   }
@@ -1039,7 +1104,7 @@ export class AnkiIntegration {
       videoPath,
       startTime,
       endTime,
-      this.config.media?.audioPadding,
+      context?.mediaPaddingSeconds ?? this.config.media?.audioPadding,
       resolveAudioStreamIndexForMediaGeneration(videoPath, this.mpvClient.currentAudioStreamIndex),
       this.config.media?.normalizeAudio !== false,
       await this.getMpvVolumeScale(),
@@ -1063,16 +1128,18 @@ export class AnkiIntegration {
       return null;
     }
     const mediaRange = this.getSubtitleMediaRange(context);
-    const timestamp = context
-      ? mediaRange.startTime + (mediaRange.endTime - mediaRange.startTime) / 2
-      : this.mpvClient.currentTimePos || 0;
+    const timestamp =
+      context?.screenshotTime ??
+      (context
+        ? mediaRange.startTime + (mediaRange.endTime - mediaRange.startTime) / 2
+        : this.mpvClient.currentTimePos || 0);
 
     if (this.config.media?.imageType === 'avif') {
       return this.mediaGenerator.generateAnimatedImage(
         videoPath,
         mediaRange.startTime,
         mediaRange.endTime,
-        this.config.media?.audioPadding,
+        context?.mediaPaddingSeconds ?? this.config.media?.audioPadding,
         {
           fps: this.config.media?.animatedFps,
           maxWidth: this.config.media?.animatedMaxWidth,
@@ -1111,11 +1178,13 @@ export class AnkiIntegration {
     }
 
     const videoFilename = extractFilenameFromMediaPath(mediaPath);
-    const resolvedMediaTitle = trimToNonEmptyString(mediaTitle);
+    const resolvedMediaTitle = sanitizeMediaTitle(mediaTitle);
     const filenameWithExt =
       (shouldPreferMediaTitleForMiscInfo(mediaPath, videoFilename)
-        ? resolvedMediaTitle || videoFilename
-        : videoFilename || resolvedMediaTitle) || fallbackFilename;
+        ? resolvedMediaTitle || 'Unknown media'
+        : sanitizeMediaTitle(videoFilename) || resolvedMediaTitle) ||
+      sanitizeMediaTitle(fallbackFilename) ||
+      'Unknown media';
     const filenameWithoutExt = filenameWithExt.replace(/\.[^.]+$/, '');
 
     const currentTimePos =
@@ -1203,12 +1272,13 @@ export class AnkiIntegration {
   private beginUpdateProgress(initialMessage: string): void {
     if (!this.shouldUseOsdNotifications()) {
       if (this.shouldUseOverlayNotifications()) {
+        this.overlayUpdateProgressActive = true;
         this.overlayNotificationCallback?.({
           id: 'anki-update-progress',
           title: 'Anki update',
           body: initialMessage,
           variant: 'progress',
-          persistent: false,
+          persistent: true,
         });
       }
       return;
@@ -1219,6 +1289,10 @@ export class AnkiIntegration {
   }
 
   private endUpdateProgress(): void {
+    if (this.overlayUpdateProgressActive) {
+      this.overlayUpdateProgressActive = false;
+      this.overlayNotificationDismissCallback?.('anki-update-progress');
+    }
     if (!this.shouldUseOsdNotifications()) {
       return;
     }
@@ -1243,18 +1317,20 @@ export class AnkiIntegration {
     if (!this.shouldUseOsdNotifications()) {
       this.updateInProgress = true;
       if (this.shouldUseOverlayNotifications()) {
+        this.overlayUpdateProgressActive = true;
         this.overlayNotificationCallback?.({
           id: 'anki-update-progress',
           title: 'Anki update',
           body: initialMessage,
           variant: 'progress',
-          persistent: false,
+          persistent: true,
         });
       }
       try {
         return await action();
       } finally {
         this.updateInProgress = false;
+        this.endUpdateProgress();
       }
     }
     return withUpdateProgress(
@@ -1353,6 +1429,7 @@ export class AnkiIntegration {
         : undefined;
 
     if (shouldShowOverlayNotification && this.overlayNotificationCallback) {
+      this.overlayUpdateProgressActive = false;
       this.overlayNotificationCallback({
         id: 'anki-update-progress',
         title: 'Anki Card Updated',
@@ -1496,7 +1573,7 @@ export class AnkiIntegration {
     trackedDuplicateNoteIdsBeforeCreate: Set<number>,
   ): boolean {
     const sentenceCardConfig = this.getEffectiveSentenceCardConfig();
-    if (!sentenceCardConfig.kikuEnabled || sentenceCardConfig.kikuFieldGrouping === 'disabled') {
+    if (sentenceCardConfig.fieldGroupingMode === 'disabled') {
       return false;
     }
 
@@ -1555,13 +1632,6 @@ export class AnkiIntegration {
     return sentenceCardConfig.audioField || 'SentenceAudio';
   }
 
-  private getResolvedSentenceAudioFieldName(noteInfo: NoteInfo): string | null {
-    return (
-      this.resolveNoteFieldName(noteInfo, this.getPreferredSentenceAudioFieldName()) ||
-      this.resolveConfiguredFieldName(noteInfo, this.config.fields?.audio)
-    );
-  }
-
   private getConfiguredWordFieldName(): string {
     return getConfiguredWordFieldName(this.config);
   }
@@ -1723,6 +1793,31 @@ export class AnkiIntegration {
     this.consumeSubtitleMiningContextCallback = callback;
   }
 
+  setSentenceFuriganaGenerator(callback: typeof this.generateSentenceFuriganaCallback): void {
+    this.generateSentenceFuriganaCallback = callback;
+  }
+
+  setMediaTimingReviewCallback(
+    callback: ((request: MediaTimingReviewRequest) => Promise<MediaTimingReviewDecision>) | null,
+  ): void {
+    this.mediaTimingReviewCallback = callback;
+  }
+
+  private async reviewMediaTiming(
+    request: Omit<MediaTimingReviewRequest, 'audioPadding' | 'maxMediaDuration'>,
+  ): Promise<MediaTimingReviewDecision> {
+    if (this.config.media?.reviewTiming !== true || !this.mediaTimingReviewCallback) {
+      return { action: 'use-original' };
+    }
+    return await this.mediaTimingReviewCallback({
+      ...request,
+      audioPadding: Math.max(0, this.config.media.audioPadding ?? 0),
+      maxMediaDuration: Math.max(0, this.config.media.maxMediaDuration ?? 30),
+      screenshotEnabled:
+        this.config.media.generateImage !== false && this.config.media.imageType !== 'avif',
+    });
+  }
+
   resolveCurrentNoteId(noteId: number): number {
     let resolved = noteId;
     const seen = new Set<number>();
diff --git a/src/anki-integration/animated-image-sync.test.ts b/src/anki-integration/animated-image-sync.test.ts
index 6f18cba5..2bfe309a 100644
--- a/src/anki-integration/animated-image-sync.test.ts
+++ b/src/anki-integration/animated-image-sync.test.ts
@@ -14,7 +14,8 @@ test('resolveAnimatedImageLeadInSeconds sums configured word audio durations for
   const leadInSeconds = await resolveAnimatedImageLeadInSeconds({
     config: {
       fields: {
-        audio: 'ExpressionAudio',
+        audio: 'SentenceAudio',
+        wordAudio: 'Pronunciation',
       },
       media: {
         imageType: 'avif',
@@ -25,7 +26,8 @@ test('resolveAnimatedImageLeadInSeconds sums configured word audio durations for
     noteInfo: {
       noteId: 42,
       fields: {
-        ExpressionAudio: {
+        SentenceAudio: { value: '[sound:sentence.mp3]' },
+        Pronunciation: {
           value: '[sound:word.mp3][sound:alt.ogg]',
         },
       },
@@ -121,3 +123,32 @@ test('resolveAnimatedImageLeadInSeconds falls back to zero when sync is disabled
 
   assert.equal(leadInSeconds, 0);
 });
+
+for (const sentenceAudio of ['', '[sound:sentence.mp3]']) {
+  test(`word audio defaults independently of sentence audio (${sentenceAudio ? 'existing' : 'new'} note)`, async () => {
+    const retrieved: string[] = [];
+    const leadInSeconds = await resolveAnimatedImageLeadInSeconds({
+      config: {
+        fields: { audio: 'SentenceAudio' },
+        media: { imageType: 'avif' },
+      },
+      noteInfo: {
+        noteId: 42,
+        fields: {
+          ExpressionAudio: { value: '[sound:word.mp3]' },
+          SentenceAudio: { value: sentenceAudio },
+        },
+      },
+      resolveConfiguredFieldName: (noteInfo, ...preferredNames) =>
+        preferredNames.find((name) => name !== undefined && name in noteInfo.fields) ?? null,
+      retrieveMediaFileBase64: async (filename) => {
+        retrieved.push(filename);
+        return 'd29yZA==';
+      },
+      probeAudioDurationSeconds: async (_buffer, filename) => (filename === 'word.mp3' ? 0.6 : 4),
+    });
+
+    assert.equal(leadInSeconds, 0.6);
+    assert.deepEqual(retrieved, ['word.mp3']);
+  });
+}
diff --git a/src/anki-integration/animated-image-sync.ts b/src/anki-integration/animated-image-sync.ts
index 25282873..96d81809 100644
--- a/src/anki-integration/animated-image-sync.ts
+++ b/src/anki-integration/animated-image-sync.ts
@@ -97,8 +97,8 @@ export async function resolveAnimatedImageLeadInSeconds<TNoteInfo extends NoteIn
 
   const wordAudioFieldName = resolveConfiguredFieldName(
     noteInfo,
-    config.fields?.audio,
-    DEFAULT_ANKI_CONNECT_CONFIG.fields.audio,
+    config.fields?.wordAudio,
+    DEFAULT_ANKI_CONNECT_CONFIG.fields.wordAudio,
   );
   if (!wordAudioFieldName) {
     return 0;
diff --git a/src/anki-integration/card-creation-manual-update.test.ts b/src/anki-integration/card-creation-manual-update.test.ts
index 59cbe267..4ff20aa6 100644
--- a/src/anki-integration/card-creation-manual-update.test.ts
+++ b/src/anki-integration/card-creation-manual-update.test.ts
@@ -85,6 +85,7 @@ function createManualUpdateService(overrides: Partial<CardCreationDeps> = {}): {
       },
       findNotes: async () => [42],
       retrieveMediaFile: async () => '',
+      deleteNotes: async () => undefined,
     },
     mediaGenerator: {
       generateAudio: async () => Buffer.from('audio'),
@@ -124,11 +125,11 @@ function createManualUpdateService(overrides: Partial<CardCreationDeps> = {}): {
       audioField: 'SentenceAudio',
       lapisEnabled: false,
       kikuEnabled: false,
-      kikuFieldGrouping: 'disabled',
-      kikuDeleteDuplicateInAuto: false,
+      fieldGroupingMode: 'disabled',
     }),
     getFallbackDurationSeconds: () => 10,
     appendKnownWordsFromNoteInfo: () => undefined,
+    removeKnownWordNote: () => undefined,
     isUpdateInProgress: () => false,
     setUpdateInProgress: () => undefined,
     trackLastAddedNoteId: () => undefined,
@@ -143,7 +144,7 @@ function createManualUpdateService(overrides: Partial<CardCreationDeps> = {}): {
   };
 }
 
-test('manual clipboard subtitle update replaces sentence audio without touching expression audio', async () => {
+test('manual clipboard subtitle update replaces audio in the configured field', async () => {
   const { service, updatedFields, mergeCalls, storedMedia } = createManualUpdateService();
 
   await service.updateLastAddedFromClipboard('字幕');
@@ -151,14 +152,190 @@ test('manual clipboard subtitle update replaces sentence audio without touching
   assert.equal(updatedFields.length, 1);
   assert.equal(storedMedia.length, 1);
   const audioValue = `[sound:${storedMedia[0]}]`;
-  assert.equal(updatedFields[0]?.SentenceAudio, audioValue);
-  assert.equal('ExpressionAudio' in updatedFields[0]!, false);
+  assert.equal(updatedFields[0]?.ExpressionAudio, audioValue);
+  assert.equal('SentenceAudio' in updatedFields[0]!, false);
   assert.deepEqual(
     mergeCalls.map((call) => call.overwrite),
     [true],
   );
 });
 
+test('manual clipboard mining treats a zero media duration cap as unlimited', async () => {
+  const audioRanges: Array<{ start: number; end: number; padding: number | undefined }> = [];
+  const scenarios = [
+    { maxMediaDuration: 0, expectedEnd: 14 },
+    { maxMediaDuration: 1, expectedEnd: 13 },
+  ];
+
+  for (const scenario of scenarios) {
+    const { service } = createManualUpdateService({
+      getConfig: () =>
+        ({
+          deck: 'Mining',
+          fields: {
+            word: 'Expression',
+            sentence: 'Sentence',
+            audio: 'ExpressionAudio',
+          },
+          media: {
+            generateAudio: true,
+            generateImage: false,
+            audioPadding: 0.25,
+            maxMediaDuration: scenario.maxMediaDuration,
+          },
+          behavior: {},
+          ai: false,
+        }) as AnkiConnectConfig,
+      mediaGenerator: {
+        generateAudio: async (_path, start, end, padding) => {
+          audioRanges.push({ start, end, padding });
+          return Buffer.from('audio');
+        },
+        generateScreenshot: async () => null,
+        generateAnimatedImage: async () => null,
+      },
+    });
+
+    await service.updateLastAddedFromClipboard('字幕');
+
+    assert.deepEqual(audioRanges.at(-1), {
+      start: 12,
+      end: scenario.expectedEnd,
+      padding: 0.25,
+    });
+  }
+});
+
+test('manual clipboard word-card update uses configured fields with Lapis and Kiku enabled', async () => {
+  const { service, updatedFields } = createManualUpdateService({
+    getConfig: () =>
+      ({
+        deck: 'Mining',
+        fields: {
+          word: 'Expression',
+          sentence: 'Context',
+          audio: 'ContextAudio',
+        },
+        media: {
+          generateAudio: true,
+          generateImage: false,
+          maxMediaDuration: 30,
+        },
+        behavior: {
+          overwriteAudio: false,
+          overwriteImage: false,
+        },
+        ai: false,
+      }) as AnkiConnectConfig,
+    client: {
+      addNote: async () => 0,
+      addTags: async () => undefined,
+      notesInfo: async () => [
+        {
+          noteId: 42,
+          fields: {
+            Expression: { value: '単語' },
+            Sentence: { value: '' },
+            SentenceAudio: { value: '' },
+            Context: { value: '' },
+            ContextAudio: { value: '' },
+          },
+        },
+      ],
+      updateNoteFields: async (_noteId, fields) => {
+        updatedFields.push(fields);
+      },
+      storeMediaFile: async () => undefined,
+      findNotes: async () => [42],
+      retrieveMediaFile: async () => '',
+      deleteNotes: async () => undefined,
+    },
+    getEffectiveSentenceCardConfig: () => ({
+      model: 'Sentence',
+      sentenceField: 'Sentence',
+      audioField: 'SentenceAudio',
+      lapisEnabled: true,
+      kikuEnabled: true,
+      fieldGroupingMode: 'disabled',
+    }),
+  });
+
+  await service.updateLastAddedFromClipboard('字幕');
+
+  assert.equal(updatedFields.length, 1);
+  assert.match(updatedFields[0]?.ContextAudio ?? '', /^\[sound:audio_\d+\.mp3\]$/);
+  assert.deepEqual(Object.keys(updatedFields[0] ?? {}).sort(), ['Context', 'ContextAudio']);
+  assert.equal(updatedFields[0]?.Context, '字幕');
+});
+
+test('audio-card action keeps Lapis and Kiku sentence fields', async () => {
+  const { service, updatedFields } = createManualUpdateService({
+    getConfig: () =>
+      ({
+        deck: 'Mining',
+        fields: {
+          word: 'Expression',
+          sentence: 'Context',
+          audio: 'ContextAudio',
+        },
+        media: {
+          generateAudio: true,
+          generateImage: false,
+          maxMediaDuration: 30,
+        },
+        behavior: {},
+        ai: false,
+      }) as AnkiConnectConfig,
+    getMpvClient: () =>
+      ({
+        currentVideoPath: '/video.mp4',
+        currentAudioStreamIndex: 0,
+        currentSubText: '字幕',
+        currentSubStart: 12,
+        currentSubEnd: 14,
+      }) as never,
+    client: {
+      addNote: async () => 0,
+      addTags: async () => undefined,
+      notesInfo: async () => [
+        {
+          noteId: 42,
+          fields: {
+            Expression: { value: '単語' },
+            Sentence: { value: '' },
+            SentenceAudio: { value: '' },
+            Context: { value: '' },
+            ContextAudio: { value: '' },
+          },
+        },
+      ],
+      updateNoteFields: async (_noteId, fields) => {
+        updatedFields.push(fields);
+      },
+      storeMediaFile: async () => undefined,
+      findNotes: async () => [42],
+      retrieveMediaFile: async () => '',
+      deleteNotes: async () => undefined,
+    },
+    getEffectiveSentenceCardConfig: () => ({
+      model: 'Sentence',
+      sentenceField: 'Sentence',
+      audioField: 'SentenceAudio',
+      lapisEnabled: true,
+      kikuEnabled: true,
+      fieldGroupingMode: 'disabled',
+    }),
+  });
+
+  await service.markLastCardAsAudioCard();
+
+  assert.equal(updatedFields.length, 1);
+  assert.equal(updatedFields[0]?.Sentence, '字幕');
+  assert.match(updatedFields[0]?.SentenceAudio ?? '', /^\[sound:audio_\d+\.mp3\]$/);
+  assert.equal('Context' in (updatedFields[0] ?? {}), false);
+  assert.equal('ContextAudio' in (updatedFields[0] ?? {}), false);
+});
+
 test('manual clipboard subtitle update marks Kiku word cards as word-and-sentence cards when enabled', async () => {
   const { service, updatedFields } = createManualUpdateService({
     getConfig: () =>
@@ -201,6 +378,7 @@ test('manual clipboard subtitle update marks Kiku word cards as word-and-sentenc
       storeMediaFile: async () => undefined,
       findNotes: async () => [42],
       retrieveMediaFile: async () => '',
+      deleteNotes: async () => undefined,
     },
     getEffectiveSentenceCardConfig: () => ({
       model: 'Sentence',
@@ -208,8 +386,7 @@ test('manual clipboard subtitle update marks Kiku word cards as word-and-sentenc
       audioField: 'SentenceAudio',
       lapisEnabled: false,
       kikuEnabled: true,
-      kikuFieldGrouping: 'disabled',
-      kikuDeleteDuplicateInAuto: false,
+      fieldGroupingMode: 'disabled',
     }),
     setCardTypeFields,
   });
@@ -225,7 +402,7 @@ test('manual clipboard subtitle update marks Kiku word cards as word-and-sentenc
   });
 });
 
-test('manual clipboard subtitle update skips audio when sentence audio field is missing', async () => {
+test('manual clipboard subtitle update uses configured audio when SentenceAudio is missing', async () => {
   const { service, updatedFields, mergeCalls, storedMedia } = createManualUpdateService({
     client: {
       addNote: async () => 0,
@@ -248,6 +425,7 @@ test('manual clipboard subtitle update skips audio when sentence audio field is
       },
       findNotes: async () => [42],
       retrieveMediaFile: async () => '',
+      deleteNotes: async () => undefined,
     },
   });
 
@@ -255,8 +433,9 @@ test('manual clipboard subtitle update skips audio when sentence audio field is
 
   assert.equal(storedMedia.length, 1);
   assert.equal(updatedFields.length, 1);
-  assert.deepEqual(updatedFields[0], { Sentence: '字幕' });
-  assert.equal(mergeCalls.length, 0);
+  assert.match(updatedFields[0]?.ExpressionAudio ?? '', /^\[sound:audio_\d+\.mp3\]$/);
+  assert.equal(updatedFields[0]?.Sentence, '字幕');
+  assert.equal(mergeCalls.length, 1);
 });
 
 test('manual clipboard subtitle update uses resolved mpv stream URLs for remote media', async () => {
@@ -335,6 +514,7 @@ test('manual clipboard subtitle update uses resolved mpv stream URLs for remote
       },
       findNotes: async () => [42],
       retrieveMediaFile: async () => '',
+      deleteNotes: async () => undefined,
     },
     mediaGenerator: {
       generateAudio: async (path) => {
@@ -383,3 +563,98 @@ test('createSentenceCard relies on Anki progress notification without standalone
   assert.deepEqual(progressMessages, ['Creating sentence card']);
   assert.deepEqual(statusMessages, []);
 });
+
+test('discarding an audio-card timing review deletes the note before evicting its cache entry', async () => {
+  const events: string[] = [];
+  const statusMessages: string[] = [];
+  const { service } = createManualUpdateService({
+    getMpvClient: () =>
+      ({
+        currentVideoPath: '/video.mp4',
+        currentSubText: '字幕',
+        currentSubStart: 4,
+        currentSubEnd: 6,
+        currentTimePos: 5,
+      }) as never,
+    client: {
+      addNote: async () => 0,
+      addTags: async () => undefined,
+      notesInfo: async () => [
+        {
+          noteId: 42,
+          fields: { Expression: { value: '単語' } },
+        },
+      ],
+      updateNoteFields: async () => undefined,
+      storeMediaFile: async () => undefined,
+      findNotes: async () => [42],
+      retrieveMediaFile: async () => '',
+      deleteNotes: async (noteIds) => {
+        events.push(`delete:${noteIds.join(',')}`);
+      },
+    },
+    reviewMediaTiming: async () => ({ action: 'discard' }),
+    removeKnownWordNote: (noteId) => {
+      events.push(`cache:${noteId}`);
+    },
+    showStatusNotification: (message) => {
+      statusMessages.push(message);
+    },
+  });
+
+  await service.markLastCardAsAudioCard();
+
+  assert.deepEqual(events, ['delete:42', 'cache:42']);
+  assert.deepEqual(statusMessages, ['Card deleted.']);
+});
+
+test('keeping an audio card without media skips generation and preserves the note', async () => {
+  let generatedAudio = false;
+  let deleted = false;
+  const updates: Array<{ noteId: number; fields: Record<string, string> }> = [];
+  const { service, storedMedia } = createManualUpdateService({
+    getMpvClient: () =>
+      ({
+        currentVideoPath: '/video.mp4',
+        currentSubText: '字幕',
+        currentSubStart: 4,
+        currentSubEnd: 6,
+        currentTimePos: 5,
+      }) as never,
+    client: {
+      addNote: async () => 0,
+      addTags: async () => undefined,
+      notesInfo: async () => [
+        {
+          noteId: 42,
+          fields: { Expression: { value: '単語' }, Sentence: { value: '' } },
+        },
+      ],
+      updateNoteFields: async (noteId, fields) => {
+        updates.push({ noteId, fields });
+      },
+      storeMediaFile: async () => undefined,
+      findNotes: async () => [42],
+      retrieveMediaFile: async () => '',
+      deleteNotes: async () => {
+        deleted = true;
+      },
+    },
+    mediaGenerator: {
+      generateAudio: async () => {
+        generatedAudio = true;
+        return Buffer.from('audio');
+      },
+      generateScreenshot: async () => null,
+      generateAnimatedImage: async () => null,
+    },
+    reviewMediaTiming: async () => ({ action: 'skip-media' }),
+  });
+
+  await service.markLastCardAsAudioCard();
+
+  assert.equal(generatedAudio, false);
+  assert.equal(deleted, false);
+  assert.deepEqual(storedMedia, []);
+  assert.deepEqual(updates, [{ noteId: 42, fields: { Sentence: '字幕' } }]);
+});
diff --git a/src/anki-integration/card-creation-sentence-media.test.ts b/src/anki-integration/card-creation-sentence-media.test.ts
index d8bb27cc..baadfd92 100644
--- a/src/anki-integration/card-creation-sentence-media.test.ts
+++ b/src/anki-integration/card-creation-sentence-media.test.ts
@@ -12,6 +12,7 @@ test('sentence card writes generated audio only to sentence audio field', async
   const storedMedia: string[] = [];
   const requestedProperties: string[] = [];
   const audioVolumeScales: Array<number | undefined> = [];
+  const audioRanges: Array<{ start: number; end: number; padding: number | undefined }> = [];
 
   const deps: CardCreationDeps = {
     getConfig: () =>
@@ -73,17 +74,19 @@ test('sentence card writes generated audio only to sentence audio field', async
       },
       findNotes: async () => [],
       retrieveMediaFile: async () => '',
+      deleteNotes: async () => undefined,
     },
     mediaGenerator: {
       generateAudio: async (
         _path,
-        _startTime,
-        _endTime,
-        _audioPadding,
+        startTime,
+        endTime,
+        audioPadding,
         _audioStreamIndex,
         _normalizeAudio,
         volumeScale,
       ) => {
+        audioRanges.push({ start: startTime, end: endTime, padding: audioPadding });
         audioVolumeScales.push(volumeScale);
         return Buffer.from('audio');
       },
@@ -117,22 +120,19 @@ test('sentence card writes generated audio only to sentence audio field', async
       audioField: 'SentenceAudio',
       lapisEnabled: true,
       kikuEnabled: false,
-      kikuFieldGrouping: 'disabled',
-      kikuDeleteDuplicateInAuto: false,
+      fieldGroupingMode: 'disabled',
     }),
     getFallbackDurationSeconds: () => 10,
     appendKnownWordsFromNoteInfo: () => undefined,
+    removeKnownWordNote: () => undefined,
     isUpdateInProgress: () => false,
     setUpdateInProgress: () => undefined,
     trackLastAddedNoteId: () => undefined,
+    reviewMediaTiming: async () => ({ action: 'confirm', startTime: 11.4, endTime: 14.2 }),
   };
 
-  const created = await new CardCreationService(deps).createSentenceCard(
-    '字幕',
-    12,
-    14,
-    'Subtitle',
-  );
+  const service = new CardCreationService(deps);
+  const created = await service.createSentenceCard('字幕', 12, 14, 'Subtitle');
 
   assert.equal(created, true);
   assert.deepEqual(addedFields[0], {
@@ -144,7 +144,19 @@ test('sentence card writes generated audio only to sentence audio field', async
   assert.equal(storedMedia.length, 1);
   assert.deepEqual(requestedProperties, ['volume']);
   assert.deepEqual(audioVolumeScales, [0.4 ** 3]);
+  assert.deepEqual(audioRanges, [{ start: 11.4, end: 14.2, padding: 0 }]);
   const mediaUpdate = updatedFields.find((fields) => 'SentenceAudio' in fields);
   assert.equal(mediaUpdate?.SentenceAudio, `[sound:${storedMedia[0]}]`);
   assert.equal('ExpressionAudio' in mediaUpdate!, false);
+
+  deps.reviewMediaTiming = async () => ({ action: 'discard' });
+  assert.equal(await service.createSentenceCard('作らない', 20, 22), false);
+  assert.equal(addedFields.length, 1);
+
+  deps.reviewMediaTiming = async () => ({ action: 'skip-media' });
+  assert.equal(await service.createSentenceCard('メディアなし', 30, 32), true);
+  assert.equal(addedFields.length, 2);
+  assert.equal(storedMedia.length, 1);
+  assert.deepEqual(audioRanges, [{ start: 11.4, end: 14.2, padding: 0 }]);
+  assert.deepEqual(requestedProperties, ['volume']);
 });
diff --git a/src/anki-integration/card-creation.test.ts b/src/anki-integration/card-creation.test.ts
index 19159887..881ebe5f 100644
--- a/src/anki-integration/card-creation.test.ts
+++ b/src/anki-integration/card-creation.test.ts
@@ -42,6 +42,7 @@ test('CardCreationService counts locally created sentence cards', async () => {
       storeMediaFile: async () => undefined,
       findNotes: async () => [],
       retrieveMediaFile: async () => '',
+      deleteNotes: async () => undefined,
     },
     mediaGenerator: {
       generateAudio: async () => null,
@@ -69,11 +70,11 @@ test('CardCreationService counts locally created sentence cards', async () => {
       audioField: 'SentenceAudio',
       lapisEnabled: false,
       kikuEnabled: false,
-      kikuFieldGrouping: 'disabled',
-      kikuDeleteDuplicateInAuto: false,
+      fieldGroupingMode: 'disabled',
     }),
     getFallbackDurationSeconds: () => 10,
     appendKnownWordsFromNoteInfo: () => undefined,
+    removeKnownWordNote: () => undefined,
     isUpdateInProgress: () => false,
     setUpdateInProgress: () => undefined,
     trackLastAddedNoteId: () => undefined,
@@ -139,6 +140,7 @@ test('CardCreationService keeps updating after trackLastAddedNoteId throws', asy
       storeMediaFile: async () => undefined,
       findNotes: async () => [],
       retrieveMediaFile: async () => '',
+      deleteNotes: async () => undefined,
     },
     mediaGenerator: {
       generateAudio: async () => null,
@@ -168,11 +170,11 @@ test('CardCreationService keeps updating after trackLastAddedNoteId throws', asy
       audioField: 'SentenceAudio',
       lapisEnabled: false,
       kikuEnabled: false,
-      kikuFieldGrouping: 'disabled',
-      kikuDeleteDuplicateInAuto: false,
+      fieldGroupingMode: 'disabled',
     }),
     getFallbackDurationSeconds: () => 10,
     appendKnownWordsFromNoteInfo: () => undefined,
+    removeKnownWordNote: () => undefined,
     isUpdateInProgress: () => false,
     setUpdateInProgress: () => undefined,
     trackLastAddedNoteId: () => {
@@ -238,6 +240,7 @@ test('CardCreationService keeps updating after recordCardsMinedCallback throws',
       storeMediaFile: async () => undefined,
       findNotes: async () => [],
       retrieveMediaFile: async () => '',
+      deleteNotes: async () => undefined,
     },
     mediaGenerator: {
       generateAudio: async () => null,
@@ -267,11 +270,11 @@ test('CardCreationService keeps updating after recordCardsMinedCallback throws',
       audioField: 'SentenceAudio',
       lapisEnabled: false,
       kikuEnabled: false,
-      kikuFieldGrouping: 'disabled',
-      kikuDeleteDuplicateInAuto: false,
+      fieldGroupingMode: 'disabled',
     }),
     getFallbackDurationSeconds: () => 10,
     appendKnownWordsFromNoteInfo: () => undefined,
+    removeKnownWordNote: () => undefined,
     isUpdateInProgress: () => false,
     setUpdateInProgress: () => undefined,
     recordCardsMinedCallback: () => {
@@ -287,6 +290,9 @@ test('CardCreationService keeps updating after recordCardsMinedCallback throws',
 });
 
 test('CardCreationService uses stream-open-filename for remote media generation', async () => {
+  let reviewing = false;
+  const audioRanges: number[][] = [];
+  const imageTimes: number[] = [];
   const audioPaths: string[] = [];
   const imagePaths: string[] = [];
   const recordMediaPath = (mediaInput: MediaInput): string =>
@@ -316,6 +322,10 @@ test('CardCreationService uses stream-open-filename for remote media generation'
         behavior: {},
         ai: false,
       }) as AnkiConnectConfig,
+    reviewMediaTiming: async () =>
+      reviewing
+        ? { action: 'confirm', startTime: 0.2, endTime: 0.8, screenshotTime: 3.125 }
+        : { action: 'use-original' },
     getAiConfig: () => ({}),
     getTimingTracker: () => ({}) as never,
     getMpvClient: () =>
@@ -346,15 +356,18 @@ test('CardCreationService uses stream-open-filename for remote media generation'
       ],
       updateNoteFields: async () => undefined,
       storeMediaFile: async () => undefined,
-      findNotes: async () => [],
+      findNotes: async () => [42],
       retrieveMediaFile: async () => '',
+      deleteNotes: async () => undefined,
     },
     mediaGenerator: {
-      generateAudio: async (path) => {
+      generateAudio: async (path, start, end, padding) => {
+        audioRanges.push([start, end, padding ?? -1]);
         audioPaths.push(recordMediaPath(path));
         return Buffer.from('audio');
       },
-      generateScreenshot: async (path) => {
+      generateScreenshot: async (path, timestamp) => {
+        imageTimes.push(timestamp);
         imagePaths.push(recordMediaPath(path));
         return Buffer.from('image');
       },
@@ -387,11 +400,11 @@ test('CardCreationService uses stream-open-filename for remote media generation'
       audioField: 'SentenceAudio',
       lapisEnabled: false,
       kikuEnabled: false,
-      kikuFieldGrouping: 'disabled',
-      kikuDeleteDuplicateInAuto: false,
+      fieldGroupingMode: 'disabled',
     }),
     getFallbackDurationSeconds: () => 10,
     appendKnownWordsFromNoteInfo: () => undefined,
+    removeKnownWordNote: () => undefined,
     isUpdateInProgress: () => false,
     setUpdateInProgress: () => undefined,
     trackLastAddedNoteId: () => undefined,
@@ -402,6 +415,14 @@ test('CardCreationService uses stream-open-filename for remote media generation'
   assert.equal(created, true);
   assert.deepEqual(audioPaths, [audioUrl]);
   assert.deepEqual(imagePaths, [videoUrl]);
+  reviewing = true;
+  assert.equal(await service.createSentenceCard('テスト', 0, 1), true);
+  assert.deepEqual(audioRanges.at(-1), [0.2, 0.8, 0]);
+  assert.equal(imageTimes.at(-1), 3.125);
+  await service.markLastCardAsAudioCard();
+  assert.equal(imageTimes.length, 3);
+  assert.deepEqual(audioRanges.at(-1), [0.2, 0.8, 0]);
+  assert.equal(imageTimes.at(-1), 3.125);
 });
 
 test('CardCreationService does not use mpv stream indexes for ready cached YouTube media', async () => {
@@ -454,6 +475,7 @@ test('CardCreationService does not use mpv stream indexes for ready cached YouTu
       storeMediaFile: async () => undefined,
       findNotes: async () => [],
       retrieveMediaFile: async () => '',
+      deleteNotes: async () => undefined,
     },
     mediaGenerator: {
       generateAudio: async (path, _startTime, _endTime, _padding, audioStreamIndex) => {
@@ -490,11 +512,11 @@ test('CardCreationService does not use mpv stream indexes for ready cached YouTu
       audioField: 'SentenceAudio',
       lapisEnabled: false,
       kikuEnabled: false,
-      kikuFieldGrouping: 'disabled',
-      kikuDeleteDuplicateInAuto: false,
+      fieldGroupingMode: 'disabled',
     }),
     getFallbackDurationSeconds: () => 10,
     appendKnownWordsFromNoteInfo: () => undefined,
+    removeKnownWordNote: () => undefined,
     isUpdateInProgress: () => false,
     setUpdateInProgress: () => undefined,
     trackLastAddedNoteId: () => undefined,
@@ -590,6 +612,7 @@ test('CardCreationService queues YouTube media when required cache is not ready'
       storeMediaFile: async () => undefined,
       findNotes: async () => [],
       retrieveMediaFile: async () => '',
+      deleteNotes: async () => undefined,
     },
     mediaGenerator: {
       generateAudio: async () => {
@@ -629,11 +652,11 @@ test('CardCreationService queues YouTube media when required cache is not ready'
       audioField: 'SentenceAudio',
       lapisEnabled: false,
       kikuEnabled: false,
-      kikuFieldGrouping: 'disabled',
-      kikuDeleteDuplicateInAuto: false,
+      fieldGroupingMode: 'disabled',
     }),
     getFallbackDurationSeconds: () => 10,
     appendKnownWordsFromNoteInfo: () => undefined,
+    removeKnownWordNote: () => undefined,
     isUpdateInProgress: () => false,
     setUpdateInProgress: () => undefined,
     trackLastAddedNoteId: () => undefined,
@@ -701,6 +724,7 @@ test('CardCreationService tracks pre-add duplicate note ids for kiku sentence ca
       storeMediaFile: async () => undefined,
       findNotes: async () => [],
       retrieveMediaFile: async () => '',
+      deleteNotes: async () => undefined,
     },
     mediaGenerator: {
       generateAudio: async () => null,
@@ -728,11 +752,11 @@ test('CardCreationService tracks pre-add duplicate note ids for kiku sentence ca
       audioField: 'SentenceAudio',
       lapisEnabled: false,
       kikuEnabled: true,
-      kikuFieldGrouping: 'manual',
-      kikuDeleteDuplicateInAuto: false,
+      fieldGroupingMode: 'manual',
     }),
     getFallbackDurationSeconds: () => 10,
     appendKnownWordsFromNoteInfo: () => undefined,
+    removeKnownWordNote: () => undefined,
     isUpdateInProgress: () => false,
     setUpdateInProgress: () => undefined,
     trackLastAddedNoteId: () => undefined,
@@ -790,6 +814,7 @@ test('CardCreationService does not track duplicate ids when pre-add lookup retur
       storeMediaFile: async () => undefined,
       findNotes: async () => [],
       retrieveMediaFile: async () => '',
+      deleteNotes: async () => undefined,
     },
     mediaGenerator: {
       generateAudio: async () => null,
@@ -817,11 +842,11 @@ test('CardCreationService does not track duplicate ids when pre-add lookup retur
       audioField: 'SentenceAudio',
       lapisEnabled: false,
       kikuEnabled: true,
-      kikuFieldGrouping: 'manual',
-      kikuDeleteDuplicateInAuto: false,
+      fieldGroupingMode: 'manual',
     }),
     getFallbackDurationSeconds: () => 10,
     appendKnownWordsFromNoteInfo: () => undefined,
+    removeKnownWordNote: () => undefined,
     isUpdateInProgress: () => false,
     setUpdateInProgress: () => undefined,
     trackLastAddedNoteId: () => undefined,
diff --git a/src/anki-integration/card-creation.ts b/src/anki-integration/card-creation.ts
index abfe41f3..5917b292 100644
--- a/src/anki-integration/card-creation.ts
+++ b/src/anki-integration/card-creation.ts
@@ -3,7 +3,13 @@ import {
   getConfiguredWordFieldName,
   getPreferredWordValueFromExtractedFields,
 } from '../anki-field-config';
-import { AnkiConnectConfig, type CardKind, type WordCardKind } from '../types/anki';
+import {
+  AnkiConnectConfig,
+  type CardKind,
+  type MediaTimingReviewDecision,
+  type MediaTimingReviewRequest,
+  type WordCardKind,
+} from '../types/anki';
 import { createLogger } from '../logger';
 import type { MediaInput } from '../media-input';
 import { SubtitleTimingTracker } from '../subtitle-timing-tracker';
@@ -15,6 +21,7 @@ import {
   resolveAudioStreamIndexForMediaGeneration,
   type MediaGenerationInputResolverOptions,
 } from './media-source';
+import { clampMediaEndTime } from './media-duration';
 import { resolveWordCardKind } from './note-field-utils';
 import type { PendingYoutubeMediaUpdate } from './pending-youtube-media';
 import { resolveMpvVolumeScale } from './mpv-volume';
@@ -55,6 +62,7 @@ interface CardCreationClient {
   storeMediaFile(filename: string, data: Buffer): Promise<void>;
   findNotes(query: string, options?: { maxRetries?: number }): Promise<number[]>;
   retrieveMediaFile(filename: string): Promise<string>;
+  deleteNotes(noteIds: number[]): Promise<void>;
 }
 
 interface CardCreationMediaGenerator {
@@ -132,18 +140,21 @@ interface CardCreationDeps {
     audioField: string;
     lapisEnabled: boolean;
     kikuEnabled: boolean;
-    kikuFieldGrouping: 'auto' | 'manual' | 'disabled';
-    kikuDeleteDuplicateInAuto: boolean;
+    fieldGroupingMode: 'auto' | 'manual' | 'disabled';
     wordCardKind?: WordCardKind;
   };
   getFallbackDurationSeconds: () => number;
   appendKnownWordsFromNoteInfo: (noteInfo: CardCreationNoteInfo) => void;
+  removeKnownWordNote: (noteId: number) => void;
   isUpdateInProgress: () => boolean;
   setUpdateInProgress: (value: boolean) => void;
   trackLastAddedNoteId?: (noteId: number) => void;
   trackLastAddedDuplicateNoteIds?: (noteId: number, duplicateNoteIds: number[]) => void;
   findDuplicateNoteIds?: (expression: string, noteInfo: CardCreationNoteInfo) => Promise<number[]>;
   recordCardsMinedCallback?: (count: number, noteIds?: number[]) => void;
+  reviewMediaTiming?: (
+    request: Omit<MediaTimingReviewRequest, 'audioPadding' | 'maxMediaDuration'>,
+  ) => Promise<MediaTimingReviewDecision>;
 }
 
 export class CardCreationService {
@@ -223,11 +234,12 @@ export class CardCreationService {
       let rangeEnd = Math.max(...timings.map((entry) => entry.endTime));
 
       const maxMediaDuration = this.deps.getConfig().media?.maxMediaDuration ?? 30;
-      if (maxMediaDuration > 0 && rangeEnd - rangeStart > maxMediaDuration) {
+      const cappedRangeEnd = clampMediaEndTime(rangeStart, rangeEnd, maxMediaDuration);
+      if (cappedRangeEnd !== rangeEnd) {
         log.warn(
           `Media range ${(rangeEnd - rangeStart).toFixed(1)}s exceeds cap of ${maxMediaDuration}s, clamping`,
         );
-        rangeEnd = rangeStart + maxMediaDuration;
+        rangeEnd = cappedRangeEnd;
       }
 
       this.deps.showOsdNotification('Updating card from clipboard...');
@@ -260,9 +272,16 @@ export class CardCreationService {
           fields,
           this.deps.getConfig(),
         );
-        const sentenceAudioField = this.getResolvedSentenceOnlyAudioFieldName(noteInfo);
+        const config = this.deps.getConfig();
+        const sentenceAudioField = this.deps.resolveConfiguredFieldName(
+          noteInfo,
+          config.fields?.audio ?? DEFAULT_ANKI_CONNECT_CONFIG.fields.audio,
+        );
         const sentenceCardConfig = this.deps.getEffectiveSentenceCardConfig();
-        const sentenceField = sentenceCardConfig.sentenceField;
+        const sentenceField = this.deps.resolveConfiguredFieldName(
+          noteInfo,
+          config.fields?.sentence ?? DEFAULT_ANKI_CONNECT_CONFIG.fields.sentence,
+        );
 
         const sentence = blocks.join(' ');
         const updatedFields: Record<string, string> = {};
@@ -284,7 +303,6 @@ export class CardCreationService {
           `Clipboard update: timing range ${rangeStart.toFixed(2)}s - ${rangeEnd.toFixed(2)}s`,
         );
 
-        const config = this.deps.getConfig();
         const generateAudio = shouldGenerateAudio(config);
         const generateImage = shouldGenerateImage(config);
         const mediaResolverOptions = this.getMediaResolverOptions();
@@ -421,9 +439,7 @@ export class CardCreationService {
       }
 
       const maxMediaDuration = this.deps.getConfig().media?.maxMediaDuration ?? 30;
-      if (maxMediaDuration > 0 && endTime - startTime > maxMediaDuration) {
-        endTime = startTime + maxMediaDuration;
-      }
+      endTime = clampMediaEndTime(startTime, endTime, maxMediaDuration);
 
       this.deps.showOsdNotification('Marking card as audio card...');
       await this.deps.withUpdateProgress('Marking audio card', async () => {
@@ -451,39 +467,66 @@ export class CardCreationService {
           this.deps.getConfig(),
         );
 
+        const timingDecision = this.deps.reviewMediaTiming
+          ? await this.deps.reviewMediaTiming({
+              kind: 'audio',
+              text: mpvClient.currentSubText,
+              startTime,
+              endTime,
+              noteId,
+            })
+          : ({ action: 'use-original' } as const);
+        if (timingDecision.action === 'discard') {
+          await this.deps.client.deleteNotes([noteId]);
+          this.deps.removeKnownWordNote(noteId);
+          this.deps.showStatusNotification('Card deleted.');
+          return;
+        }
+        const skipMedia = timingDecision.action === 'skip-media';
+        const exactReviewedRange = timingDecision.action === 'confirm';
+        let sentenceText = mpvClient.currentSubText;
+        if (timingDecision.action === 'confirm') {
+          startTime = timingDecision.startTime;
+          endTime = timingDecision.endTime;
+          sentenceText = timingDecision.text?.trim() || sentenceText;
+        }
+
         const updatedFields: Record<string, string> = {};
         const errors: string[] = [];
         let miscInfoFilename: string | null = null;
 
         this.deps.setCardTypeFields(updatedFields, Object.keys(noteInfo.fields), 'audio');
 
-        const sentenceField = this.deps.getConfig().fields?.sentence;
+        const sentenceCardConfig = this.deps.getEffectiveSentenceCardConfig();
+        const sentenceField = sentenceCardConfig.sentenceField;
         if (sentenceField) {
-          const processedSentence = this.deps.processSentence(mpvClient.currentSubText, fields);
+          const processedSentence = this.deps.processSentence(sentenceText, fields);
           updatedFields[sentenceField] = processedSentence;
         }
 
-        const sentenceCardConfig = this.deps.getEffectiveSentenceCardConfig();
         const audioFieldName = sentenceCardConfig.audioField;
-        try {
-          const audioFilename = this.generateAudioFilename();
-          const audioBuffer = await this.mediaGenerateAudio(
-            mpvClient.currentVideoPath,
-            startTime,
-            endTime,
-          );
+        if (!skipMedia) {
+          try {
+            const audioFilename = this.generateAudioFilename();
+            const audioBuffer = await this.mediaGenerateAudio(
+              mpvClient.currentVideoPath,
+              startTime,
+              endTime,
+              exactReviewedRange ? 0 : undefined,
+            );
 
-          if (audioBuffer) {
-            await this.deps.client.storeMediaFile(audioFilename, audioBuffer);
-            updatedFields[audioFieldName] = `[sound:${audioFilename}]`;
-            miscInfoFilename = audioFilename;
+            if (audioBuffer) {
+              await this.deps.client.storeMediaFile(audioFilename, audioBuffer);
+              updatedFields[audioFieldName] = `[sound:${audioFilename}]`;
+              miscInfoFilename = audioFilename;
+            }
+          } catch (error) {
+            log.error('Failed to generate audio for audio card:', (error as Error).message);
+            errors.push('audio');
           }
-        } catch (error) {
-          log.error('Failed to generate audio for audio card:', (error as Error).message);
-          errors.push('audio');
         }
 
-        if (shouldGenerateImage(this.deps.getConfig())) {
+        if (!skipMedia && shouldGenerateImage(this.deps.getConfig())) {
           try {
             const animatedLeadInSeconds = await this.deps.getAnimatedImageLeadInSeconds(noteInfo);
             const imageFilename = this.generateImageFilename();
@@ -492,6 +535,8 @@ export class CardCreationService {
               startTime,
               endTime,
               animatedLeadInSeconds,
+              exactReviewedRange,
+              timingDecision.action === 'confirm' ? timingDecision.screenshotTime : undefined,
             );
 
             const imageField = this.deps.getConfig().fields?.image;
@@ -555,18 +600,39 @@ export class CardCreationService {
     }
 
     const maxMediaDuration = this.deps.getConfig().media?.maxMediaDuration ?? 30;
-    if (maxMediaDuration > 0 && endTime - startTime > maxMediaDuration) {
+    const cappedEndTime = clampMediaEndTime(startTime, endTime, maxMediaDuration);
+    if (cappedEndTime !== endTime) {
       log.warn(
         `Sentence card media range ${(endTime - startTime).toFixed(1)}s exceeds cap of ${maxMediaDuration}s, clamping`,
       );
-      endTime = startTime + maxMediaDuration;
+      endTime = cappedEndTime;
     }
 
     try {
       return await this.deps.withUpdateProgress('Creating sentence card', async () => {
+        const timingDecision = this.deps.reviewMediaTiming
+          ? await this.deps.reviewMediaTiming({
+              kind: 'sentence',
+              text: sentence,
+              startTime,
+              endTime,
+            })
+          : ({ action: 'use-original' } as const);
+        if (timingDecision.action === 'discard') {
+          this.deps.showStatusNotification('Card creation cancelled.');
+          return false;
+        }
+        const skipMedia = timingDecision.action === 'skip-media';
+        const exactReviewedRange = timingDecision.action === 'confirm';
+        if (timingDecision.action === 'confirm') {
+          startTime = timingDecision.startTime;
+          endTime = timingDecision.endTime;
+          sentence = timingDecision.text?.trim() || sentence;
+        }
+
         const config = this.deps.getConfig();
-        const generateAudio = shouldGenerateAudio(config);
-        const generateImage = shouldGenerateImage(config);
+        const generateAudio = !skipMedia && shouldGenerateAudio(config);
+        const generateImage = !skipMedia && shouldGenerateImage(config);
         const mediaResolverOptions = this.getMediaResolverOptions();
         const videoPath = generateImage
           ? await resolveMediaGenerationInput(mpvClient, 'video', mediaResolverOptions)
@@ -632,8 +698,7 @@ export class CardCreationService {
         ).trim();
         let duplicateNoteIds: number[] = [];
         if (
-          sentenceCardConfig.kikuEnabled &&
-          sentenceCardConfig.kikuFieldGrouping !== 'disabled' &&
+          sentenceCardConfig.fieldGroupingMode !== 'disabled' &&
           pendingExpressionText &&
           this.deps.findDuplicateNoteIds
         ) {
@@ -732,6 +797,10 @@ export class CardCreationService {
             generateAudio,
             generateImage,
             volumeScale,
+            ...(exactReviewedRange ? { mediaPaddingSeconds: 0 } : {}),
+            ...(timingDecision.action === 'confirm' && timingDecision.screenshotTime !== undefined
+              ? { screenshotTime: timingDecision.screenshotTime }
+              : {}),
           });
           await this.deps.showNotification(noteId, label, 'media queued');
           return true;
@@ -747,7 +816,12 @@ export class CardCreationService {
           try {
             const audioFilename = this.generateAudioFilename();
             const audioBuffer = audioSourcePath
-              ? await this.mediaGenerateAudio(audioSourcePath, startTime, endTime)
+              ? await this.mediaGenerateAudio(
+                  audioSourcePath,
+                  startTime,
+                  endTime,
+                  exactReviewedRange ? 0 : undefined,
+                )
               : null;
 
             if (audioBuffer) {
@@ -765,7 +839,14 @@ export class CardCreationService {
         if (generateImage) {
           try {
             const imageFilename = this.generateImageFilename();
-            const imageBuffer = await this.generateImageBuffer(videoPath!, startTime, endTime);
+            const imageBuffer = await this.generateImageBuffer(
+              videoPath!,
+              startTime,
+              endTime,
+              0,
+              exactReviewedRange,
+              timingDecision.action === 'confirm' ? timingDecision.screenshotTime : undefined,
+            );
 
             const imageField = config.fields?.image;
             if (imageBuffer && imageField) {
@@ -806,22 +887,6 @@ export class CardCreationService {
     }
   }
 
-  private getResolvedSentenceAudioFieldName(noteInfo: CardCreationNoteInfo): string | null {
-    return (
-      this.deps.resolveNoteFieldName(
-        noteInfo,
-        this.deps.getEffectiveSentenceCardConfig().audioField || 'SentenceAudio',
-      ) || this.deps.resolveConfiguredFieldName(noteInfo, this.deps.getConfig().fields?.audio)
-    );
-  }
-
-  private getResolvedSentenceOnlyAudioFieldName(noteInfo: CardCreationNoteInfo): string | null {
-    return this.deps.resolveNoteFieldName(
-      noteInfo,
-      this.deps.getEffectiveSentenceCardConfig().audioField || 'SentenceAudio',
-    );
-  }
-
   private createPendingNoteInfo(fields: Record<string, string>): CardCreationNoteInfo {
     return {
       noteId: -1,
@@ -833,6 +898,7 @@ export class CardCreationService {
     videoPath: MediaInput,
     startTime: number,
     endTime: number,
+    audioPaddingOverride?: number,
   ): Promise<Buffer | null> {
     const mpvClient = this.deps.getMpvClient();
     if (!mpvClient) {
@@ -843,7 +909,7 @@ export class CardCreationService {
       videoPath,
       startTime,
       endTime,
-      this.deps.getConfig().media?.audioPadding,
+      audioPaddingOverride ?? this.deps.getConfig().media?.audioPadding,
       resolveAudioStreamIndexForMediaGeneration(
         videoPath,
         mpvClient.currentAudioStreamIndex ?? undefined,
@@ -861,13 +927,17 @@ export class CardCreationService {
     startTime: number,
     endTime: number,
     animatedLeadInSeconds = 0,
+    exactReviewedRange = false,
+    screenshotTime?: number,
   ): Promise<Buffer | null> {
     const mpvClient = this.deps.getMpvClient();
     if (!mpvClient) {
       return null;
     }
 
-    const timestamp = mpvClient.currentTimePos || 0;
+    const timestamp =
+      screenshotTime ??
+      (exactReviewedRange ? startTime + (endTime - startTime) / 2 : mpvClient.currentTimePos || 0);
 
     if (this.deps.getConfig().media?.imageType === 'avif') {
       let imageStart = startTime;
@@ -883,7 +953,7 @@ export class CardCreationService {
         videoPath,
         imageStart,
         imageEnd,
-        this.deps.getConfig().media?.audioPadding,
+        exactReviewedRange ? 0 : this.deps.getConfig().media?.audioPadding,
         {
           fps: this.deps.getConfig().media?.animatedFps,
           maxWidth: this.deps.getConfig().media?.animatedMaxWidth,
diff --git a/src/anki-integration/field-grouping-merge.test.ts b/src/anki-integration/field-grouping-merge.test.ts
index 1a1494e3..92c04146 100644
--- a/src/anki-integration/field-grouping-merge.test.ts
+++ b/src/anki-integration/field-grouping-merge.test.ts
@@ -26,6 +26,7 @@ function createCollaborator(
       miscInfoValue?: string;
     };
     warnings?: Array<{ fieldName: string; reason: string; detail?: string }>;
+    fieldGroupingProvider?: 'kiku' | 'senren' | null;
   } = {},
 ) {
   const warnings = options.warnings ?? [];
@@ -46,6 +47,8 @@ function createCollaborator(
       getEffectiveSentenceCardConfig: () => ({
         sentenceField: 'Sentence',
         audioField: 'SentenceAudio',
+        fieldGroupingProvider:
+          options.fieldGroupingProvider === undefined ? 'kiku' : options.fieldGroupingProvider,
       }),
       getCurrentSubtitleText: () => options.currentSubtitleText,
       resolveFieldName,
@@ -251,7 +254,218 @@ test('computeFieldGroupingMergedFields uses generated media only when includeGen
   assert.equal(withMedia.MiscInfo, '<span data-group-id="11">generated misc</span>');
 });
 
-test('computeFieldGroupingMergedFields clears SentenceFurigana when either note lacks it', async () => {
+test('computeFieldGroupingMergedFields merges Senren notes into scene-switching markup', async () => {
+  const { collaborator } = createCollaborator({ fieldGroupingProvider: 'senren' });
+
+  const merged = await collaborator.computeFieldGroupingMergedFields(
+    300,
+    200,
+    makeNote(300, {
+      word: '語',
+      sentence: '<span class="group">前<span class="highlight">語</span>後</span>',
+      sentenceAudio: '[sound:original.opus]',
+      picture: '<img src="original.webp">',
+      miscInfo: '<span class="group">Show EP1 (0:01:00)</span>',
+    }),
+    makeNote(200, {
+      word: '語',
+      sentence: '<span class="group">次<span class="highlight">語</span>文</span>',
+      sentenceAudio: '[sound:new.opus]',
+      picture: '<img src="new.webp">',
+      miscInfo: 'Show EP2 (0:02:00)',
+    }),
+    false,
+  );
+
+  assert.equal(
+    merged.sentence,
+    '<span class="group">前<span class="highlight">語</span>後</span>' +
+      '<span class="group2">次<span class="highlight">語</span>文</span>',
+  );
+  assert.equal(merged.sentenceAudio, '[sound:original.opus][sound:new.opus]');
+  assert.equal(merged.picture, '<img src="original.webp"><img src="new.webp">');
+  assert.equal(
+    merged.miscInfo,
+    '<span class="group">Show EP1 (0:01:00)</span><span class="group2">Show EP2 (0:02:00)</span>',
+  );
+});
+
+test('Senren merge warns for invalid source audio when kept audio is empty', async () => {
+  const warnings: Array<{ fieldName: string; reason: string; detail?: string }> = [];
+  const { collaborator } = createCollaborator({
+    fieldGroupingProvider: 'senren',
+    warnings,
+  });
+
+  const merged = await collaborator.computeFieldGroupingMergedFields(
+    300,
+    200,
+    makeNote(300, { SentenceAudio: '' }),
+    makeNote(200, { SentenceAudio: 'invalid audio' }),
+    false,
+  );
+
+  assert.equal(merged.SentenceAudio, 'invalid audio');
+  assert.deepEqual(warnings, [
+    {
+      fieldName: 'SentenceAudio',
+      reason: 'missing-sound-tag',
+      detail: undefined,
+    },
+  ]);
+});
+
+test('Senren merge wraps ungrouped legacy content and preserves numbered groups', async () => {
+  const { collaborator } = createCollaborator({ fieldGroupingProvider: 'senren' });
+
+  const merged = await collaborator.computeFieldGroupingMergedFields(
+    300,
+    200,
+    makeNote(300, {
+      sentence: 'plain legacy sentence',
+      sentenceAudio: '[sound:a.opus][sound:b.opus]',
+      miscInfo: '<span class="group2">pinned</span> stray text',
+    }),
+    makeNote(200, {
+      sentence: '<span class="group">new sentence</span>',
+      sentenceAudio: '[sound:c.opus]',
+      miscInfo: '<span class="group">new misc</span>',
+    }),
+    false,
+  );
+
+  assert.equal(
+    merged.sentence,
+    '<span class="group">plain legacy sentence</span><span class="group3">new sentence</span>',
+  );
+  assert.equal(merged.sentenceAudio, '[sound:a.opus][sound:b.opus][sound:c.opus]');
+  assert.equal(
+    merged.miscInfo,
+    '<span class="group2">pinned</span><span class="group">stray text</span>' +
+      '<span class="group3">new misc</span>',
+  );
+});
+
+test('Senren merge rebases numbered groups from an appended source note', async () => {
+  const { collaborator } = createCollaborator({ fieldGroupingProvider: 'senren' });
+
+  const merged = await collaborator.computeFieldGroupingMergedFields(
+    300,
+    200,
+    makeNote(300, {
+      sentenceAudio: '[sound:keep-a.opus][sound:keep-b.opus]',
+      miscInfo: '<span class="group">keep one</span><span class="group">keep two</span>',
+    }),
+    makeNote(200, {
+      sentenceAudio: '[sound:source-a.opus][sound:source-b.opus]',
+      miscInfo: '<span class="group2">source two</span>',
+    }),
+    false,
+  );
+
+  assert.equal(
+    merged.sentenceAudio,
+    '[sound:keep-a.opus][sound:keep-b.opus][sound:source-a.opus][sound:source-b.opus]',
+  );
+  assert.equal(
+    merged.miscInfo,
+    '<span class="group">keep one</span><span class="group">keep two</span>' +
+      '<span class="group4">source two</span>',
+  );
+});
+
+test('Senren merge rebases plain source groups after empty and sparse kept fields', async () => {
+  const { collaborator } = createCollaborator({ fieldGroupingProvider: 'senren' });
+
+  const merged = await collaborator.computeFieldGroupingMergedFields(
+    300,
+    200,
+    makeNote(300, {
+      sentenceAudio: '[sound:keep-a.opus][sound:keep-b.opus]',
+      sentence: '',
+      miscInfo: '<span class="group">keep first</span>',
+    }),
+    makeNote(200, {
+      sentenceAudio: '[sound:source-a.opus][sound:source-b.opus]',
+      sentence: '<span class="group">source first</span>',
+      miscInfo: '<span class="group">source first</span><span class="group2">source second</span>',
+    }),
+    false,
+  );
+
+  assert.equal(merged.sentence, '<span class="group3">source first</span>');
+  assert.equal(
+    merged.miscInfo,
+    '<span class="group">keep first</span><span class="group3">source first</span>' +
+      '<span class="group4">source second</span>',
+  );
+});
+
+test('Senren merge keeps ungrouped text in place around an existing group span', async () => {
+  const { collaborator } = createCollaborator({ fieldGroupingProvider: 'senren' });
+
+  const merged = await collaborator.computeFieldGroupingMergedFields(
+    300,
+    200,
+    makeNote(300, {
+      miscInfo: 'leading<span class="group">middle</span>trailing',
+      sentenceAudio: '[sound:a.opus][sound:b.opus][sound:c.opus]',
+    }),
+    makeNote(200, {
+      miscInfo: '<span class="group">appended</span>',
+      sentenceAudio: '[sound:d.opus]',
+    }),
+    false,
+  );
+
+  // Order must follow the source field, and the two ungrouped runs must stay separate.
+  assert.equal(
+    merged.miscInfo,
+    '<span class="group">leading</span><span class="group">middle</span>' +
+      '<span class="group">trailing</span><span class="group4">appended</span>',
+  );
+  assert.equal(merged.sentenceAudio, '[sound:a.opus][sound:b.opus][sound:c.opus][sound:d.opus]');
+});
+
+test('Senren merge closes unclosed group spans so later scenes stay siblings', async () => {
+  const { collaborator } = createCollaborator({ fieldGroupingProvider: 'senren' });
+
+  const merged = await collaborator.computeFieldGroupingMergedFields(
+    300,
+    200,
+    makeNote(300, { miscInfo: '<span class="group">a<span class="highlight">b' }),
+    makeNote(200, { miscInfo: '<span class="group">next</span>' }),
+    false,
+  );
+
+  assert.equal(
+    merged.miscInfo,
+    '<span class="group">a<span class="highlight">b</span></span><span class="group">next</span>',
+  );
+  const openTags = merged.miscInfo!.match(/<span\b/g)?.length ?? 0;
+  const closeTags = merged.miscInfo!.match(/<\/span>/g)?.length ?? 0;
+  assert.equal(openTags, closeTags);
+});
+
+test('Senren merge closes unclosed trailing markup before appending later scenes', async () => {
+  const { collaborator } = createCollaborator({ fieldGroupingProvider: 'senren' });
+
+  const merged = await collaborator.computeFieldGroupingMergedFields(
+    300,
+    200,
+    makeNote(300, { miscInfo: 'leading<span class="highlight">tail' }),
+    makeNote(200, { miscInfo: '<span class="group">next</span>' }),
+    false,
+  );
+
+  assert.equal(
+    merged.miscInfo,
+    '<span class="group">leading<span class="highlight">tail</span></span>' +
+      '<span class="group">next</span>',
+  );
+});
+
+test('Kiku merge clears SentenceFurigana when either note lacks it', async () => {
   const { collaborator } = createCollaborator();
 
   const merged = await collaborator.computeFieldGroupingMergedFields(
@@ -268,3 +482,21 @@ test('computeFieldGroupingMergedFields clears SentenceFurigana when either note
 
   assert.equal(merged.SentenceFurigana, '');
 });
+
+test('Senren merge keeps duplicate SentenceFurigana when the kept field is empty', async () => {
+  const { collaborator } = createCollaborator({ fieldGroupingProvider: 'senren' });
+
+  const merged = await collaborator.computeFieldGroupingMergedFields(
+    300,
+    200,
+    makeNote(300, {
+      SentenceFurigana: '',
+    }),
+    makeNote(200, {
+      SentenceFurigana: 'duplicate furigana',
+    }),
+    false,
+  );
+
+  assert.equal(merged.SentenceFurigana, '<span class="group">duplicate furigana</span>');
+});
diff --git a/src/anki-integration/field-grouping-merge.ts b/src/anki-integration/field-grouping-merge.ts
index d7def9ef..00deef62 100644
--- a/src/anki-integration/field-grouping-merge.ts
+++ b/src/anki-integration/field-grouping-merge.ts
@@ -19,6 +19,7 @@ interface FieldGroupingMergeDeps {
   getEffectiveSentenceCardConfig: () => {
     sentenceField: string;
     audioField: string;
+    fieldGroupingProvider: 'kiku' | 'senren' | null;
   };
   getCurrentSubtitleText: () => string | undefined;
   resolveFieldName: (availableFieldNames: string[], preferredName: string) => string | null;
@@ -78,6 +79,13 @@ export class FieldGroupingMergeCollaborator {
     const configuredWordField = getConfiguredWordFieldName(config);
     const groupableFields = this.getGroupableFieldNames();
     const keepFieldNames = Object.keys(keepNoteInfo.fields);
+    const sentenceCardConfig = this.deps.getEffectiveSentenceCardConfig();
+    const senrenSourceSceneOffset =
+      sentenceCardConfig.fieldGroupingProvider === 'senren'
+        ? this.countSenrenAudioScenes(
+            this.getResolvedFieldValue(keepNoteInfo, sentenceCardConfig.audioField),
+          )
+        : 0;
     const sourceFields: Record<string, string> = {};
     const resolvedKeepFieldByPreferred = new Map<string, string>();
     for (const preferredFieldName of groupableFields) {
@@ -154,14 +162,18 @@ export class FieldGroupingMergeCollaborator {
       if (!existingValue.trim() && !newValue.trim()) continue;
 
       if (keepFieldNormalized === 'sentencefurigana') {
+        const hasBothValues = existingValue.trim().length > 0 && newValue.trim().length > 0;
+        const usesSenrenGrouping =
+          this.deps.getEffectiveSentenceCardConfig().fieldGroupingProvider === 'senren';
         mergedFields[keepFieldName] =
-          existingValue.trim() && newValue.trim()
+          hasBothValues || usesSenrenGrouping
             ? this.applyFieldGrouping(
                 existingValue,
                 newValue,
                 keepNoteId,
                 deleteNoteId,
                 keepFieldName,
+                senrenSourceSceneOffset,
               )
             : '';
         continue;
@@ -174,6 +186,7 @@ export class FieldGroupingMergeCollaborator {
           keepNoteId,
           deleteNoteId,
           keepFieldName,
+          senrenSourceSceneOffset,
         );
       } else if (existingValue.trim() && newValue.trim()) {
         mergedFields[keepFieldName] = this.applyFieldGrouping(
@@ -182,6 +195,7 @@ export class FieldGroupingMergeCollaborator {
           keepNoteId,
           deleteNoteId,
           keepFieldName,
+          senrenSourceSceneOffset,
         );
       } else {
         if (!newValue.trim()) continue;
@@ -342,13 +356,152 @@ export class FieldGroupingMergeCollaborator {
     return [...entries].sort((a, b) => b.groupId - a.groupId);
   }
 
+  private isSentenceAudioField(fieldName: string): boolean {
+    const normalized = fieldName.toLowerCase();
+    const audioField = (
+      this.deps.getEffectiveSentenceCardConfig().audioField || 'sentenceaudio'
+    ).toLowerCase();
+    return normalized === 'sentenceaudio' || normalized === audioField;
+  }
+
+  private isSenrenGroupOpenTag(openTag: string): boolean {
+    const classMatch =
+      openTag.match(/class\s*=\s*"([^"]*)"/i) || openTag.match(/class\s*=\s*'([^']*)'/i);
+    if (!classMatch) return false;
+    // Senren's templates match class tokens case-sensitively (/^group\d*$/).
+    return classMatch[1]!.split(/\s+/).some((token) => /^group\d*$/.test(token));
+  }
+
+  private countSenrenAudioScenes(value: string): number {
+    const soundEntries = value.match(/\[sound:[^\]]+\]/g)?.length ?? 0;
+    if (soundEntries > 0) return soundEntries;
+    return this.parseSenrenSceneEntries(value).length;
+  }
+
+  private rebaseSenrenGroup(entry: string, sceneOffset: number, sourceEntryIndex: number): string {
+    if (sceneOffset <= 0) return entry;
+
+    return entry.replace(
+      /^(\s*<span\b[^>]*?\bclass\s*=\s*)(["'])([^"']*)\2/i,
+      (_match: string, prefix: string, quote: string, rawClasses: string) => {
+        const classes = rawClasses
+          .split(/(\s+)/)
+          .map((classToken) => {
+            if (classToken === 'group') {
+              return `group${sceneOffset + sourceEntryIndex + 1}`;
+            }
+            const groupMatch = classToken.match(/^group(\d+)$/);
+            if (!groupMatch) return classToken;
+            const targetScene = Number(groupMatch[1]);
+            if (!Number.isSafeInteger(targetScene) || targetScene <= 0) return classToken;
+            return `group${targetScene + sceneOffset}`;
+          })
+          .join('');
+        return `${prefix}${quote}${classes}${quote}`;
+      },
+    );
+  }
+
+  /**
+   * Splits a Senren field into ordered scene entries. Top-level
+   * `<span class="group">`/`"groupN"` spans are kept verbatim (nested markup like
+   * `<span class="highlight">` included); ungrouped runs are wrapped in a group
+   * span at their original position, because Senren discards anything outside a
+   * group span once scene switching activates.
+   */
+  private parseSenrenSceneEntries(value: string): string[] {
+    const tokenRegex = /<span\b[^>]*>|<\/span>/gi;
+    const entries: string[] = [];
+    const pushUngrouped = (raw: string): void => {
+      const text = raw.replace(/<br\s*\/?>/gi, ' ').trim();
+      if (text) entries.push(`<span class="group">${text}</span>`);
+    };
+    let cursor = 0;
+    let depth = 0;
+    let entryStart = -1;
+    let match;
+    while ((match = tokenRegex.exec(value)) !== null) {
+      const token = match[0]!;
+      if (token[1] !== '/') {
+        if (depth === 0 && this.isSenrenGroupOpenTag(token)) {
+          pushUngrouped(value.slice(cursor, match.index));
+          entryStart = match.index;
+          cursor = match.index;
+        }
+        depth += 1;
+      } else {
+        depth = Math.max(0, depth - 1);
+        if (depth === 0 && entryStart !== -1) {
+          const end = match.index + token.length;
+          entries.push(value.slice(entryStart, end));
+          entryStart = -1;
+          cursor = end;
+        }
+      }
+    }
+    if (entryStart !== -1) {
+      // Unclosed group span: close every span still open (the group and any nested
+      // markup) so the following scenes are siblings rather than nested inside it.
+      entries.push(`${value.slice(entryStart)}${'</span>'.repeat(depth)}`);
+    } else {
+      pushUngrouped(`${value.slice(cursor)}${'</span>'.repeat(depth)}`);
+    }
+    return entries;
+  }
+
+  /**
+   * Merges two notes' field values in Senren's scene-switching format. Scenes are
+   * appended in order (existing first, never resorted) so indices stay aligned
+   * across sentence/picture/miscInfo with the sentenceAudio entries, which alone
+   * drive Senren's scene count.
+   */
+  private applySenrenFieldGrouping(
+    existingValue: string,
+    newValue: string,
+    fieldName: string,
+    sourceSceneOffset: number,
+  ): string {
+    if (this.isPictureField(fieldName)) {
+      const tags = [...this.extractImageTags(existingValue), ...this.extractImageTags(newValue)];
+      if (tags.length === 0) return existingValue || newValue;
+      return tags.join('');
+    }
+
+    if (this.isSentenceAudioField(fieldName)) {
+      const existing = existingValue.trim();
+      const added = newValue.trim();
+      if (added && !/\[sound:[^\]]+\]/.test(added)) {
+        this.deps.warnFieldParseOnce(fieldName, 'missing-sound-tag');
+      }
+      if (!existing || !added) return existing || added;
+      return existing + added;
+    }
+
+    const sourceEntries = this.parseSenrenSceneEntries(newValue).map((entry, sourceEntryIndex) =>
+      this.rebaseSenrenGroup(entry, sourceSceneOffset, sourceEntryIndex),
+    );
+    const merged = [...this.parseSenrenSceneEntries(existingValue), ...sourceEntries];
+    if (merged.length === 0) return existingValue || newValue;
+    return merged.join('');
+  }
+
   private applyFieldGrouping(
     existingValue: string,
     newValue: string,
     keepGroupId: number,
     sourceGroupId: number,
     fieldName: string,
+    senrenSourceSceneOffset: number,
   ): string {
+    if (this.deps.getEffectiveSentenceCardConfig().fieldGroupingProvider === 'senren') {
+      return this.applySenrenFieldGrouping(
+        existingValue,
+        newValue,
+        fieldName,
+        senrenSourceSceneOffset,
+      );
+    }
+
     if (this.shouldUseStrictSpanGrouping(fieldName)) {
       if (this.isPictureField(fieldName)) {
         const keepEntries = this.parsePictureEntries(existingValue, keepGroupId);
diff --git a/src/anki-integration/field-grouping-workflow.test.ts b/src/anki-integration/field-grouping-workflow.test.ts
index 71306374..a01f209c 100644
--- a/src/anki-integration/field-grouping-workflow.test.ts
+++ b/src/anki-integration/field-grouping-workflow.test.ts
@@ -71,7 +71,7 @@ function createWorkflowHarness() {
     getEffectiveSentenceCardConfig: () => ({
       sentenceField: 'Sentence',
       audioField: 'SentenceAudio',
-      kikuDeleteDuplicateInAuto: true,
+      fieldGroupingDeleteDuplicateInAuto: true,
     }),
     getCurrentSubtitleText: () => 'subtitle-text',
     getFieldGroupingCallback: (): FieldGroupingCallback | null => {
diff --git a/src/anki-integration/field-grouping-workflow.ts b/src/anki-integration/field-grouping-workflow.ts
index 6c3854f1..a0dfb669 100644
--- a/src/anki-integration/field-grouping-workflow.ts
+++ b/src/anki-integration/field-grouping-workflow.ts
@@ -24,7 +24,7 @@ export interface FieldGroupingWorkflowDeps {
   getEffectiveSentenceCardConfig: () => {
     sentenceField: string;
     audioField: string;
-    kikuDeleteDuplicateInAuto: boolean;
+    fieldGroupingDeleteDuplicateInAuto: boolean;
   };
   getCurrentSubtitleText: () => string | undefined;
   getFieldGroupingCallback:
@@ -75,7 +75,7 @@ export class FieldGroupingWorkflow {
         originalNoteId,
         newNoteId,
         this.getExpression(newNoteInfo),
-        sentenceCardConfig.kikuDeleteDuplicateInAuto,
+        sentenceCardConfig.fieldGroupingDeleteDuplicateInAuto,
       );
     } catch (error) {
       this.deps.logError('Field grouping auto merge failed:', (error as Error).message);
diff --git a/src/anki-integration/field-grouping.test.ts b/src/anki-integration/field-grouping.test.ts
index 5d44a600..2aa770ad 100644
--- a/src/anki-integration/field-grouping.test.ts
+++ b/src/anki-integration/field-grouping.test.ts
@@ -21,14 +21,14 @@ function createHarness(
     manualHandled?: boolean;
     expression?: string | null;
     currentSentenceImageField?: string | undefined;
-    onProcessNewCard?: (noteId: number, options?: { skipKikuFieldGrouping?: boolean }) => void;
+    onProcessNewCard?: (noteId: number, options?: { skipFieldGrouping?: boolean }) => void;
   } = {},
 ) {
   const calls: string[] = [];
   const findNotesQueries: Array<{ query: string; maxRetries?: number }> = [];
   const noteInfoRequests: number[][] = [];
   const duplicateRequests: Array<{ expression: string; excludeNoteId: number }> = [];
-  const processCalls: Array<{ noteId: number; options?: { skipKikuFieldGrouping?: boolean } }> = [];
+  const processCalls: Array<{ noteId: number; options?: { skipFieldGrouping?: boolean } }> = [];
   const autoCalls: Array<{ originalNoteId: number; newNoteId: number; expression: string }> = [];
   const manualCalls: Array<{ originalNoteId: number; newNoteId: number; expression: string }> = [];
 
@@ -46,9 +46,8 @@ function createHarness(
       sentenceField: 'Sentence',
       audioField: 'SentenceAudio',
       lapisEnabled: false,
-      kikuEnabled: options.kikuEnabled ?? true,
-      kikuFieldGrouping: options.kikuFieldGrouping ?? 'auto',
-      kikuDeleteDuplicateInAuto: true,
+      fieldGroupingProvider: (options.kikuEnabled ?? true) ? ('kiku' as const) : null,
+      fieldGroupingMode: options.kikuFieldGrouping ?? 'auto',
     }),
     isUpdateInProgress: () => false,
     getDeck: options.deck ? () => options.deck : undefined,
@@ -134,7 +133,7 @@ test('triggerFieldGroupingForLastAddedCard stops when kiku mode is disabled', as
 
   await harness.service.triggerFieldGroupingForLastAddedCard();
 
-  assert.deepEqual(harness.calls, ['osd:Kiku mode is not enabled']);
+  assert.deepEqual(harness.calls, ['osd:Field grouping requires Kiku or Senren mode']);
   assert.equal(harness.findNotesQueries.length, 0);
 });
 
@@ -143,7 +142,7 @@ test('triggerFieldGroupingForLastAddedCard stops when field grouping is disabled
 
   await harness.service.triggerFieldGroupingForLastAddedCard();
 
-  assert.deepEqual(harness.calls, ['osd:Kiku field grouping is disabled']);
+  assert.deepEqual(harness.calls, ['osd:Field grouping is disabled']);
   assert.equal(harness.findNotesQueries.length, 0);
 });
 
@@ -155,9 +154,8 @@ test('triggerFieldGroupingForLastAddedCard stops when an update is already in pr
       sentenceField: 'Sentence',
       audioField: 'SentenceAudio',
       lapisEnabled: false,
-      kikuEnabled: true,
-      kikuFieldGrouping: 'auto',
-      kikuDeleteDuplicateInAuto: true,
+      fieldGroupingProvider: 'kiku' as const,
+      fieldGroupingMode: 'auto' as const,
     }),
     isUpdateInProgress: () => true,
     withUpdateProgress: async () => {
@@ -266,7 +264,7 @@ test('triggerFieldGroupingForLastAddedCard prefers tracked duplicate note ids be
 });
 
 test('triggerFieldGroupingForLastAddedCard refreshes the card when configured fields are missing', async () => {
-  const processCalls: Array<{ noteId: number; options?: { skipKikuFieldGrouping?: boolean } }> = [];
+  const processCalls: Array<{ noteId: number; options?: { skipFieldGrouping?: boolean } }> = [];
   const harness = createHarness({
     noteIds: [11],
     notesInfo: [
@@ -298,7 +296,7 @@ test('triggerFieldGroupingForLastAddedCard refreshes the card when configured fi
 
   await harness.service.triggerFieldGroupingForLastAddedCard();
 
-  assert.deepEqual(processCalls, [{ noteId: 11, options: { skipKikuFieldGrouping: true } }]);
+  assert.deepEqual(processCalls, [{ noteId: 11, options: { skipFieldGrouping: true } }]);
   assert.deepEqual(harness.manualCalls, []);
 });
 
@@ -352,9 +350,8 @@ test('buildFieldGroupingPreview returns merged compact and full previews', async
       sentenceField: 'Sentence',
       audioField: 'SentenceAudio',
       lapisEnabled: false,
-      kikuEnabled: true,
-      kikuFieldGrouping: 'auto',
-      kikuDeleteDuplicateInAuto: true,
+      fieldGroupingProvider: 'kiku' as const,
+      fieldGroupingMode: 'auto' as const,
     }),
     isUpdateInProgress: () => false,
     withUpdateProgress: async (_message, action) => action(),
@@ -417,9 +414,8 @@ test('buildFieldGroupingPreview reports missing notes cleanly', async () => {
       sentenceField: 'Sentence',
       audioField: 'SentenceAudio',
       lapisEnabled: false,
-      kikuEnabled: true,
-      kikuFieldGrouping: 'auto',
-      kikuDeleteDuplicateInAuto: true,
+      fieldGroupingProvider: 'kiku' as const,
+      fieldGroupingMode: 'auto' as const,
     }),
     isUpdateInProgress: () => false,
     withUpdateProgress: async (_message, action) => action(),
diff --git a/src/anki-integration/field-grouping.ts b/src/anki-integration/field-grouping.ts
index b6acb57b..ba491aa2 100644
--- a/src/anki-integration/field-grouping.ts
+++ b/src/anki-integration/field-grouping.ts
@@ -20,9 +20,8 @@ interface FieldGroupingDeps {
     sentenceField: string;
     audioField: string;
     lapisEnabled: boolean;
-    kikuEnabled: boolean;
-    kikuFieldGrouping: 'auto' | 'manual' | 'disabled';
-    kikuDeleteDuplicateInAuto: boolean;
+    fieldGroupingProvider: 'kiku' | 'senren' | null;
+    fieldGroupingMode: 'auto' | 'manual' | 'disabled';
   };
   isUpdateInProgress: () => boolean;
   getDeck?: () => string | undefined;
@@ -46,7 +45,7 @@ interface FieldGroupingDeps {
     noteInfo: FieldGroupingNoteInfo,
     configuredFieldNames: (string | undefined)[],
   ) => boolean;
-  processNewCard: (noteId: number, options?: { skipKikuFieldGrouping?: boolean }) => Promise<void>;
+  processNewCard: (noteId: number, options?: { skipFieldGrouping?: boolean }) => Promise<void>;
   getSentenceCardImageFieldName: () => string | undefined;
   resolveFieldName: (availableFieldNames: string[], preferredName: string) => string | null;
   computeFieldGroupingMergedFields: (
@@ -76,12 +75,12 @@ export class FieldGroupingService {
 
   async triggerFieldGroupingForLastAddedCard(): Promise<void> {
     const sentenceCardConfig = this.deps.getEffectiveSentenceCardConfig();
-    if (!sentenceCardConfig.kikuEnabled) {
-      this.deps.showOsdNotification('Kiku mode is not enabled');
+    if (sentenceCardConfig.fieldGroupingProvider === null) {
+      this.deps.showOsdNotification('Field grouping requires Kiku or Senren mode');
       return;
     }
-    if (sentenceCardConfig.kikuFieldGrouping === 'disabled') {
-      this.deps.showOsdNotification('Kiku field grouping is disabled');
+    if (sentenceCardConfig.fieldGroupingMode === 'disabled') {
+      this.deps.showOsdNotification('Field grouping is disabled');
       return;
     }
 
@@ -134,7 +133,7 @@ export class FieldGroupingService {
           ])
         ) {
           await this.deps.processNewCard(noteId, {
-            skipKikuFieldGrouping: true,
+            skipFieldGrouping: true,
           });
         }
 
@@ -147,7 +146,7 @@ export class FieldGroupingService {
 
         const noteInfo = refreshedInfo[0]!;
 
-        if (sentenceCardConfig.kikuFieldGrouping === 'auto') {
+        if (sentenceCardConfig.fieldGroupingMode === 'auto') {
           await this.deps.handleFieldGroupingAuto(
             duplicateNoteId,
             noteId,
diff --git a/src/anki-integration/known-word-cache.test.ts b/src/anki-integration/known-word-cache.test.ts
index 3d54036b..306fdba8 100644
--- a/src/anki-integration/known-word-cache.test.ts
+++ b/src/anki-integration/known-word-cache.test.ts
@@ -261,6 +261,32 @@ test('KnownWordCacheManager invalidates persisted cache when fields.word changes
   }
 });
 
+test('KnownWordCacheManager removes a deleted note from memory and persisted state', () => {
+  const config: AnkiConnectConfig = {
+    fields: { word: 'Word' },
+    knownWords: { highlightEnabled: true },
+  };
+  const { manager, statePath, cleanup } = createKnownWordCacheHarness(config);
+
+  try {
+    manager.appendFromNoteInfo({
+      noteId: 42,
+      fields: { Word: { value: '猫' } },
+    });
+
+    assert.equal(manager.removeNote(42), true);
+    assert.equal(manager.removeNote(42), false);
+    assert.equal(manager.isKnownWord('猫'), false);
+
+    const persisted = JSON.parse(fs.readFileSync(statePath, 'utf-8')) as {
+      notes?: Record<string, unknown>;
+    };
+    assert.deepEqual(persisted.notes, {});
+  } finally {
+    cleanup();
+  }
+});
+
 test('KnownWordCacheManager refresh incrementally reconciles deleted and edited note words', async () => {
   const config: AnkiConnectConfig = {
     fields: {
diff --git a/src/anki-integration/known-word-cache.ts b/src/anki-integration/known-word-cache.ts
index f1fc16b7..436d3d71 100644
--- a/src/anki-integration/known-word-cache.ts
+++ b/src/anki-integration/known-word-cache.ts
@@ -350,6 +350,17 @@ export class KnownWordCacheManager {
     return true;
   }
 
+  removeNote(noteId: number): boolean {
+    if (!this.noteEntriesById.has(noteId)) {
+      return false;
+    }
+
+    this.removeNoteSnapshot(noteId);
+    this.persistKnownWordCacheState();
+    log.info('Known-word cache removed deleted note', `noteId=${noteId}`);
+    return true;
+  }
+
   clearKnownWordCacheState(): void {
     this.clearInMemoryState();
     this.knownWordsStateKey = this.getKnownWordCacheStateKey();
diff --git a/src/anki-integration/media-duration.ts b/src/anki-integration/media-duration.ts
new file mode 100644
index 00000000..04f937d4
--- /dev/null
+++ b/src/anki-integration/media-duration.ts
@@ -0,0 +1,10 @@
+/** Zero or a negative cap leaves the requested end time unchanged. */
+export function clampMediaEndTime(
+  startTime: number,
+  endTime: number,
+  maxMediaDuration: number,
+): number {
+  return maxMediaDuration > 0 && endTime - startTime > maxMediaDuration
+    ? startTime + maxMediaDuration
+    : endTime;
+}
diff --git a/src/anki-integration/media-source.test.ts b/src/anki-integration/media-source.test.ts
index a3c49871..92a6792d 100644
--- a/src/anki-integration/media-source.test.ts
+++ b/src/anki-integration/media-source.test.ts
@@ -213,6 +213,30 @@ test('resolveMediaGenerationInput reads file-local mpv request options', async (
   });
 });
 
+test('resolveMediaGenerationInput keeps stream selection for a directly played remote container', async () => {
+  const resolver = (
+    mediaSource as typeof mediaSource & {
+      resolveMediaGenerationInput?: StructuredMediaResolver;
+    }
+  ).resolveMediaGenerationInput;
+  assert.equal(typeof resolver, 'function');
+
+  // Jellyfin direct play: mpv opens the URL as-is, so it can hold several audio streams.
+  const jellyfinUrl = 'http://jellyfin.local:8096/Videos/abc/stream?static=true';
+  const result = await resolver!(
+    {
+      currentVideoPath: jellyfinUrl,
+      requestProperty: async (name: string) =>
+        name === 'stream-open-filename' ? jellyfinUrl : null,
+    },
+    'audio',
+  );
+
+  assert.equal(result?.path, jellyfinUrl);
+  assert.equal(result?.source, 'stream-open-filename');
+  assert.equal(result?.singleResolvedStream, false);
+});
+
 test('resolveMediaGenerationInput prefers a ready cached media file for YouTube extraction', async () => {
   const resolver = (
     mediaSource as typeof mediaSource & {
diff --git a/src/anki-integration/media-source.ts b/src/anki-integration/media-source.ts
index 8f511bc9..0bb650d2 100644
--- a/src/anki-integration/media-source.ts
+++ b/src/anki-integration/media-source.ts
@@ -400,12 +400,15 @@ export async function resolveMediaGenerationInput(
       return result;
     }
     if (streamOpenFilename) {
+      // A URL that yt-dlp resolved (e.g. youtube.com -> googlevideo) is one picked stream.
+      // When mpv opens the path as-is (e.g. Jellyfin direct play), it is the full container,
+      // so mpv's audio stream index still applies.
       const result = await toResolvedMediaGenerationInput(
         mpvClient,
         streamOpenFilename,
         kind,
         'stream-open-filename',
-        isRemoteMediaPath(streamOpenFilename),
+        isRemoteMediaPath(streamOpenFilename) && streamOpenFilename !== currentVideoPath,
       );
       logResolvedMediaGenerationInput(options, currentVideoPath, result);
       return result;
diff --git a/src/anki-integration/note-update-workflow.test.ts b/src/anki-integration/note-update-workflow.test.ts
index 2138b538..d1dcb188 100644
--- a/src/anki-integration/note-update-workflow.test.ts
+++ b/src/anki-integration/note-update-workflow.test.ts
@@ -44,6 +44,7 @@ function createWorkflowHarness() {
         updates.push({ noteId, fields });
       },
       storeMediaFile: async () => undefined,
+      deleteNotes: async () => undefined,
     },
     getConfig: () => ({
       fields: {
@@ -58,9 +59,10 @@ function createWorkflowHarness() {
       sentenceField: 'Sentence',
       lapisEnabled: false,
       kikuEnabled: false,
-      kikuFieldGrouping: 'disabled' as const,
+      fieldGroupingMode: 'disabled' as const,
     }),
     appendKnownWordsFromNoteInfo: (_noteInfo: NoteUpdateWorkflowNoteInfo) => undefined,
+    removeKnownWordNote: (_noteId: number) => undefined,
     extractFields: (fields: Record<string, { value: string }>) => {
       const out: Record<string, string> = {};
       for (const [key, value] of Object.entries(fields)) {
@@ -80,7 +82,6 @@ function createWorkflowHarness() {
       const names = Object.keys(noteInfo.fields);
       return names.find((name) => name.toLowerCase() === preferred.toLowerCase()) ?? null;
     },
-    getResolvedSentenceAudioFieldName: () => null,
     getAnimatedImageLeadInSeconds: async () => 0,
     mergeFieldValue: (_existing: string, next: string, _overwrite: boolean) => next,
     generateAudioFilename: () => 'audio_1.mp3',
@@ -120,15 +121,59 @@ test('NoteUpdateWorkflow updates sentence field and emits notification', async (
   assert.equal(harness.notifications.length, 1);
 });
 
+test('NoteUpdateWorkflow uses configured fields for word-card enrichment with Lapis and Kiku enabled', async () => {
+  const harness = createWorkflowHarness();
+  harness.deps.getConfig = () => ({
+    fields: {
+      sentence: 'Context',
+      audio: 'ContextAudio',
+    },
+    media: {
+      generateAudio: true,
+      generateImage: false,
+    },
+    behavior: {},
+  });
+  harness.deps.getEffectiveSentenceCardConfig = () => ({
+    sentenceField: 'Sentence',
+    lapisEnabled: true,
+    kikuEnabled: true,
+    fieldGroupingMode: 'disabled',
+  });
+  harness.deps.client.notesInfo = async () =>
+    [
+      {
+        noteId: 42,
+        fields: {
+          Expression: { value: 'taberu' },
+          Sentence: { value: '' },
+          SentenceAudio: { value: '' },
+          Context: { value: '' },
+          ContextAudio: { value: '' },
+        },
+      },
+    ] satisfies NoteUpdateWorkflowNoteInfo[];
+  harness.deps.generateAudio = async () => Buffer.from('audio');
+
+  await harness.workflow.execute(42);
+
+  assert.equal(harness.updates.length, 1);
+  assert.deepEqual(harness.updates[0]?.fields, {
+    Context: 'subtitle-text',
+    ContextAudio: '[sound:audio_1.mp3]',
+  });
+});
+
 test('NoteUpdateWorkflow updates sentence furigana when highlight processor changes it', async () => {
   const harness = createWorkflowHarness();
+  harness.deps.getCurrentSubtitleText = () => 'tokugi';
   harness.deps.client.notesInfo = async () =>
     [
       {
         noteId: 42,
         fields: {
           Expression: { value: 'tokugi' },
-          Sentence: { value: '' },
+          Sentence: { value: 'tokugi' },
           SentenceFurigana: { value: '<span class="term">tokugi</span>' },
         },
       },
@@ -140,7 +185,7 @@ test('NoteUpdateWorkflow updates sentence furigana when highlight processor chan
 
   assert.equal(harness.updates.length, 1);
   assert.deepEqual(harness.updates[0]?.fields, {
-    Sentence: 'subtitle-text',
+    Sentence: 'tokugi',
     SentenceFurigana: '<span class="term"><b>tokugi</b></span>',
   });
 });
@@ -151,7 +196,7 @@ test('NoteUpdateWorkflow marks enriched Kiku word cards as word-and-sentence car
     sentenceField: 'Sentence',
     lapisEnabled: false,
     kikuEnabled: true,
-    kikuFieldGrouping: 'manual',
+    fieldGroupingMode: 'manual',
   });
   harness.deps.client.notesInfo = async () =>
     [
@@ -184,7 +229,7 @@ test('NoteUpdateWorkflow marks the configured word card kind instead of word-and
     sentenceField: 'Sentence',
     lapisEnabled: false,
     kikuEnabled: true,
-    kikuFieldGrouping: 'manual',
+    fieldGroupingMode: 'manual',
     wordCardKind: 'click',
   });
   harness.deps.client.notesInfo = async () =>
@@ -220,7 +265,7 @@ test('NoteUpdateWorkflow leaves card type flags alone when the word card kind is
     sentenceField: 'Sentence',
     lapisEnabled: false,
     kikuEnabled: true,
-    kikuFieldGrouping: 'manual',
+    fieldGroupingMode: 'manual',
     wordCardKind: 'none',
   });
   harness.deps.client.notesInfo = async () =>
@@ -275,7 +320,7 @@ test('NoteUpdateWorkflow preserves explicit sentence card type during sentence e
     sentenceField: 'Sentence',
     lapisEnabled: true,
     kikuEnabled: false,
-    kikuFieldGrouping: 'disabled',
+    fieldGroupingMode: 'disabled',
   });
   harness.deps.client.notesInfo = async () =>
     [
@@ -318,7 +363,7 @@ test('NoteUpdateWorkflow updates note before auto field grouping merge', async (
     sentenceField: 'Sentence',
     lapisEnabled: false,
     kikuEnabled: true,
-    kikuFieldGrouping: 'auto',
+    fieldGroupingMode: 'auto',
   });
   harness.deps.findDuplicateNote = async () => 99;
   harness.deps.client.notesInfo = async () => {
@@ -432,6 +477,7 @@ test('NoteUpdateWorkflow uses subtitle sidebar context for sentence media timing
   harness.deps.getConfig = () => ({
     fields: {
       sentence: 'Sentence',
+      audio: 'SentenceAudio',
       image: 'Picture',
       miscInfo: 'MiscInfo',
     },
@@ -444,7 +490,6 @@ test('NoteUpdateWorkflow uses subtitle sidebar context for sentence media timing
   });
   harness.deps.getCurrentSubtitleText = () => 'current primary line';
   harness.deps.getCurrentSubtitleStart = () => 20;
-  harness.deps.getResolvedSentenceAudioFieldName = () => 'SentenceAudio';
   harness.deps.generateAudio = async (context?: SubtitleMiningContext) => {
     audioContext = context ?? null;
     return Buffer.from('audio');
@@ -501,6 +546,7 @@ test('NoteUpdateWorkflow snapshots one media range for audio and image without a
   harness.deps.getConfig = () => ({
     fields: {
       sentence: 'Sentence',
+      audio: 'SentenceAudio',
       image: 'Picture',
       miscInfo: 'MiscInfo',
     },
@@ -511,7 +557,6 @@ test('NoteUpdateWorkflow snapshots one media range for audio and image without a
     },
     behavior: {},
   });
-  harness.deps.getResolvedSentenceAudioFieldName = () => 'SentenceAudio';
   harness.deps.captureSubtitleMediaContext = () => {
     captureCalls += 1;
     return capturedContext;
@@ -592,3 +637,203 @@ test('NoteUpdateWorkflow queues media updates when YouTube cache is pending', as
   assert.equal(queuedUpdates[0]?.context, undefined);
   assert.deepEqual(harness.updates, [{ noteId: 42, fields: { Sentence: 'subtitle-text' } }]);
 });
+
+test('NoteUpdateWorkflow deletes an existing word card when timing review discards it', async () => {
+  const harness = createWorkflowHarness();
+  const deletedNoteIds: number[][] = [];
+  const removedKnownWordNoteIds: number[] = [];
+  let appendedKnownWords = false;
+  harness.deps.captureSubtitleMediaContext = () => ({
+    source: 'overlay',
+    text: 'subtitle-text',
+    startTime: 4,
+    endTime: 6,
+  });
+  harness.deps.client.deleteNotes = async (noteIds) => {
+    deletedNoteIds.push(noteIds);
+  };
+  harness.deps.appendKnownWordsFromNoteInfo = () => {
+    appendedKnownWords = true;
+  };
+  harness.deps.removeKnownWordNote = (noteId) => {
+    removedKnownWordNoteIds.push(noteId);
+  };
+  harness.deps.reviewMediaTiming = async () => ({ action: 'discard' });
+
+  await harness.workflow.execute(42);
+
+  assert.deepEqual(deletedNoteIds, [[42]]);
+  assert.deepEqual(removedKnownWordNoteIds, [42]);
+  assert.equal(appendedKnownWords, false);
+  assert.deepEqual(harness.updates, []);
+  assert.deepEqual(harness.notifications, []);
+});
+
+test('NoteUpdateWorkflow keeps the word card but skips media after timing review', async () => {
+  const harness = createWorkflowHarness();
+  const mediaCalls: string[] = [];
+  const deletedNoteIds: number[][] = [];
+  const queuedUpdates: unknown[] = [];
+  harness.deps.captureSubtitleMediaContext = () => ({
+    source: 'overlay',
+    text: 'subtitle-text',
+    startTime: 4,
+    endTime: 6,
+  });
+  harness.deps.getConfig = () => ({
+    fields: { sentence: 'Sentence', image: 'Picture' },
+    media: { generateAudio: true, generateImage: true },
+    behavior: {},
+  });
+  harness.deps.reviewMediaTiming = async () => ({ action: 'skip-media' });
+  harness.deps.generateAudio = async () => {
+    mediaCalls.push('audio');
+    return Buffer.from('audio');
+  };
+  harness.deps.generateImage = async () => {
+    mediaCalls.push('image');
+    return Buffer.from('image');
+  };
+  harness.deps.queuePendingYoutubeMediaUpdate = async (update) => {
+    queuedUpdates.push(update);
+    return true;
+  };
+  harness.deps.client.deleteNotes = async (noteIds) => {
+    deletedNoteIds.push(noteIds);
+  };
+
+  await harness.workflow.execute(42);
+
+  assert.deepEqual(mediaCalls, []);
+  assert.deepEqual(queuedUpdates, []);
+  assert.deepEqual(deletedNoteIds, []);
+  assert.deepEqual(harness.updates, [{ noteId: 42, fields: { Sentence: 'subtitle-text' } }]);
+  assert.deepEqual(harness.notifications, [{ noteId: 42, label: 'taberu' }]);
+});
+
+test('NoteUpdateWorkflow uses the combined review sentence for the card and media range', async () => {
+  const harness = createWorkflowHarness();
+  const audioContexts: Array<SubtitleMiningContext | undefined> = [];
+  harness.deps.captureSubtitleMediaContext = () => ({
+    source: 'overlay',
+    text: 'current-line',
+    startTime: 4,
+    endTime: 6,
+  });
+  harness.deps.getConfig = () => ({
+    fields: { sentence: 'Sentence' },
+    media: { generateAudio: true, generateImage: false },
+    behavior: {},
+  });
+  harness.deps.reviewMediaTiming = async () => ({
+    action: 'confirm',
+    startTime: 2,
+    endTime: 7,
+    text: 'previous-line current-line next-line',
+    screenshotTime: 8,
+  });
+  harness.deps.generateAudio = async (context) => {
+    audioContexts.push(context);
+    return null;
+  };
+
+  await harness.workflow.execute(42);
+
+  assert.deepEqual(harness.updates, [
+    { noteId: 42, fields: { Sentence: 'previous-line current-line next-line' } },
+  ]);
+  assert.equal(audioContexts.length, 1);
+  assert.equal(audioContexts[0]?.text, 'previous-line current-line next-line');
+  assert.equal(audioContexts[0]?.startTime, 2);
+  assert.equal(audioContexts[0]?.endTime, 7);
+  assert.equal(audioContexts[0]?.mediaPaddingSeconds, 0);
+  assert.equal(audioContexts[0]?.screenshotTime, 8);
+});
+
+test('NoteUpdateWorkflow keeps cache unchanged and reports when deletion fails', async () => {
+  const harness = createWorkflowHarness();
+  const statusMessages: string[] = [];
+  let removedKnownWord = false;
+  harness.deps.captureSubtitleMediaContext = () => ({
+    source: 'overlay',
+    text: 'subtitle-text',
+    startTime: 4,
+    endTime: 6,
+  });
+  harness.deps.client.deleteNotes = async () => {
+    throw new Error('delete failed');
+  };
+  harness.deps.removeKnownWordNote = () => {
+    removedKnownWord = true;
+  };
+  harness.deps.showOsdNotification = (message) => {
+    statusMessages.push(message);
+  };
+  harness.deps.reviewMediaTiming = async () => ({ action: 'discard' });
+
+  await harness.workflow.execute(42);
+
+  assert.equal(removedKnownWord, false);
+  assert.deepEqual(statusMessages, ['Card deletion failed: delete failed']);
+  assert.ok(harness.warnings.length === 0);
+});
+
+for (const outcome of ['success', 'unavailable', 'throws'] as const) {
+  test(`NoteUpdateWorkflow regenerates expanded furigana (${outcome})`, async () => {
+    const harness = createWorkflowHarness();
+    harness.deps.client.notesInfo = async () => [
+      {
+        noteId: 42,
+        fields: {
+          Expression: { value: '猫' },
+          Sentence: { value: '<b>猫</b>を見た。' },
+          SentenceFurigana: { value: ' 猫[ねこ]を 見[み]た。' },
+        },
+      },
+    ];
+    harness.deps.captureSubtitleMediaContext = () => ({
+      source: 'overlay',
+      text: '猫を見た。',
+      startTime: 4,
+      endTime: 6,
+    });
+    harness.deps.reviewMediaTiming = async () => ({
+      action: 'confirm',
+      text: '猫を見た。犬もいた。',
+      startTime: 2,
+      endTime: 8,
+    });
+    harness.deps.generateSentenceFurigana = async (text, fields) => {
+      assert.equal(text, '猫を見た。犬もいた。');
+      assert.equal(fields.expression, '猫');
+      if (outcome === 'throws') throw new Error('parser unavailable');
+      return outcome === 'success' ? '<b> 猫[ねこ]</b>を 見[み]た。 犬[いぬ]もいた。' : null;
+    };
+    await harness.workflow.execute(42);
+    assert.equal(harness.updates[0]?.fields.Sentence, '猫を見た。犬もいた。');
+    assert.equal(
+      harness.updates[0]?.fields.SentenceFurigana,
+      outcome === 'success' ? '<b> 猫[ねこ]</b>を 見[み]た。 犬[いぬ]もいた。' : '',
+    );
+  });
+}
+
+test('NoteUpdateWorkflow preserves native furigana formatting when sentence context is unchanged', async () => {
+  const harness = createWorkflowHarness();
+  harness.deps.client.notesInfo = async () => [
+    {
+      noteId: 42,
+      fields: {
+        Expression: { value: '猫' },
+        Sentence: { value: '<b>猫</b>を見た。' },
+        SentenceFurigana: { value: '<ruby>猫<rt>ねこ</rt></ruby>を見た。' },
+      },
+    },
+  ];
+  harness.deps.getCurrentSubtitleText = () => '猫を見た。';
+  harness.deps.generateSentenceFurigana = async () => {
+    assert.fail('unchanged sentence must keep native formatting');
+  };
+  await harness.workflow.execute(42);
+  assert.equal(harness.updates[0]?.fields.SentenceFurigana, undefined);
+});
diff --git a/src/anki-integration/note-update-workflow.ts b/src/anki-integration/note-update-workflow.ts
index 0348bdeb..ccb560c8 100644
--- a/src/anki-integration/note-update-workflow.ts
+++ b/src/anki-integration/note-update-workflow.ts
@@ -1,7 +1,12 @@
 import { DEFAULT_ANKI_CONNECT_CONFIG } from '../config';
 import { getPreferredWordValueFromExtractedFields } from '../anki-field-config';
 import type { SubtitleMiningContext } from '../types/subtitle';
-import type { CardKind, WordCardKind } from '../types/anki';
+import type {
+  CardKind,
+  MediaTimingReviewDecision,
+  MediaTimingReviewRequest,
+  WordCardKind,
+} from '../types/anki';
 import { resolveWordCardKind } from './note-field-utils';
 
 export interface NoteUpdateWorkflowNoteInfo {
@@ -14,11 +19,13 @@ export interface NoteUpdateWorkflowDeps {
     notesInfo(noteIds: number[]): Promise<unknown>;
     updateNoteFields(noteId: number, fields: Record<string, string>): Promise<void>;
     storeMediaFile(filename: string, data: Buffer): Promise<void>;
+    deleteNotes(noteIds: number[]): Promise<void>;
   };
   getConfig: () => {
     fields?: {
       word?: string;
       sentence?: string;
+      audio?: string;
       image?: string;
       miscInfo?: string;
     };
@@ -39,10 +46,11 @@ export interface NoteUpdateWorkflowDeps {
     sentenceField: string;
     lapisEnabled: boolean;
     kikuEnabled: boolean;
-    kikuFieldGrouping: 'auto' | 'manual' | 'disabled';
+    fieldGroupingMode: 'auto' | 'manual' | 'disabled';
     wordCardKind?: WordCardKind;
   };
   appendKnownWordsFromNoteInfo: (noteInfo: NoteUpdateWorkflowNoteInfo) => void;
+  removeKnownWordNote: (noteId: number) => void;
   extractFields: (fields: Record<string, { value: string }>) => Record<string, string>;
   findDuplicateNote: (
     expression: string,
@@ -66,6 +74,10 @@ export interface NoteUpdateWorkflowDeps {
     sentenceFurigana: string,
     noteFields: Record<string, string>,
   ) => string;
+  generateSentenceFurigana?: (
+    text: string,
+    noteFields: Record<string, string>,
+  ) => Promise<string | null>;
   setCardTypeFields: (
     updatedFields: Record<string, string>,
     availableFieldNames: string[],
@@ -75,7 +87,6 @@ export interface NoteUpdateWorkflowDeps {
     noteInfo: NoteUpdateWorkflowNoteInfo,
     ...preferredNames: (string | undefined)[]
   ) => string | null;
-  getResolvedSentenceAudioFieldName: (noteInfo: NoteUpdateWorkflowNoteInfo) => string | null;
   getAnimatedImageLeadInSeconds: (noteInfo: NoteUpdateWorkflowNoteInfo) => Promise<number>;
   mergeFieldValue: (existing: string, newValue: string, overwrite: boolean) => string;
   generateAudioFilename: () => string;
@@ -102,6 +113,9 @@ export interface NoteUpdateWorkflowDeps {
   logWarn: (message: string, ...args: unknown[]) => void;
   logInfo: (message: string, ...args: unknown[]) => void;
   logError: (message: string, ...args: unknown[]) => void;
+  reviewMediaTiming?: (
+    request: Omit<MediaTimingReviewRequest, 'audioPadding' | 'maxMediaDuration'>,
+  ) => Promise<MediaTimingReviewDecision>;
 }
 
 function normalizeSubtitleContextText(text: string): string {
@@ -160,7 +174,7 @@ export class NoteUpdateWorkflow {
     return null;
   }
 
-  async execute(noteId: number, options?: { skipKikuFieldGrouping?: boolean }): Promise<void> {
+  async execute(noteId: number, options?: { skipFieldGrouping?: boolean }): Promise<void> {
     this.deps.beginUpdateProgress('Updating card');
     try {
       const notesInfoResult = await this.deps.client.notesInfo([noteId]);
@@ -171,7 +185,6 @@ export class NoteUpdateWorkflow {
       }
 
       const noteInfo = notesInfo[0]!;
-      this.deps.appendKnownWordsFromNoteInfo(noteInfo);
       const fields = this.deps.extractFields(noteInfo.fields);
       const config = this.deps.getConfig();
 
@@ -187,9 +200,7 @@ export class NoteUpdateWorkflow {
 
       const sentenceCardConfig = this.deps.getEffectiveSentenceCardConfig();
       const shouldRunFieldGrouping =
-        !options?.skipKikuFieldGrouping &&
-        sentenceCardConfig.kikuEnabled &&
-        sentenceCardConfig.kikuFieldGrouping !== 'disabled';
+        !options?.skipFieldGrouping && sentenceCardConfig.fieldGroupingMode !== 'disabled';
       let duplicateNoteId: number | null = null;
       if (shouldRunFieldGrouping && hasExpressionText) {
         duplicateNoteId = await this.deps.findDuplicateNote(expressionText, noteId, noteInfo);
@@ -198,20 +209,67 @@ export class NoteUpdateWorkflow {
       const updatedFields: Record<string, string> = {};
       let updatePerformed = false;
       let miscInfoFilename: string | null = null;
-      const sentenceField = sentenceCardConfig.sentenceField;
+      const configuredSentenceField =
+        config.fields?.sentence ?? DEFAULT_ANKI_CONNECT_CONFIG.fields.sentence;
+      const sentenceField = this.deps.resolveConfiguredFieldName(noteInfo, configuredSentenceField);
       const subtitleMiningContext = this.consumeMatchingSubtitleMiningContext(
         fields,
-        sentenceField,
-        config.fields?.sentence,
+        sentenceField ?? configuredSentenceField,
+        configuredSentenceField,
       );
       // Audio and image generation run sequentially and audio extraction can take tens of
       // seconds, so resolve the clip range exactly once up front; reading live mpv sub
       // timings per generator clips whichever line is on screen when each one starts.
-      const mediaTimingContext =
+      let mediaTimingContext =
         subtitleMiningContext ?? this.deps.captureSubtitleMediaContext?.() ?? null;
+      let skipMedia = false;
+      let reviewedSentenceText: string | undefined;
       const noteLabel = hasExpressionText ? expressionText : noteId;
 
-      const currentSubtitleText = subtitleMiningContext?.text ?? this.deps.getCurrentSubtitleText();
+      if (mediaTimingContext) {
+        const timingDecision = this.deps.reviewMediaTiming
+          ? await this.deps.reviewMediaTiming({
+              kind: 'word',
+              text: mediaTimingContext.text,
+              startTime: mediaTimingContext.startTime,
+              endTime: mediaTimingContext.endTime,
+              noteId,
+            })
+          : ({ action: 'use-original' } as const);
+        if (timingDecision.action === 'discard') {
+          try {
+            await this.deps.client.deleteNotes([noteId]);
+          } catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            this.deps.logError('Failed to delete discarded card:', message);
+            this.deps.showOsdNotification(`Card deletion failed: ${message}`);
+            return;
+          }
+          this.deps.removeKnownWordNote(noteId);
+          this.deps.showOsdNotification('Card deleted.');
+          return;
+        }
+        if (timingDecision.action === 'confirm') {
+          reviewedSentenceText = timingDecision.text?.trim() || undefined;
+          mediaTimingContext = {
+            ...mediaTimingContext,
+            ...(reviewedSentenceText !== undefined ? { text: reviewedSentenceText } : {}),
+            startTime: timingDecision.startTime,
+            endTime: timingDecision.endTime,
+            mediaPaddingSeconds: 0,
+            ...(timingDecision.screenshotTime !== undefined
+              ? { screenshotTime: timingDecision.screenshotTime }
+              : {}),
+          };
+        } else if (timingDecision.action === 'skip-media') {
+          skipMedia = true;
+        }
+      }
+
+      this.deps.appendKnownWordsFromNoteInfo(noteInfo);
+
+      const currentSubtitleText =
+        reviewedSentenceText ?? subtitleMiningContext?.text ?? this.deps.getCurrentSubtitleText();
       if (sentenceField && currentSubtitleText) {
         const processedSentence = this.deps.processSentence(currentSubtitleText, fields);
         updatedFields[sentenceField] = processedSentence;
@@ -228,7 +286,27 @@ export class NoteUpdateWorkflow {
       const existingSentenceFurigana = sentenceFuriganaField
         ? noteInfo.fields[sentenceFuriganaField]?.value || ''
         : '';
-      if (sentenceFuriganaField && existingSentenceFurigana && this.deps.processSentenceFurigana) {
+      const sentenceChanged =
+        sentenceField &&
+        currentSubtitleText &&
+        normalizeSubtitleContextText(currentSubtitleText) !==
+          normalizeSubtitleContextText(noteInfo.fields[sentenceField]?.value ?? '');
+      if (sentenceFuriganaField && sentenceChanged) {
+        let furigana: string | null = null;
+        try {
+          furigana =
+            (await this.deps.generateSentenceFurigana?.(currentSubtitleText, fields)) ?? null;
+        } catch (error) {
+          this.deps.logWarn('Failed to regenerate sentence furigana:', error);
+        }
+        // Empty furigana lets card templates fall back to the updated Sentence field.
+        updatedFields[sentenceFuriganaField] = furigana ?? '';
+        updatePerformed = true;
+      } else if (
+        sentenceFuriganaField &&
+        existingSentenceFurigana &&
+        this.deps.processSentenceFurigana
+      ) {
         const processedSentenceFurigana = this.deps.processSentenceFurigana(
           existingSentenceFurigana,
           fields,
@@ -239,8 +317,8 @@ export class NoteUpdateWorkflow {
         }
       }
 
-      const generateAudio = config.media?.generateAudio !== false;
-      const generateImage = config.media?.generateImage !== false;
+      const generateAudio = !skipMedia && config.media?.generateAudio !== false;
+      const generateImage = !skipMedia && config.media?.generateImage !== false;
       const mediaCacheQueued =
         (generateAudio || generateImage) && this.deps.queuePendingYoutubeMediaUpdate
           ? await this.deps.queuePendingYoutubeMediaUpdate({
@@ -258,7 +336,10 @@ export class NoteUpdateWorkflow {
 
           if (audioBuffer) {
             await this.deps.client.storeMediaFile(audioFilename, audioBuffer);
-            const sentenceAudioField = this.deps.getResolvedSentenceAudioFieldName(noteInfo);
+            const sentenceAudioField = this.deps.resolveConfiguredFieldName(
+              noteInfo,
+              config.fields?.audio ?? DEFAULT_ANKI_CONNECT_CONFIG.fields.audio,
+            );
             if (sentenceAudioField) {
               const existingAudio = noteInfo.fields[sentenceAudioField]?.value || '';
               updatedFields[sentenceAudioField] = this.deps.mergeFieldValue(
@@ -345,7 +426,7 @@ export class NoteUpdateWorkflow {
           noteInfoForGrouping = refreshedInfo[0]!;
         }
 
-        if (sentenceCardConfig.kikuFieldGrouping === 'auto') {
+        if (sentenceCardConfig.fieldGroupingMode === 'auto') {
           await this.deps.handleFieldGroupingAuto(
             duplicateNoteId,
             noteId,
@@ -354,7 +435,7 @@ export class NoteUpdateWorkflow {
           );
           return;
         }
-        if (sentenceCardConfig.kikuFieldGrouping === 'manual') {
+        if (sentenceCardConfig.fieldGroupingMode === 'manual') {
           await this.deps.handleFieldGroupingManual(
             duplicateNoteId,
             noteId,
diff --git a/src/anki-integration/pending-youtube-media-queue.test.ts b/src/anki-integration/pending-youtube-media-queue.test.ts
index cff5c693..4c347063 100644
--- a/src/anki-integration/pending-youtube-media-queue.test.ts
+++ b/src/anki-integration/pending-youtube-media-queue.test.ts
@@ -31,7 +31,6 @@ function createDeps(
     getCachedMediaPath: async () => null,
     shouldRequireRemoteMediaCache: () => true,
     getSubtitleMediaRange: () => ({ startTime: 1, endTime: 2 }),
-    getResolvedSentenceAudioFieldName: () => 'SentenceAudio',
     resolveConfiguredFieldName: () => 'Picture',
     mergeFieldValue: (_existing, newValue) => newValue,
     getAnimatedImageLeadInSeconds: async () => 0,
@@ -52,6 +51,41 @@ function createDeps(
   return deps;
 }
 
+test('queued media keeps a chosen screenshot separate from the reviewed audio range', async () => {
+  const screenshots: number[] = [];
+  const audioRanges: number[][] = [];
+  const deps = createDeps();
+  deps.client.notesInfo = async () => [{ noteId: 42, fields: { Picture: { value: '' } } }];
+  deps.mediaGenerator.generateScreenshot = async (_media, time) => {
+    screenshots.push(time);
+    return Buffer.from('image');
+  };
+  deps.mediaGenerator.generateAudio = async (_media, start, end, padding) => {
+    audioRanges.push([start, end, padding ?? -1]);
+    return Buffer.from('audio');
+  };
+  const queue = new PendingYoutubeMediaQueue(deps);
+  assert.equal(
+    await queue.queueFromNote({
+      noteId: 42,
+      noteInfo: { noteId: 42, fields: {} },
+      label: 'test',
+      context: {
+        source: 'overlay',
+        text: '字幕',
+        startTime: 1,
+        endTime: 2,
+        mediaPaddingSeconds: 0,
+        screenshotTime: 3.125,
+      },
+    }),
+    true,
+  );
+  await queue.handleReady('https://youtu.be/abc123', '/cache/video.mkv');
+  assert.deepEqual(screenshots, [3.125]);
+  assert.deepEqual(audioRanges, [[1, 2, 0]]);
+});
+
 test('PendingYoutubeMediaQueue treats cache lookup failures as an immediate generation fallback', async () => {
   const deps = createDeps({
     getCachedMediaPath: async () => {
@@ -133,7 +167,7 @@ test('PendingYoutubeMediaQueue defaults missing media flags to enabled when queu
         noteIds.map((noteId) => ({
           noteId,
           fields: {
-            SentenceAudio: { value: '' },
+            ExpressionAudio: { value: '' },
             Picture: { value: '' },
           },
         })),
@@ -144,13 +178,16 @@ test('PendingYoutubeMediaQueue defaults missing media flags to enabled when queu
         storedMedia.push(filename);
       },
     },
-    getConfig: () => ({ media: {}, fields: { image: 'Picture' } }) as AnkiConnectConfig,
+    getConfig: () =>
+      ({ media: {}, fields: { audio: 'ExpressionAudio', image: 'Picture' } }) as AnkiConnectConfig,
+    resolveConfiguredFieldName: (noteInfo, ...preferredNames) =>
+      preferredNames.find((name) => name && name in noteInfo.fields) ?? null,
   });
   const queue = new PendingYoutubeMediaQueue(deps);
 
   const queued = await queue.queueFromNote({
     noteId: 42,
-    noteInfo: { noteId: 42, fields: {} },
+    noteInfo: { noteId: 42, fields: { ExpressionAudio: { value: '' } } },
     label: 'demo',
   });
   await queue.handleReady('https://youtu.be/abc123', '/tmp/media.mkv');
@@ -158,7 +195,8 @@ test('PendingYoutubeMediaQueue defaults missing media flags to enabled when queu
   assert.equal(queued, true);
   assert.equal(updatedNotes.length, 1);
   assert.equal(storedMedia.length, 2);
-  assert.match(updatedNotes[0]?.fields.SentenceAudio ?? '', /^\[sound:audio\.mp3\]$/);
+  assert.match(updatedNotes[0]?.fields.ExpressionAudio ?? '', /^\[sound:audio\.mp3\]$/);
+  assert.equal('SentenceAudio' in (updatedNotes[0]?.fields ?? {}), false);
   assert.match(updatedNotes[0]?.fields.Picture ?? '', /^<img src="image\.webp">$/);
 });
 
diff --git a/src/anki-integration/pending-youtube-media-queue.ts b/src/anki-integration/pending-youtube-media-queue.ts
index 68abd2c9..59802c6d 100644
--- a/src/anki-integration/pending-youtube-media-queue.ts
+++ b/src/anki-integration/pending-youtube-media-queue.ts
@@ -39,7 +39,6 @@ export interface PendingYoutubeMediaQueueDeps {
     startTime: number;
     endTime: number;
   };
-  getResolvedSentenceAudioFieldName: (noteInfo: PendingYoutubeMediaNoteInfo) => string | null;
   resolveConfiguredFieldName: (
     noteInfo: PendingYoutubeMediaNoteInfo,
     ...preferredNames: (string | undefined)[]
@@ -136,7 +135,7 @@ export class PendingYoutubeMediaQueue {
       startTime: mediaRange.startTime,
       endTime: mediaRange.endTime,
       label: job.label,
-      audioFieldName: this.deps.getResolvedSentenceAudioFieldName(job.noteInfo) ?? undefined,
+      audioFieldName: this.resolveConfiguredAudioFieldName(job.noteInfo) ?? undefined,
       imageFieldName:
         this.deps.resolveConfiguredFieldName(
           job.noteInfo,
@@ -148,6 +147,12 @@ export class PendingYoutubeMediaQueue {
       generateAudio: shouldGenerateAudio(config),
       generateImage: shouldGenerateImage(config),
       volumeScale,
+      ...(job.context?.screenshotTime !== undefined
+        ? { screenshotTime: job.context.screenshotTime }
+        : {}),
+      ...(job.context?.mediaPaddingSeconds !== undefined
+        ? { mediaPaddingSeconds: job.context.mediaPaddingSeconds }
+        : {}),
     });
     return true;
   }
@@ -247,6 +252,14 @@ export class PendingYoutubeMediaQueue {
     return matched;
   }
 
+  private resolveConfiguredAudioFieldName(noteInfo: PendingYoutubeMediaNoteInfo): string | null {
+    const config = this.deps.getConfig();
+    return this.deps.resolveConfiguredFieldName(
+      noteInfo,
+      config.fields?.audio ?? DEFAULT_ANKI_CONNECT_CONFIG.fields.audio,
+    );
+  }
+
   private async applyUpdate(
     job: PendingYoutubeMediaUpdate,
     cachedPath: string,
@@ -275,7 +288,7 @@ export class PendingYoutubeMediaQueue {
           cachedMediaInput,
           job.startTime,
           job.endTime,
-          config.media?.audioPadding,
+          job.mediaPaddingSeconds ?? config.media?.audioPadding,
           undefined,
           config.media?.normalizeAudio !== false,
           job.volumeScale,
@@ -283,7 +296,7 @@ export class PendingYoutubeMediaQueue {
         if (audioBuffer) {
           await this.deps.client.storeMediaFile(audioFilename, audioBuffer);
           const audioField =
-            job.audioFieldName || this.deps.getResolvedSentenceAudioFieldName(noteInfo) || null;
+            job.audioFieldName || this.resolveConfiguredAudioFieldName(noteInfo) || null;
           if (audioField) {
             const existingAudio = noteInfo.fields[audioField]?.value || '';
             mediaFields[audioField] = this.deps.mergeFieldValue(
@@ -309,6 +322,8 @@ export class PendingYoutubeMediaQueue {
           job.startTime,
           job.endTime,
           animatedLeadInSeconds,
+          job.mediaPaddingSeconds,
+          job.screenshotTime,
         );
         if (imageBuffer) {
           await this.deps.client.storeMediaFile(imageFilename, imageBuffer);
@@ -369,6 +384,8 @@ export class PendingYoutubeMediaQueue {
     startTime: number,
     endTime: number,
     animatedLeadInSeconds = 0,
+    mediaPaddingSeconds?: number,
+    screenshotTime?: number,
   ): Promise<Buffer | null> {
     const config = this.deps.getConfig();
     if (config.media?.imageType === 'avif') {
@@ -376,7 +393,7 @@ export class PendingYoutubeMediaQueue {
         videoPath,
         startTime,
         endTime,
-        config.media?.audioPadding,
+        mediaPaddingSeconds ?? config.media?.audioPadding,
         {
           fps: config.media?.animatedFps,
           maxWidth: config.media?.animatedMaxWidth,
@@ -387,7 +404,7 @@ export class PendingYoutubeMediaQueue {
       );
     }
 
-    const timestamp = startTime + (endTime - startTime) / 2;
+    const timestamp = screenshotTime ?? startTime + (endTime - startTime) / 2;
     return this.deps.mediaGenerator.generateScreenshot(videoPath, timestamp, {
       format: config.media?.imageFormat as 'jpg' | 'png' | 'webp',
       quality: config.media?.imageQuality,
diff --git a/src/anki-integration/pending-youtube-media.ts b/src/anki-integration/pending-youtube-media.ts
index 52d65af8..dec424bf 100644
--- a/src/anki-integration/pending-youtube-media.ts
+++ b/src/anki-integration/pending-youtube-media.ts
@@ -10,6 +10,8 @@ export interface PendingYoutubeMediaUpdate {
   generateAudio: boolean;
   generateImage: boolean;
   volumeScale?: number;
+  mediaPaddingSeconds?: number;
+  screenshotTime?: number;
 }
 
 function trimToNonEmptyString(value: unknown): string | null {
diff --git a/src/anki-integration/runtime.ts b/src/anki-integration/runtime.ts
index 83be62e8..d00d9b48 100644
--- a/src/anki-integration/runtime.ts
+++ b/src/anki-integration/runtime.ts
@@ -116,6 +116,10 @@ export function normalizeAnkiIntegrationConfig(config: AnkiConnectConfig): AnkiC
       ...DEFAULT_ANKI_CONNECT_CONFIG.isKiku,
       ...(config.isKiku ?? {}),
     },
+    isSenren: {
+      ...DEFAULT_ANKI_CONNECT_CONFIG.isSenren,
+      ...(config.isSenren ?? {}),
+    },
     lapisKiku: {
       ...DEFAULT_ANKI_CONNECT_CONFIG.lapisKiku,
       ...(config.lapisKiku ?? {}),
@@ -209,6 +213,10 @@ export class AnkiIntegrationRuntime {
         patch.isKiku !== undefined
           ? { ...this.config.isKiku, ...patch.isKiku }
           : this.config.isKiku,
+      isSenren:
+        patch.isSenren !== undefined
+          ? { ...this.config.isSenren, ...patch.isSenren }
+          : this.config.isSenren,
       lapisKiku:
         patch.lapisKiku !== undefined
           ? { ...this.config.lapisKiku, ...patch.lapisKiku }
diff --git a/src/anki-integration/sentence-furigana.test.ts b/src/anki-integration/sentence-furigana.test.ts
new file mode 100644
index 00000000..7654c0c9
--- /dev/null
+++ b/src/anki-integration/sentence-furigana.test.ts
@@ -0,0 +1,80 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { formatSentenceFurigana } from './sentence-furigana';
+
+const parsed = [
+  {
+    source: 'scanning-parser',
+    content: [
+      [{ text: '猫', reading: 'ねこ' }],
+      [{ text: 'を' }],
+      [{ text: '見', reading: 'み' }, { text: 'た' }],
+      [{ text: '。\n' }],
+      [{ text: '犬', reading: 'いぬ' }],
+      [{ text: 'もいた。' }],
+    ],
+  },
+];
+
+test('formats the complete expanded sentence with readings and the mined word highlighted', () => {
+  assert.equal(
+    formatSentenceFurigana('猫を見た。\n犬もいた。', parsed, '猫'),
+    '<b> 猫[ねこ]</b>を 見[み]た。\n 犬[いぬ]もいた。',
+  );
+});
+
+test('rejects headword-only and malformed parse results instead of saving partial furigana', () => {
+  assert.equal(
+    formatSentenceFurigana('猫を見た。', [
+      { source: 'scanning-parser', content: [[{ text: '猫', reading: 'ねこ' }]] },
+    ]),
+    null,
+  );
+  assert.equal(
+    formatSentenceFurigana('猫', [
+      { source: 'scanning-parser', content: [[{ text: '猫', reading: 42 }]] },
+    ]),
+    null,
+  );
+});
+
+test('escapes literal markup and annotation delimiters and leaves kana unannotated', () => {
+  const text = '<猫> [メモ]';
+  assert.equal(
+    formatSentenceFurigana(text, [
+      {
+        source: 'scanning-parser',
+        content: [
+          [{ text: '<' }],
+          [{ text: '猫', reading: 'ねこ' }],
+          [{ text: '> [' }],
+          [{ text: 'メモ', reading: 'めも' }],
+          [{ text: ']' }],
+        ],
+      },
+    ]),
+    '&lt; 猫[ねこ]&gt; &#91;メモ&#93;',
+  );
+});
+
+test('highlights the mined word without bolding the rest of a dictionary phrase', () => {
+  assert.equal(
+    formatSentenceFurigana(
+      '行儀を直して',
+      [
+        {
+          content: [
+            [
+              { text: '行儀', reading: 'ぎょうぎ' },
+              { text: 'を' },
+              { text: '直', reading: 'なお' },
+              { text: 'して' },
+            ],
+          ],
+        },
+      ],
+      '行儀',
+    ),
+    '<b> 行儀[ぎょうぎ]</b>を 直[なお]して',
+  );
+});
diff --git a/src/anki-integration/sentence-furigana.ts b/src/anki-integration/sentence-furigana.ts
new file mode 100644
index 00000000..e707c606
--- /dev/null
+++ b/src/anki-integration/sentence-furigana.ts
@@ -0,0 +1,87 @@
+type Segment = { text: string; reading?: string };
+
+function readGroups(value: unknown): Segment[][] | null {
+  if (!Array.isArray(value)) return null;
+  const groups: Segment[][] = [];
+  const rawGroups: unknown[] = value;
+  for (const group of rawGroups) {
+    if (!Array.isArray(group)) return null;
+    const segments: Segment[] = [];
+    const rawSegments: unknown[] = group;
+    for (const segment of rawSegments) {
+      if (
+        typeof segment !== 'object' ||
+        segment === null ||
+        !('text' in segment) ||
+        typeof segment.text !== 'string' ||
+        ('reading' in segment &&
+          segment.reading !== undefined &&
+          typeof segment.reading !== 'string')
+      )
+        return null;
+      segments.push({
+        text: segment.text,
+        reading:
+          'reading' in segment && typeof segment.reading === 'string' ? segment.reading : undefined,
+      });
+    }
+    groups.push(segments);
+  }
+  return groups;
+}
+
+function escapeText(text: string): string {
+  return text
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/\[/g, '&#91;')
+    .replace(/\]/g, '&#93;');
+}
+
+// Only accept a complete parse, so a lookup of just the headword cannot replace sentence context.
+export function formatSentenceFurigana(
+  text: string,
+  results: unknown[] | null,
+  highlightedText?: string,
+): string | null {
+  for (const result of results ?? []) {
+    if (typeof result !== 'object' || result === null || !('content' in result)) continue;
+    const groups = readGroups(result.content);
+    if (
+      !groups ||
+      groups
+        .flat()
+        .map((segment) => segment.text)
+        .join('') !== text
+    )
+      continue;
+    const highlights: number[] = [];
+    if (highlightedText) {
+      let start = text.indexOf(highlightedText);
+      while (start >= 0) {
+        highlights.push(start);
+        start = text.indexOf(highlightedText, start + highlightedText.length);
+      }
+    }
+    let offset = 0;
+    let bold = false;
+    let output = '';
+    for (const { text: surface, reading } of groups.flat()) {
+      const start = offset;
+      offset += surface.length;
+      const highlighted = highlights.some(
+        (position) => position < offset && position + (highlightedText?.length ?? 0) > start,
+      );
+      if (highlighted !== bold) output += highlighted ? '<b>' : '</b>';
+      bold = highlighted;
+      const escaped = escapeText(surface);
+      output +=
+        reading && reading !== surface && /[\p{Script=Han}々]/u.test(surface)
+          ? ` ${escaped}[${escapeText(reading)}]`
+          : escaped;
+    }
+    return output + (bold ? '</b>' : '');
+  }
+  return null;
+}
diff --git a/src/ci-workflow.test.ts b/src/ci-workflow.test.ts
index 800d53c4..db4895c1 100644
--- a/src/ci-workflow.test.ts
+++ b/src/ci-workflow.test.ts
@@ -19,6 +19,23 @@ test('package scripts expose a sharded maintained source coverage lane with lcov
   );
 });
 
+test('source and coverage scripts discover the same maintained source lane', () => {
+  const sourceLane = packageJson.scripts['test:src']?.match(/run-test-lane\.mjs\s+([^\s]+)/)?.[1];
+  const coverageLane = packageJson.scripts['test:coverage:src']?.match(
+    /run-coverage-lane\.ts\s+([^\s]+)/,
+  )?.[1];
+
+  assert.equal(sourceLane, 'bun-src-full');
+  assert.equal(coverageLane, sourceLane);
+});
+
+test('environment suite owns launcher smoke execution', () => {
+  assert.match(
+    packageJson.scripts['test:env'] ?? '',
+    /^bun run test:launcher:smoke:src && bun run test:plugin:src && bun run test:immersion:sqlite:src$/,
+  );
+});
+
 test('ci delegates its gate instead of duplicating quality steps', () => {
   assert.match(
     ciWorkflow,
@@ -36,15 +53,17 @@ test('main docs deploy exists, serializes deploys, and uses Cloudflare credentia
   assert.match(docsPagesWorkflow, /CLOUDFLARE_API_TOKEN/);
   assert.match(docsPagesWorkflow, /CLOUDFLARE_ACCOUNT_ID/);
   assert.match(docsPagesWorkflow, /CLOUDFLARE_PAGES_PROJECT_NAME/);
-  assert.match(docsPagesWorkflow, /pages deploy \.tmp\/docs-versioned-site/);
+  assert.match(docsPagesWorkflow, /pages deploy \.\.\/\.tmp\/docs-versioned-site/);
   assert.match(docsPagesWorkflow, /--branch main/);
 });
 
-test('docs deploy caches stable archive builds between runs', () => {
-  assert.match(docsPagesWorkflow, /actions\/cache@v4/);
-  assert.match(docsPagesWorkflow, /\.tmp\/docs-versioned-archive-cache/);
-  assert.match(docsPagesWorkflow, /docs-versioned-archives-/);
-  assert.match(docsPagesWorkflow, /docs-site\/\.vitepress\/\*\*/);
+test('docs deploy syncs frozen archives to R2 and ships the archive Pages Function', () => {
+  assert.doesNotMatch(docsPagesWorkflow, /actions\/cache@/);
+  assert.match(docsPagesWorkflow, /DOCS_ARCHIVE_R2_ACCESS_KEY_ID/);
+  assert.match(docsPagesWorkflow, /DOCS_ARCHIVE_R2_SECRET_ACCESS_KEY/);
+  assert.match(docsPagesWorkflow, /--require-archives/);
+  assert.match(docsPagesWorkflow, /--rebuild-archives=\$\{REBUILD_ARCHIVES\}/);
+  assert.match(docsPagesWorkflow, /workingDirectory: docs-site/);
 });
 
 test('docs deploy skips invalid release tags without failing the workflow', () => {
diff --git a/src/config/config.test.ts b/src/config/config.test.ts
index 423cef29..45090419 100644
--- a/src/config/config.test.ts
+++ b/src/config/config.test.ts
@@ -2181,6 +2181,7 @@ test('runtime options registry is centralized', () => {
   const ids = RUNTIME_OPTION_REGISTRY.map((entry) => entry.id);
   assert.deepEqual(ids, [
     'anki.autoUpdateNewCards',
+    'anki.mediaReviewTiming',
     'subtitle.annotation.knownWords.highlightEnabled',
     'subtitle.annotation.knownWords.maturityEnabled',
     'subtitle.annotation.nPlusOne',
@@ -2188,6 +2189,7 @@ test('runtime options registry is centralized', () => {
     'subtitle.annotation.frequency',
     'anki.nPlusOneMatchMode',
     'anki.kikuFieldGrouping',
+    'anki.senrenFieldGrouping',
   ]);
 });
 
@@ -2775,6 +2777,70 @@ test('accepts a Kiku/Lapis word card kind and warns on an unknown one', () => {
   );
 });
 
+test('forces Senren off when Kiku is also enabled and validates Senren fieldGrouping', () => {
+  const dir = makeTempDir();
+  fs.writeFileSync(
+    path.join(dir, 'config.jsonc'),
+    `{
+      "ankiConnect": {
+        "isKiku": { "enabled": true },
+        "isSenren": { "enabled": true }
+      }
+    }`,
+    'utf-8',
+  );
+
+  const service = new ConfigService(dir);
+  assert.equal(service.getConfig().ankiConnect.isKiku.enabled, true);
+  assert.equal(service.getConfig().ankiConnect.isSenren.enabled, false);
+  assert.ok(
+    service.getWarnings().some((warning) => warning.path === 'ankiConnect.isSenren.enabled'),
+  );
+
+  const senrenOnlyDir = makeTempDir();
+  fs.writeFileSync(
+    path.join(senrenOnlyDir, 'config.jsonc'),
+    `{
+      "ankiConnect": {
+        "isSenren": { "enabled": true, "fieldGrouping": "sometimes" }
+      }
+    }`,
+    'utf-8',
+  );
+
+  const senrenOnlyService = new ConfigService(senrenOnlyDir);
+  assert.equal(senrenOnlyService.getConfig().ankiConnect.isSenren.enabled, true);
+  assert.equal(senrenOnlyService.getConfig().ankiConnect.isSenren.fieldGrouping, 'auto');
+  assert.ok(
+    senrenOnlyService
+      .getWarnings()
+      .some((warning) => warning.path === 'ankiConnect.isSenren.fieldGrouping'),
+  );
+});
+
+test('warns and falls back when isSenren.enabled is not boolean', () => {
+  const dir = makeTempDir();
+  fs.writeFileSync(
+    path.join(dir, 'config.jsonc'),
+    `{
+      "ankiConnect": {
+        "isSenren": { "enabled": "true" }
+      }
+    }`,
+    'utf-8',
+  );
+
+  const service = new ConfigService(dir);
+
+  assert.equal(
+    service.getConfig().ankiConnect.isSenren.enabled,
+    DEFAULT_CONFIG.ankiConnect.isSenren.enabled,
+  );
+  assert.ok(
+    service.getWarnings().some((warning) => warning.path === 'ankiConnect.isSenren.enabled'),
+  );
+});
+
 test('accepts valid ankiConnect knownWords deck object', () => {
   const dir = makeTempDir();
   fs.writeFileSync(
diff --git a/src/config/definitions.ts b/src/config/definitions.ts
index 0cdfc924..32f8250f 100644
--- a/src/config/definitions.ts
+++ b/src/config/definitions.ts
@@ -1,4 +1,5 @@
 import { RawConfig, ResolvedConfig } from '../types/config';
+import { DEFAULT_SUBTITLE_GENERATION_CONFIG } from '../shared/subtitle-generation';
 import { CORE_DEFAULT_CONFIG } from './definitions/defaults-core';
 import { IMMERSION_DEFAULT_CONFIG } from './definitions/defaults-immersion';
 import { INTEGRATIONS_DEFAULT_CONFIG } from './definitions/defaults-integrations';
@@ -41,6 +42,7 @@ const {
   ankiConnect,
   jimaku,
   tsukihime,
+  tmdb,
   anilist,
   mpv,
   yomitan,
@@ -54,6 +56,8 @@ const { immersionTracking } = IMMERSION_DEFAULT_CONFIG;
 const { stats } = STATS_DEFAULT_CONFIG;
 
 export const DEFAULT_CONFIG: ResolvedConfig = {
+  subtitleSelection: { enabled: false },
+  subtitleGeneration: { ...DEFAULT_SUBTITLE_GENERATION_CONFIG },
   subtitlePosition,
   keybindings,
   websocket,
@@ -74,6 +78,7 @@ export const DEFAULT_CONFIG: ResolvedConfig = {
   auto_start_overlay,
   jimaku,
   tsukihime,
+  tmdb,
   anilist,
   mpv,
   yomitan,
diff --git a/src/config/definitions/defaults-core.ts b/src/config/definitions/defaults-core.ts
index 7d61e884..270d5e74 100644
--- a/src/config/definitions/defaults-core.ts
+++ b/src/config/definitions/defaults-core.ts
@@ -99,6 +99,8 @@ export const CORE_DEFAULT_CONFIG: Pick<
     openRuntimeOptions: 'CommandOrControl+Shift+O',
     openJimaku: 'Ctrl+Shift+J',
     openTsukihime: 'Ctrl+Shift+T',
+    openSubtitleSelection: 'g-s',
+    openSubtitleGeneration: 'Ctrl+Shift+G',
     openSessionHelp: 'CommandOrControl+Slash',
     openControllerSelect: 'Alt+C',
     openControllerDebug: 'Alt+Shift+C',
diff --git a/src/config/definitions/defaults-integrations.ts b/src/config/definitions/defaults-integrations.ts
index 788564be..69e2b90b 100644
--- a/src/config/definitions/defaults-integrations.ts
+++ b/src/config/definitions/defaults-integrations.ts
@@ -6,6 +6,7 @@ export const INTEGRATIONS_DEFAULT_CONFIG: Pick<
   | 'ankiConnect'
   | 'jimaku'
   | 'tsukihime'
+  | 'tmdb'
   | 'anilist'
   | 'mpv'
   | 'yomitan'
@@ -29,6 +30,7 @@ export const INTEGRATIONS_DEFAULT_CONFIG: Pick<
     fields: {
       word: 'Expression',
       audio: 'ExpressionAudio',
+      wordAudio: 'ExpressionAudio',
       image: 'Picture',
       sentence: 'Sentence',
       miscInfo: 'MiscInfo',
@@ -54,6 +56,7 @@ export const INTEGRATIONS_DEFAULT_CONFIG: Pick<
       syncAnimatedImageToWordAudio: true,
       normalizeAudio: true,
       mirrorMpvVolume: true,
+      reviewTiming: false,
       audioPadding: 0,
       fallbackDuration: 3.0,
       maxMediaDuration: 30,
@@ -91,6 +94,11 @@ export const INTEGRATIONS_DEFAULT_CONFIG: Pick<
       fieldGrouping: 'disabled',
       deleteDuplicateInAuto: true,
     },
+    isSenren: {
+      enabled: false,
+      fieldGrouping: 'auto',
+      deleteDuplicateInAuto: true,
+    },
     lapisKiku: {
       wordCardKind: 'word-and-sentence',
     },
@@ -106,6 +114,10 @@ export const INTEGRATIONS_DEFAULT_CONFIG: Pick<
     apiBaseUrl: 'https://api.tsukihime.org/v1',
     maxSearchResults: 10,
   },
+  tmdb: {
+    apiKey: '',
+    apiKeyCommand: '',
+  },
   mpv: {
     executablePath: '',
     launchMode: 'normal',
diff --git a/src/config/definitions/options-core.ts b/src/config/definitions/options-core.ts
index 46cd7399..09b03755 100644
--- a/src/config/definitions/options-core.ts
+++ b/src/config/definitions/options-core.ts
@@ -628,6 +628,19 @@ export function buildCoreConfigOptionRegistry(
       defaultValue: defaultConfig.shortcuts.openSessionHelp,
       description: 'Accelerator that opens the session help / keybinding cheatsheet.',
     },
+    {
+      path: 'shortcuts.openSubtitleSelection',
+      kind: 'string',
+      defaultValue: defaultConfig.shortcuts.openSubtitleSelection,
+      description:
+        'Open subtitle selection when enabled. Use g-s to press g then s. Set null to unbind.',
+    },
+    {
+      path: 'shortcuts.openSubtitleGeneration',
+      kind: 'string',
+      defaultValue: defaultConfig.shortcuts.openSubtitleGeneration,
+      description: 'Accelerator that opens the standalone Japanese subtitle generation modal.',
+    },
     {
       path: 'shortcuts.openControllerSelect',
       kind: 'string',
diff --git a/src/config/definitions/options-integrations.ts b/src/config/definitions/options-integrations.ts
index 9f8c3e32..68545d92 100644
--- a/src/config/definitions/options-integrations.ts
+++ b/src/config/definitions/options-integrations.ts
@@ -82,6 +82,13 @@ export function buildIntegrationConfigOptionRegistry(
       defaultValue: defaultConfig.ankiConnect.fields.audio,
       description: 'Card field that receives generated sentence audio.',
     },
+    {
+      path: 'ankiConnect.fields.wordAudio',
+      kind: 'string',
+      defaultValue: defaultConfig.ankiConnect.fields.wordAudio,
+      description:
+        'Existing word-audio field read to time the frozen first frame of animated images. This mapping is only used for synchronization.',
+    },
     {
       path: 'ankiConnect.fields.image',
       kind: 'string',
@@ -196,6 +203,14 @@ export function buildIntegrationConfigOptionRegistry(
       description:
         "Apply mpv's current software volume curve to generated sentence audio. Changes apply live.",
     },
+    {
+      path: 'ankiConnect.media.reviewTiming',
+      kind: 'boolean',
+      defaultValue: defaultConfig.ankiConnect.media.reviewTiming,
+      description:
+        'Review and preview subtitle media timing before SubMiner creates or enriches a mined card.',
+      runtime: runtimeOptionById.get('anki.mediaReviewTiming'),
+    },
     {
       path: 'ankiConnect.media.generateImage',
       kind: 'boolean',
@@ -280,7 +295,7 @@ export function buildIntegrationConfigOptionRegistry(
       path: 'ankiConnect.media.maxMediaDuration',
       kind: 'number',
       defaultValue: defaultConfig.ankiConnect.media.maxMediaDuration,
-      description: 'Maximum allowed media clip duration in seconds.',
+      description: 'Maximum allowed media clip duration in seconds. 0 disables the cap.',
     },
     {
       path: 'ankiConnect.knownWords.matchMode',
@@ -363,6 +378,28 @@ export function buildIntegrationConfigOptionRegistry(
       description:
         'When Kiku field grouping is "auto", delete the duplicate source card after grouping completes.',
     },
+    {
+      path: 'ankiConnect.isSenren.fieldGrouping',
+      kind: 'enum',
+      enumValues: ['auto', 'manual', 'disabled'],
+      defaultValue: defaultConfig.ankiConnect.isSenren.fieldGrouping,
+      description: 'Senren duplicate-card field grouping mode (scene switching).',
+      runtime: runtimeOptionById.get('anki.senrenFieldGrouping'),
+    },
+    {
+      path: 'ankiConnect.isSenren.enabled',
+      kind: 'boolean',
+      defaultValue: defaultConfig.ankiConnect.isSenren.enabled,
+      description:
+        'Enable Senren-specific duplicate handling (scene-switching field grouping, including miscInfo grouping). Mutually exclusive with isKiku.enabled.',
+    },
+    {
+      path: 'ankiConnect.isSenren.deleteDuplicateInAuto',
+      kind: 'boolean',
+      defaultValue: defaultConfig.ankiConnect.isSenren.deleteDuplicateInAuto,
+      description:
+        'When Senren field grouping is "auto", delete the duplicate source card after grouping completes.',
+    },
     {
       path: 'ankiConnect.isLapis.enabled',
       kind: 'boolean',
@@ -442,6 +479,20 @@ export function buildIntegrationConfigOptionRegistry(
       defaultValue: defaultConfig.tsukihime.maxSearchResults,
       description: 'Maximum TsukiHime search results returned.',
     },
+    {
+      path: 'tmdb.apiKey',
+      kind: 'string',
+      defaultValue: defaultConfig.tmdb.apiKey,
+      description:
+        'Your own TMDB API key or read access token for live-action posters and synopses in the stats Library. Release builds bundle a project key, so set this only to use your own quota or when running from source (free under Settings > API on themoviedb.org).',
+    },
+    {
+      path: 'tmdb.apiKeyCommand',
+      kind: 'string',
+      defaultValue: defaultConfig.tmdb.apiKeyCommand,
+      description:
+        'Shell command that prints the TMDB API key to stdout. Used instead of apiKey to avoid storing the key in plain text.',
+    },
     {
       path: 'anilist.enabled',
       kind: 'boolean',
diff --git a/src/config/definitions/options-subtitle.ts b/src/config/definitions/options-subtitle.ts
index b7ab187e..72a1b386 100644
--- a/src/config/definitions/options-subtitle.ts
+++ b/src/config/definitions/options-subtitle.ts
@@ -1,10 +1,53 @@
 import { ResolvedConfig } from '../../types/config';
 import { ConfigOptionRegistryEntry } from './shared';
+import { SUBTITLE_GENERATION_MODELS } from '../../shared/subtitle-generation-model-catalog';
 
 export function buildSubtitleConfigOptionRegistry(
   defaultConfig: ResolvedConfig,
 ): ConfigOptionRegistryEntry[] {
   return [
+    {
+      path: 'subtitleSelection.enabled',
+      kind: 'boolean',
+      defaultValue: defaultConfig.subtitleSelection.enabled,
+      description:
+        'Use the SubMiner modal to select primary and secondary subtitle tracks. When enabled, its shortcut overrides mpv subtitle selection.',
+    },
+    ...(
+      ['whisperPath', 'modelPath', 'ffmpegPath', 'ffprobePath', 'vadModelPath', 'vadPath'] as const
+    ).map((key) => ({
+      path: `subtitleGeneration.${key}`,
+      kind: 'string' as const,
+      defaultValue: defaultConfig.subtitleGeneration[key],
+      description: {
+        whisperPath:
+          'Optional path override for whisper.cpp. Leave empty to find whisper-cli on PATH.',
+        modelPath:
+          'Path to an existing multilingual whisper.cpp GGML model. Leave empty to use a SubMiner-managed model. A configured path always takes precedence.',
+        ffmpegPath:
+          'Optional FFmpeg path override for audio extraction. Leave empty to find ffmpeg on PATH.',
+        ffprobePath:
+          'Optional FFprobe path override for audio tracks and timing. Leave empty to find ffprobe on PATH.',
+        vadModelPath:
+          'Path to a whisper.cpp Silero VAD model. Enables dialogue-focused generation while retaining uncertain audible sections, which may include songs. Leave empty to transcribe the full audio.',
+        vadPath:
+          'Optional speech detector executable override. With vadModelPath configured, leave empty to find whisper-vad-speech-segments or vad-speech-segments on PATH.',
+      }[key],
+    })),
+    {
+      path: 'subtitleGeneration.managedModel',
+      kind: 'enum',
+      enumValues: SUBTITLE_GENERATION_MODELS.map((model) => model.id),
+      defaultValue: defaultConfig.subtitleGeneration.managedModel,
+      description:
+        'Multilingual whisper.cpp model to use when modelPath is empty. Download it explicitly from the generation modal or launcher.',
+    },
+    {
+      path: 'subtitleGeneration.threads',
+      kind: 'number',
+      defaultValue: defaultConfig.subtitleGeneration.threads,
+      description: 'Positive integer CPU thread count for whisper.cpp Japanese transcription.',
+    },
     {
       path: 'subtitleStyle.primaryDefaultMode',
       kind: 'enum',
diff --git a/src/config/definitions/runtime-options.ts b/src/config/definitions/runtime-options.ts
index 12a6ceb6..7d9f5080 100644
--- a/src/config/definitions/runtime-options.ts
+++ b/src/config/definitions/runtime-options.ts
@@ -19,6 +19,20 @@ export function buildRuntimeOptionRegistry(
         behavior: { autoUpdateNewCards: value === true },
       }),
     },
+    {
+      id: 'anki.mediaReviewTiming',
+      path: 'ankiConnect.media.reviewTiming',
+      label: 'Review Media Timing',
+      scope: 'ankiConnect',
+      valueType: 'boolean',
+      allowedValues: [true, false],
+      defaultValue: defaultConfig.ankiConnect.media.reviewTiming,
+      requiresRestart: false,
+      formatValueForOsd: (value) => (value === true ? 'On' : 'Off'),
+      toAnkiPatch: (value) => ({
+        media: { reviewTiming: value === true },
+      }),
+    },
     {
       id: 'subtitle.annotation.knownWords.highlightEnabled',
       path: 'ankiConnect.knownWords.highlightEnabled',
@@ -124,5 +138,22 @@ export function buildRuntimeOptionRegistry(
         },
       }),
     },
+    {
+      id: 'anki.senrenFieldGrouping',
+      path: 'ankiConnect.isSenren.fieldGrouping',
+      label: 'Senren Field Grouping',
+      scope: 'ankiConnect',
+      valueType: 'enum',
+      allowedValues: ['auto', 'manual', 'disabled'],
+      defaultValue: 'auto',
+      requiresRestart: false,
+      formatValueForOsd: (value) => String(value),
+      toAnkiPatch: (value) => ({
+        isSenren: {
+          fieldGrouping:
+            value === 'auto' || value === 'manual' || value === 'disabled' ? value : 'auto',
+        },
+      }),
+    },
   ];
 }
diff --git a/src/config/definitions/template-sections.ts b/src/config/definitions/template-sections.ts
index 43b22c60..6411454f 100644
--- a/src/config/definitions/template-sections.ts
+++ b/src/config/definitions/template-sections.ts
@@ -1,6 +1,21 @@
 import { ConfigTemplateSection } from './shared';
 
 const CORE_TEMPLATE_SECTIONS: ConfigTemplateSection[] = [
+  {
+    title: 'Subtitle Selection',
+    description: ['Select primary and secondary mpv subtitle tracks from the overlay.'],
+    notes: ['Hot-reload: enabling or disabling updates the session shortcut immediately.'],
+    key: 'subtitleSelection',
+  },
+  {
+    title: 'Japanese Subtitle Generation',
+    description: [
+      'Generate timed Japanese subtitles from local audio using whisper.cpp.',
+      'Configure an existing GGML model path or explicitly download a SubMiner-managed model.',
+    ],
+    notes: ['Hot-reload: settings apply to the next generation or model download.'],
+    key: 'subtitleGeneration',
+  },
   {
     title: 'Visible Overlay Auto-Start',
     description: [
@@ -135,7 +150,7 @@ const INTEGRATION_TEMPLATE_SECTIONS: ConfigTemplateSection[] = [
     title: 'AnkiConnect Integration',
     description: ['Automatic Anki updates and media generation options.'],
     notes: [
-      'Hot-reload: ankiConnect.ai.enabled, media.normalizeAudio/mirrorMpvVolume, knownWords, nPlusOne, fields.word/audio/image/sentence/miscInfo, behavior.autoUpdateNewCards, isLapis.sentenceCardModel, isKiku.fieldGrouping, and lapisKiku.wordCardKind update live while SubMiner is running.',
+      'Hot-reload: ankiConnect.ai.enabled, media.normalizeAudio/mirrorMpvVolume/reviewTiming, knownWords, nPlusOne, fields.word/audio/wordAudio/image/sentence/miscInfo, behavior.autoUpdateNewCards, isLapis.sentenceCardModel, isKiku.fieldGrouping, isSenren.fieldGrouping, and lapisKiku.wordCardKind update live while SubMiner is running.',
       'Shared AI provider transport settings are read from top-level ai and typically require restart.',
       'Most other AnkiConnect settings still require restart.',
     ],
@@ -155,6 +170,14 @@ const INTEGRATION_TEMPLATE_SECTIONS: ConfigTemplateSection[] = [
     notes: ['Hot-reload: TsukiHime changes apply to the next TsukiHime request.'],
     key: 'tsukihime',
   },
+  {
+    title: 'TMDB',
+    description: [
+      'TMDB (The Movie Database) metadata for live-action dramas and movies in the stats Library: posters, synopses, and grouping by show.',
+    ],
+    notes: ['Hot-reload: TMDB changes apply to the next TMDB request.'],
+    key: 'tmdb',
+  },
   {
     title: 'YouTube Playback Settings',
     description: [
diff --git a/src/config/hot-reload.ts b/src/config/hot-reload.ts
new file mode 100644
index 00000000..990aef76
--- /dev/null
+++ b/src/config/hot-reload.ts
@@ -0,0 +1,71 @@
+function pathStartsWith(path: string, prefix: string): boolean {
+  return path === prefix || path.startsWith(`${prefix}.`);
+}
+
+const HOT_RELOAD_ROOTS = [
+  'subtitleStyle',
+  'keybindings',
+  'shortcuts',
+  'subtitleSidebar',
+  'subtitleSelection',
+] as const;
+
+const HOT_RELOAD_EXACT_OR_PREFIX_PATHS = [
+  'secondarySub.defaultMode',
+  'mpv.aniskipEnabled',
+  'mpv.aniskipButtonKey',
+  'ankiConnect.ai.enabled',
+  'stats.toggleKey',
+  'stats.markWatchedKey',
+  'logging.level',
+  'logging.rotation',
+  'logging.files',
+  'youtube.primarySubLanguages',
+  'ankiConnect.deck',
+  'ankiConnect.media.normalizeAudio',
+  'ankiConnect.media.mirrorMpvVolume',
+  'ankiConnect.media.reviewTiming',
+  'ankiConnect.behavior.autoUpdateNewCards',
+  'ankiConnect.knownWords.highlightEnabled',
+  'ankiConnect.knownWords.refreshMinutes',
+  'ankiConnect.knownWords.addMinedWordsImmediately',
+  'ankiConnect.knownWords.matchMode',
+  'ankiConnect.knownWords.decks',
+  'ankiConnect.nPlusOne.enabled',
+  'ankiConnect.nPlusOne.minSentenceWords',
+  'ankiConnect.fields.word',
+  'ankiConnect.fields.audio',
+  'ankiConnect.fields.wordAudio',
+  'ankiConnect.fields.image',
+  'ankiConnect.fields.sentence',
+  'ankiConnect.fields.miscInfo',
+  'ankiConnect.isLapis.sentenceCardModel',
+  'ankiConnect.isKiku.fieldGrouping',
+  'ankiConnect.isSenren.fieldGrouping',
+  'ankiConnect.lapisKiku.wordCardKind',
+] as const;
+
+export function getConfigHotReloadField(path: string): string | null {
+  for (const root of HOT_RELOAD_ROOTS) {
+    if (pathStartsWith(path, root)) {
+      return root;
+    }
+  }
+
+  for (const hotPath of HOT_RELOAD_EXACT_OR_PREFIX_PATHS) {
+    if (pathStartsWith(path, hotPath)) {
+      return hotPath;
+    }
+  }
+
+  // These consumers read the current config when the next operation starts.
+  if (
+    ['jimaku', 'tmdb', 'subsync', 'notifications', 'subtitleGeneration'].some((root) =>
+      pathStartsWith(path, root),
+    )
+  ) {
+    return path;
+  }
+
+  return null;
+}
diff --git a/src/config/resolve/anki-connect.test.ts b/src/config/resolve/anki-connect.test.ts
index 6b469208..2e0f76ee 100644
--- a/src/config/resolve/anki-connect.test.ts
+++ b/src/config/resolve/anki-connect.test.ts
@@ -21,6 +21,129 @@ function makeContext(ankiConnect: unknown): {
   return { context, warnings };
 }
 
+test('media timing review is disabled by default and accepts a boolean override', () => {
+  const defaultContext = makeContext({});
+  applyAnkiConnectResolution(defaultContext.context);
+  assert.equal(defaultContext.context.resolved.ankiConnect.media.reviewTiming, false);
+
+  const enabledContext = makeContext({ media: { reviewTiming: true } });
+  applyAnkiConnectResolution(enabledContext.context);
+  assert.equal(enabledContext.context.resolved.ankiConnect.media.reviewTiming, true);
+  assert.deepEqual(enabledContext.warnings, []);
+});
+
+test('invalid direct and field-grouping Anki values warn and keep defaults', () => {
+  const { context, warnings } = makeContext({
+    enabled: 'true',
+    url: 8765,
+    pollingRate: '3000',
+    deck: ['Mining'],
+    isKiku: {
+      enabled: 1,
+      fieldGrouping: 'sometimes',
+      deleteDuplicateInAuto: 'false',
+    },
+    isSenren: {
+      enabled: 'true',
+      fieldGrouping: false,
+      deleteDuplicateInAuto: 0,
+    },
+  });
+
+  applyAnkiConnectResolution(context);
+
+  assert.equal(context.resolved.ankiConnect.enabled, DEFAULT_CONFIG.ankiConnect.enabled);
+  assert.equal(context.resolved.ankiConnect.url, DEFAULT_CONFIG.ankiConnect.url);
+  assert.equal(context.resolved.ankiConnect.pollingRate, DEFAULT_CONFIG.ankiConnect.pollingRate);
+  assert.equal(context.resolved.ankiConnect.deck, DEFAULT_CONFIG.ankiConnect.deck);
+  assert.deepEqual(context.resolved.ankiConnect.isKiku, DEFAULT_CONFIG.ankiConnect.isKiku);
+  assert.deepEqual(context.resolved.ankiConnect.isSenren, DEFAULT_CONFIG.ankiConnect.isSenren);
+  assert.deepEqual(
+    warnings.map((warning) => warning.path),
+    [
+      'ankiConnect.enabled',
+      'ankiConnect.url',
+      'ankiConnect.pollingRate',
+      'ankiConnect.deck',
+      'ankiConnect.isKiku.enabled',
+      'ankiConnect.isKiku.deleteDuplicateInAuto',
+      'ankiConnect.isKiku.fieldGrouping',
+      'ankiConnect.isSenren.enabled',
+      'ankiConnect.isSenren.deleteDuplicateInAuto',
+      'ankiConnect.isSenren.fieldGrouping',
+    ],
+  );
+});
+
+test('accepts valid direct and field-grouping Anki values', () => {
+  const { context, warnings } = makeContext({
+    enabled: false,
+    url: 'http://127.0.0.1:9876',
+    pollingRate: 750,
+    deck: 'Mining',
+    isKiku: {
+      enabled: true,
+      fieldGrouping: 'manual',
+      deleteDuplicateInAuto: false,
+    },
+    isSenren: {
+      enabled: false,
+      fieldGrouping: 'disabled',
+      deleteDuplicateInAuto: false,
+    },
+  });
+
+  applyAnkiConnectResolution(context);
+
+  assert.equal(context.resolved.ankiConnect.enabled, false);
+  assert.equal(context.resolved.ankiConnect.url, 'http://127.0.0.1:9876');
+  assert.equal(context.resolved.ankiConnect.pollingRate, 750);
+  assert.equal(context.resolved.ankiConnect.deck, 'Mining');
+  assert.deepEqual(context.resolved.ankiConnect.isKiku, {
+    enabled: true,
+    fieldGrouping: 'manual',
+    deleteDuplicateInAuto: false,
+  });
+  assert.deepEqual(context.resolved.ankiConnect.isSenren, {
+    enabled: false,
+    fieldGrouping: 'disabled',
+    deleteDuplicateInAuto: false,
+  });
+  assert.deepEqual(warnings, []);
+});
+
+test('ignores unknown Anki keys without warning or admitting them to resolved config', () => {
+  const { context, warnings } = makeContext({
+    futureOption: { enabled: true },
+    isKiku: { futureGroupingOption: 'future' },
+    isSenren: { futureGroupingOption: 'future' },
+  });
+
+  applyAnkiConnectResolution(context);
+
+  assert.equal(Object.hasOwn(context.resolved.ankiConnect, 'futureOption'), false);
+  assert.equal(Object.hasOwn(context.resolved.ankiConnect.isKiku, 'futureGroupingOption'), false);
+  assert.equal(Object.hasOwn(context.resolved.ankiConnect.isSenren, 'futureGroupingOption'), false);
+  assert.deepEqual(warnings, []);
+});
+
+test('modern media duration accepts zero as the disabled cap sentinel', () => {
+  const disabledCap = makeContext({ media: { maxMediaDuration: 0 } });
+  applyAnkiConnectResolution(disabledCap.context);
+  assert.equal(disabledCap.context.resolved.ankiConnect.media.maxMediaDuration, 0);
+  assert.deepEqual(disabledCap.warnings, []);
+
+  const invalidCap = makeContext({ media: { maxMediaDuration: -1 } });
+  applyAnkiConnectResolution(invalidCap.context);
+  assert.equal(
+    invalidCap.context.resolved.ankiConnect.media.maxMediaDuration,
+    DEFAULT_CONFIG.ankiConnect.media.maxMediaDuration,
+  );
+  assert.ok(
+    invalidCap.warnings.some((warning) => warning.path === 'ankiConnect.media.maxMediaDuration'),
+  );
+});
+
 test('modern invalid knownWords.highlightEnabled warns modern key and does not fallback to legacy', () => {
   const { context, warnings } = makeContext({
     nPlusOne: { highlightEnabled: true },
@@ -262,6 +385,28 @@ test('accepts ankiConnect.media.syncAnimatedImageToWordAudio override', () => {
   );
 });
 
+test('word audio mapping defaults and validates independently of sentence audio', () => {
+  for (const wordAudio of [undefined, 'Pronunciation', 7]) {
+    const { context, warnings } = makeContext({
+      fields: {
+        audio: 'SentenceAudio',
+        ...(wordAudio !== undefined ? { wordAudio } : {}),
+      },
+    });
+    applyAnkiConnectResolution(context);
+
+    assert.equal(context.resolved.ankiConnect.fields.audio, 'SentenceAudio');
+    assert.equal(
+      context.resolved.ankiConnect.fields.wordAudio,
+      typeof wordAudio === 'string' ? wordAudio : DEFAULT_CONFIG.ankiConnect.fields.wordAudio,
+    );
+    assert.deepEqual(
+      warnings.map((warning) => warning.path),
+      typeof wordAudio === 'number' ? ['ankiConnect.fields.wordAudio'] : [],
+    );
+  }
+});
+
 test('invalid modern Anki subtrees warn and keep resolved defaults', () => {
   const { context, warnings } = makeContext({
     fields: { word: 7 },
diff --git a/src/config/resolve/anki-connect.ts b/src/config/resolve/anki-connect.ts
index 8ec0da31..f78791ab 100644
--- a/src/config/resolve/anki-connect.ts
+++ b/src/config/resolve/anki-connect.ts
@@ -1,6 +1,7 @@
 import type { ResolveContext } from './context';
 import { initializeAnkiConnectResolution } from './anki-connect/initialize';
 import { applyAnkiKikuResolution } from './anki-connect/kiku';
+import { applyAnkiSenrenResolution } from './anki-connect/senren';
 import { applyAnkiLapisKikuResolution } from './anki-connect/lapis-kiku';
 import { applyAnkiKnownWordsResolution } from './anki-connect/known-words';
 import { applyAnkiLegacyResolution } from './anki-connect/legacy';
@@ -18,10 +19,11 @@ export function applyAnkiConnectResolution(context: ResolveContext): void {
   const media = isObject(ankiConnect.media) ? ankiConnect.media : {};
   const metadata = isObject(ankiConnect.metadata) ? ankiConnect.metadata : {};
 
-  initializeAnkiConnectResolution(context, ankiConnect);
+  initializeAnkiConnectResolution(context);
   applyAnkiModernResolution(context, ankiConnect, behavior, media);
   applyAnkiLegacyResolution(context, ankiConnect, behavior, fields, media, metadata);
   applyAnkiKnownWordsResolution(context, ankiConnect, behavior);
-  applyAnkiKikuResolution(context);
+  applyAnkiKikuResolution(context, ankiConnect);
+  applyAnkiSenrenResolution(context, ankiConnect);
   applyAnkiLapisKikuResolution(context, ankiConnect);
 }
diff --git a/src/config/resolve/anki-connect/base.ts b/src/config/resolve/anki-connect/base.ts
new file mode 100644
index 00000000..b26ebf98
--- /dev/null
+++ b/src/config/resolve/anki-connect/base.ts
@@ -0,0 +1,58 @@
+import { DEFAULT_CONFIG } from '../../definitions';
+import type { ResolveContext } from '../context';
+import { asBoolean, asString } from '../shared';
+import { applyModernValue, asPositiveNumber } from './modern-value';
+
+export function applyAnkiBaseResolution(
+  context: ResolveContext,
+  ankiConnect: Record<string, unknown>,
+): void {
+  applyModernValue(
+    context,
+    ankiConnect,
+    'enabled',
+    'ankiConnect.enabled',
+    asBoolean,
+    DEFAULT_CONFIG.ankiConnect.enabled,
+    (value) => {
+      context.resolved.ankiConnect.enabled = value;
+    },
+    'Expected boolean.',
+  );
+  applyModernValue(
+    context,
+    ankiConnect,
+    'url',
+    'ankiConnect.url',
+    asString,
+    DEFAULT_CONFIG.ankiConnect.url,
+    (value) => {
+      context.resolved.ankiConnect.url = value;
+    },
+    'Expected string.',
+  );
+  applyModernValue(
+    context,
+    ankiConnect,
+    'pollingRate',
+    'ankiConnect.pollingRate',
+    asPositiveNumber,
+    DEFAULT_CONFIG.ankiConnect.pollingRate,
+    (value) => {
+      context.resolved.ankiConnect.pollingRate = value;
+    },
+    'Expected positive number.',
+  );
+  applyModernValue(
+    context,
+    ankiConnect,
+    'deck',
+    'ankiConnect.deck',
+    asString,
+    DEFAULT_CONFIG.ankiConnect.deck,
+    (value) => {
+      context.resolved.ankiConnect.deck = value;
+    },
+    'Expected string.',
+  );
+}
diff --git a/src/config/resolve/anki-connect/field-grouping-config.ts b/src/config/resolve/anki-connect/field-grouping-config.ts
new file mode 100644
index 00000000..599be33a
--- /dev/null
+++ b/src/config/resolve/anki-connect/field-grouping-config.ts
@@ -0,0 +1,53 @@
+import { DEFAULT_CONFIG } from '../../definitions';
+import type { ResolveContext } from '../context';
+import { asBoolean, isObject } from '../shared';
+import { applyModernValue } from './modern-value';
+
+type FieldGroupingConfigKey = 'isKiku' | 'isSenren';
+
+export function applyFieldGroupingConfigResolution(
+  context: ResolveContext,
+  ankiConnect: Record<string, unknown>,
+  key: FieldGroupingConfigKey,
+): void {
+  const source = ankiConnect[key];
+  if (!isObject(source)) {
+    if (source !== undefined) {
+      context.warn(
+        `ankiConnect.${key}`,
+        source,
+        DEFAULT_CONFIG.ankiConnect[key],
+        'Expected object.',
+      );
+    }
+    return;
+  }
+
+  for (const booleanKey of ['enabled', 'deleteDuplicateInAuto'] as const) {
+    applyModernValue(
+      context,
+      source,
+      booleanKey,
+      `ankiConnect.${key}.${booleanKey}`,
+      asBoolean,
+      DEFAULT_CONFIG.ankiConnect[key][booleanKey],
+      (value) => {
+        context.resolved.ankiConnect[key][booleanKey] = value;
+      },
+      'Expected boolean.',
+    );
+  }
+
+  applyModernValue(
+    context,
+    source,
+    'fieldGrouping',
+    `ankiConnect.${key}.fieldGrouping`,
+    (value) => (value === 'auto' || value === 'manual' || value === 'disabled' ? value : undefined),
+    DEFAULT_CONFIG.ankiConnect[key].fieldGrouping,
+    (value) => {
+      context.resolved.ankiConnect[key].fieldGrouping = value;
+    },
+    'Expected auto, manual, or disabled.',
+  );
+}
diff --git a/src/config/resolve/anki-connect/initialize.ts b/src/config/resolve/anki-connect/initialize.ts
index b7571b7f..490d6888 100644
--- a/src/config/resolve/anki-connect/initialize.ts
+++ b/src/config/resolve/anki-connect/initialize.ts
@@ -1,55 +1,8 @@
 import type { ResolveContext } from '../context';
-import { isObject } from '../shared';
-
-const LEGACY_KEYS = new Set([
-  'wordField',
-  'audioField',
-  'imageField',
-  'sentenceField',
-  'miscInfoField',
-  'miscInfoPattern',
-  'generateAudio',
-  'generateImage',
-  'imageType',
-  'imageFormat',
-  'imageQuality',
-  'imageMaxWidth',
-  'imageMaxHeight',
-  'animatedFps',
-  'animatedMaxWidth',
-  'animatedMaxHeight',
-  'animatedCrf',
-  'syncAnimatedImageToWordAudio',
-  'audioPadding',
-  'fallbackDuration',
-  'maxMediaDuration',
-  'overwriteAudio',
-  'overwriteImage',
-  'mediaInsertMode',
-  'highlightWord',
-  'notificationType',
-  'autoUpdateNewCards',
-]);
-
-export function initializeAnkiConnectResolution(
-  context: ResolveContext,
-  ankiConnect: Record<string, unknown>,
-): void {
-  const {
-    knownWords: _knownWordsConfigFromAnkiConnect,
-    nPlusOne: _nPlusOneConfigFromAnkiConnect,
-    ai: _ankiAiConfig,
-    ...ankiConnectWithoutKnownWordsOrNPlusOne
-  } = ankiConnect;
-  const ankiConnectWithoutLegacy = Object.fromEntries(
-    Object.entries(ankiConnectWithoutKnownWordsOrNPlusOne).filter(([key]) => !LEGACY_KEYS.has(key)),
-  );
 
+export function initializeAnkiConnectResolution(context: ResolveContext): void {
   context.resolved.ankiConnect = {
     ...context.resolved.ankiConnect,
-    ...(isObject(ankiConnectWithoutLegacy)
-      ? (ankiConnectWithoutLegacy as Partial<(typeof context.resolved)['ankiConnect']>)
-      : {}),
     fields: {
       ...context.resolved.ankiConnect.fields,
     },
@@ -73,9 +26,9 @@ export function initializeAnkiConnectResolution(
     },
     isKiku: {
       ...context.resolved.ankiConnect.isKiku,
-      ...(isObject(ankiConnect.isKiku)
-        ? (ankiConnect.isKiku as (typeof context.resolved)['ankiConnect']['isKiku'])
-        : {}),
+    },
+    isSenren: {
+      ...context.resolved.ankiConnect.isSenren,
     },
     lapisKiku: {
       ...context.resolved.ankiConnect.lapisKiku,
diff --git a/src/config/resolve/anki-connect/kiku.ts b/src/config/resolve/anki-connect/kiku.ts
index bce4ddb5..c2a854df 100644
--- a/src/config/resolve/anki-connect/kiku.ts
+++ b/src/config/resolve/anki-connect/kiku.ts
@@ -1,19 +1,9 @@
-import { DEFAULT_CONFIG } from '../../definitions';
 import type { ResolveContext } from '../context';
+import { applyFieldGroupingConfigResolution } from './field-grouping-config';
 
-export function applyAnkiKikuResolution(context: ResolveContext): void {
-  if (
-    context.resolved.ankiConnect.isKiku.fieldGrouping !== 'auto' &&
-    context.resolved.ankiConnect.isKiku.fieldGrouping !== 'manual' &&
-    context.resolved.ankiConnect.isKiku.fieldGrouping !== 'disabled'
-  ) {
-    context.warn(
-      'ankiConnect.isKiku.fieldGrouping',
-      context.resolved.ankiConnect.isKiku.fieldGrouping,
-      DEFAULT_CONFIG.ankiConnect.isKiku.fieldGrouping,
-      'Expected auto, manual, or disabled.',
-    );
-    context.resolved.ankiConnect.isKiku.fieldGrouping =
-      DEFAULT_CONFIG.ankiConnect.isKiku.fieldGrouping;
-  }
+export function applyAnkiKikuResolution(
+  context: ResolveContext,
+  ankiConnect: Record<string, unknown>,
+): void {
+  applyFieldGroupingConfigResolution(context, ankiConnect, 'isKiku');
 }
diff --git a/src/config/resolve/anki-connect/modern-fields.ts b/src/config/resolve/anki-connect/modern-fields.ts
index c8d30ad1..228d8615 100644
--- a/src/config/resolve/anki-connect/modern-fields.ts
+++ b/src/config/resolve/anki-connect/modern-fields.ts
@@ -7,7 +7,15 @@ export function applyModernFieldsResolution(
   context: ResolveContext,
   fields: Record<string, unknown>,
 ): void {
-  for (const key of ['word', 'audio', 'image', 'sentence', 'miscInfo', 'translation'] as const) {
+  for (const key of [
+    'word',
+    'audio',
+    'wordAudio',
+    'image',
+    'sentence',
+    'miscInfo',
+    'translation',
+  ] as const) {
     applyModernValue(
       context,
       fields,
diff --git a/src/config/resolve/anki-connect/modern-media.ts b/src/config/resolve/anki-connect/modern-media.ts
index d391f1c0..0babef6f 100644
--- a/src/config/resolve/anki-connect/modern-media.ts
+++ b/src/config/resolve/anki-connect/modern-media.ts
@@ -19,6 +19,7 @@ export function applyModernMediaResolution(
     'syncAnimatedImageToWordAudio',
     'normalizeAudio',
     'mirrorMpvVolume',
+    'reviewTiming',
   ] as const) {
     applyModernValue(
       context,
@@ -128,18 +129,28 @@ export function applyModernMediaResolution(
     'Expected non-negative number.',
   );
 
-  for (const key of ['fallbackDuration', 'maxMediaDuration'] as const) {
-    applyModernValue(
-      context,
-      media,
-      key,
-      `ankiConnect.media.${key}`,
-      asPositiveNumber,
-      DEFAULT_CONFIG.ankiConnect.media[key],
-      (value) => {
-        context.resolved.ankiConnect.media[key] = value;
-      },
-      'Expected positive number.',
-    );
-  }
+  applyModernValue(
+    context,
+    media,
+    'fallbackDuration',
+    'ankiConnect.media.fallbackDuration',
+    asPositiveNumber,
+    DEFAULT_CONFIG.ankiConnect.media.fallbackDuration,
+    (value) => {
+      context.resolved.ankiConnect.media.fallbackDuration = value;
+    },
+    'Expected positive number.',
+  );
+  applyModernValue(
+    context,
+    media,
+    'maxMediaDuration',
+    'ankiConnect.media.maxMediaDuration',
+    asNonNegativeNumber,
+    DEFAULT_CONFIG.ankiConnect.media.maxMediaDuration,
+    (value) => {
+      context.resolved.ankiConnect.media.maxMediaDuration = value;
+    },
+    'Expected non-negative number.',
+  );
 }
diff --git a/src/config/resolve/anki-connect/modern.ts b/src/config/resolve/anki-connect/modern.ts
index bb240cea..2ac882d8 100644
--- a/src/config/resolve/anki-connect/modern.ts
+++ b/src/config/resolve/anki-connect/modern.ts
@@ -1,6 +1,7 @@
 import type { ResolveContext } from '../context';
 import { isObject } from '../shared';
 import { applyAiResolution } from './ai';
+import { applyAnkiBaseResolution } from './base';
 import { applyLapisResolution } from './lapis';
 import { applyModernBehaviorResolution } from './modern-behavior';
 import { applyModernFieldsResolution } from './modern-fields';
@@ -18,6 +19,7 @@ export function applyAnkiModernResolution(
   const fields = isObject(ankiConnect.fields) ? ankiConnect.fields : {};
   const metadata = isObject(ankiConnect.metadata) ? ankiConnect.metadata : {};
 
+  applyAnkiBaseResolution(context, ankiConnect);
   applyModernFieldsResolution(context, fields);
   applyModernMediaResolution(context, media);
   applyModernBehaviorResolution(context, behavior);
diff --git a/src/config/resolve/anki-connect/senren.ts b/src/config/resolve/anki-connect/senren.ts
new file mode 100644
index 00000000..e101f00d
--- /dev/null
+++ b/src/config/resolve/anki-connect/senren.ts
@@ -0,0 +1,24 @@
+import type { ResolveContext } from '../context';
+import { applyFieldGroupingConfigResolution } from './field-grouping-config';
+
+export function applyAnkiSenrenResolution(
+  context: ResolveContext,
+  ankiConnect: Record<string, unknown>,
+): void {
+  applyFieldGroupingConfigResolution(context, ankiConnect, 'isSenren');
+
+  // Kiku and Senren field grouping write incompatible markup into the same note
+  // fields, so only one may be active; Kiku wins to preserve pre-existing setups.
+  if (
+    context.resolved.ankiConnect.isSenren.enabled === true &&
+    context.resolved.ankiConnect.isKiku.enabled === true
+  ) {
+    context.warn(
+      'ankiConnect.isSenren.enabled',
+      true,
+      false,
+      'Kiku and Senren are mutually exclusive; disable isKiku.enabled to use Senren field grouping.',
+    );
+    context.resolved.ankiConnect.isSenren.enabled = false;
+  }
+}
diff --git a/src/config/resolve/core-domains.ts b/src/config/resolve/core-domains.ts
index c531fc52..f29f7e57 100644
--- a/src/config/resolve/core-domains.ts
+++ b/src/config/resolve/core-domains.ts
@@ -6,6 +6,25 @@ import { asBoolean, asNumber, asString, isObject } from './shared';
 export function applyCoreDomainConfig(context: ResolveContext): void {
   const { src, resolved, warn } = context;
 
+  if (isObject(src.subtitleSelection)) {
+    const enabled = asBoolean(src.subtitleSelection.enabled);
+    if (enabled !== undefined) resolved.subtitleSelection.enabled = enabled;
+    else if (src.subtitleSelection.enabled !== undefined)
+      warn(
+        'subtitleSelection.enabled',
+        src.subtitleSelection.enabled,
+        resolved.subtitleSelection.enabled,
+        'Expected boolean.',
+      );
+  } else if (src.subtitleSelection !== undefined) {
+    warn(
+      'subtitleSelection',
+      src.subtitleSelection,
+      resolved.subtitleSelection,
+      'Expected object.',
+    );
+  }
+
   if (isObject(src.texthooker)) {
     const launchAtStartup = asBoolean(src.texthooker.launchAtStartup);
     if (launchAtStartup !== undefined) {
@@ -237,6 +256,8 @@ export function applyCoreDomainConfig(context: ResolveContext): void {
       'openRuntimeOptions',
       'openJimaku',
       'openTsukihime',
+      'openSubtitleSelection',
+      'openSubtitleGeneration',
       'openSessionHelp',
       'openControllerSelect',
       'openControllerDebug',
diff --git a/src/config/resolve/integrations.ts b/src/config/resolve/integrations.ts
index 6324eaee..952e6362 100644
--- a/src/config/resolve/integrations.ts
+++ b/src/config/resolve/integrations.ts
@@ -58,6 +58,19 @@ export function applyIntegrationConfig(context: ResolveContext): void {
     warn('ai', src.ai, resolved.ai, 'Expected object.');
   }
 
+  if (isObject(src.tmdb)) {
+    for (const key of ['apiKey', 'apiKeyCommand'] as const) {
+      const value = asString(src.tmdb[key]);
+      if (value !== undefined) {
+        resolved.tmdb[key] = value;
+      } else if (src.tmdb[key] !== undefined) {
+        warn(`tmdb.${key}`, src.tmdb[key], resolved.tmdb[key], 'Expected string.');
+      }
+    }
+  } else if (src.tmdb !== undefined) {
+    warn('tmdb', src.tmdb, resolved.tmdb, 'Expected object.');
+  }
+
   if (isObject(src.anilist)) {
     const enabled = asBoolean(src.anilist.enabled);
     if (enabled !== undefined) {
diff --git a/src/config/resolve/subtitle-domains.ts b/src/config/resolve/subtitle-domains.ts
index 8d07e410..f9aead68 100644
--- a/src/config/resolve/subtitle-domains.ts
+++ b/src/config/resolve/subtitle-domains.ts
@@ -1,5 +1,6 @@
 import { ResolvedConfig } from '../../types/config';
 import { ResolveContext } from './context';
+import { resolveSubtitleGenerationConfig } from '../../shared/subtitle-generation';
 import {
   asBoolean,
   asColor,
@@ -46,6 +47,17 @@ function applySubtitleHoverTokenCssCompatibility(
 
 export function applySubtitleDomainConfig(context: ResolveContext): void {
   const { src, resolved, warn } = context;
+  resolved.subtitleGeneration = resolveSubtitleGenerationConfig(
+    src.subtitleGeneration,
+    (key, value, message) => {
+      const configPath = key === 'subtitleGeneration' ? key : `subtitleGeneration.${key}`;
+      const fallback =
+        key === 'subtitleGeneration'
+          ? resolved.subtitleGeneration
+          : Object.entries(resolved.subtitleGeneration).find(([name]) => name === key)?.[1];
+      warn(configPath, value, fallback, message);
+    },
+  );
 
   if (isObject(src.jimaku)) {
     const apiKey = asString(src.jimaku.apiKey);
diff --git a/src/config/resolve/subtitle-generation.test.ts b/src/config/resolve/subtitle-generation.test.ts
new file mode 100644
index 00000000..10500cef
--- /dev/null
+++ b/src/config/resolve/subtitle-generation.test.ts
@@ -0,0 +1,90 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { resolveConfig } from '../resolve';
+import { buildConfigSettingsRegistry } from '../settings/registry';
+import { SUBTITLE_GENERATION_MODELS } from '../../shared/subtitle-generation-model-catalog';
+import { resolveSubtitleGenerationConfig } from '../../shared/subtitle-generation';
+
+test('every downloadable multilingual model is accepted by config and offered in settings', () => {
+  const settings = buildConfigSettingsRegistry(resolveConfig({}).resolved).find(
+    (entry) => entry.configPath === 'subtitleGeneration.managedModel',
+  );
+  assert.deepEqual(
+    settings?.enumValues,
+    SUBTITLE_GENERATION_MODELS.map((model) => model.id),
+  );
+  for (const { id } of SUBTITLE_GENERATION_MODELS) {
+    const { resolved, warnings } = resolveConfig({ subtitleGeneration: { managedModel: id } });
+    assert.equal(resolved.subtitleGeneration.managedModel, id);
+    assert.equal(warnings.length, 0);
+  }
+});
+
+test('generation config rejects English-only, unknown, and prototype model names', () => {
+  for (const managedModel of ['tiny.en', 'small.en-q5_1', 'unknown', 'toString', '__proto__']) {
+    const warnings: string[] = [];
+    const resolved = resolveSubtitleGenerationConfig({ managedModel }, (key) => warnings.push(key));
+    assert.equal(resolved.managedModel, 'small');
+    assert.equal(warnings.length, 1);
+  }
+});
+
+test('generation config is resolved and its external model path is editable without restart', () => {
+  const { resolved, warnings } = resolveConfig({
+    subtitleGeneration: { modelPath: '/models/japanese.bin', managedModel: 'medium', threads: 8 },
+  });
+  assert.equal(resolved.subtitleGeneration.modelPath, '/models/japanese.bin');
+  assert.equal(resolved.subtitleGeneration.managedModel, 'medium');
+  assert.equal(warnings.length, 0);
+  const field = buildConfigSettingsRegistry(resolved).find(
+    (entry) => entry.configPath === 'subtitleGeneration.modelPath',
+  );
+  assert.equal(field?.category, 'integrations');
+  assert.equal(field?.restartBehavior, 'hot-reload');
+});
+
+test('generation executable overrides default to empty and accept blank values without warnings', () => {
+  for (const subtitleGeneration of [
+    {},
+    { whisperPath: '', ffmpegPath: '', ffprobePath: '' },
+    { whisperPath: '  ', ffmpegPath: '  ', ffprobePath: '  ' },
+  ]) {
+    const { resolved, warnings } = resolveConfig({ subtitleGeneration });
+    assert.equal(resolved.subtitleGeneration.whisperPath, '');
+    assert.equal(resolved.subtitleGeneration.ffmpegPath, '');
+    assert.equal(resolved.subtitleGeneration.ffprobePath, '');
+    assert.equal(warnings.length, 0);
+  }
+});
+
+test('subtitle generation shortcut can be customized or disabled', () => {
+  assert.equal(resolveConfig({}).resolved.shortcuts.openSubtitleGeneration, 'Ctrl+Shift+G');
+  assert.equal(
+    resolveConfig({ shortcuts: { openSubtitleGeneration: 'Ctrl+Alt+G' } }).resolved.shortcuts
+      .openSubtitleGeneration,
+    'Ctrl+Alt+G',
+  );
+  assert.equal(
+    resolveConfig({ shortcuts: { openSubtitleGeneration: null } }).resolved.shortcuts
+      .openSubtitleGeneration,
+    null,
+  );
+});
+
+test('dialogue detection paths are optional, validated, and editable in Settings', () => {
+  const { resolved, warnings } = resolveConfig({
+    subtitleGeneration: { vadModelPath: ' /models/silero.bin ', vadPath: ' /bin/vad ' },
+  });
+  assert.equal(resolved.subtitleGeneration.vadModelPath, '/models/silero.bin');
+  assert.equal(resolved.subtitleGeneration.vadPath, '/bin/vad');
+  assert.equal(warnings.length, 0);
+  for (const key of ['vadModelPath', 'vadPath'] as const) {
+    const field = buildConfigSettingsRegistry(resolved).find(
+      (entry) => entry.configPath === `subtitleGeneration.${key}`,
+    );
+    assert.equal(field?.category, 'integrations');
+    assert.equal(field?.restartBehavior, 'hot-reload');
+    assert.equal(resolveConfig({}).resolved.subtitleGeneration[key], '');
+    assert.equal(resolveConfig({ subtitleGeneration: { [key]: false } }).warnings.length, 1);
+  }
+});
diff --git a/src/config/resolve/subtitle-selection.test.ts b/src/config/resolve/subtitle-selection.test.ts
new file mode 100644
index 00000000..7a5be976
--- /dev/null
+++ b/src/config/resolve/subtitle-selection.test.ts
@@ -0,0 +1,63 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { resolveConfig } from '../resolve';
+import { DEFAULT_CONFIG } from '../definitions';
+import { buildConfigSettingsRegistry } from '../settings/registry';
+import { resolveConfiguredShortcuts } from '../../core/utils/shortcut-config';
+import {
+  compileSessionBindings,
+  buildPluginSessionBindingsArtifact,
+} from '../../core/services/session-bindings';
+
+function bindings(config: ReturnType<typeof resolveConfig>['resolved']) {
+  return compileSessionBindings({
+    shortcuts: resolveConfiguredShortcuts(config, DEFAULT_CONFIG),
+    keybindings: config.keybindings,
+    platform: 'linux',
+  });
+}
+
+test('subtitle selection is opt-in and enabling it compiles g-s for mpv and the overlay', () => {
+  const defaults = resolveConfig({}).resolved;
+  assert.equal(defaults.subtitleSelection.enabled, false);
+  assert.equal(defaults.shortcuts.openSubtitleSelection, 'g-s');
+  const find = (config: typeof defaults) =>
+    bindings(config).bindings.find(
+      (binding) =>
+        binding.actionType === 'session-action' && binding.actionId === 'openSubtitleSelection',
+    );
+  assert.equal(find(defaults), undefined);
+  const enabled = resolveConfig({ subtitleSelection: { enabled: true } }).resolved;
+  const binding = find(enabled);
+  assert.ok(binding);
+  assert.deepEqual(binding.key, { code: 'KeyG-KeyS', modifiers: [] });
+  assert.equal(bindings(enabled).warnings.length, 0);
+  const artifact = buildPluginSessionBindingsArtifact({
+    bindings: [binding],
+    warnings: [],
+    numericSelectionTimeoutMs: 1000,
+  });
+  assert.deepEqual(artifact.bindings[0], {
+    ...binding,
+    cliArgs: ['--session-action', '{"actionId":"openSubtitleSelection"}'],
+  });
+  enabled.subtitleSelection.enabled = false;
+  assert.equal(find(enabled), undefined);
+});
+
+test('subtitle selection settings are validated, hot reloadable, and the shortcut can be cleared', () => {
+  // @ts-expect-error Config files can contain invalid values at runtime.
+  const { resolved, warnings } = resolveConfig({ subtitleSelection: { enabled: 'yes' } });
+  assert.equal(resolved.subtitleSelection.enabled, false);
+  assert.equal(warnings.length, 1);
+  const field = buildConfigSettingsRegistry(resolved).find(
+    (entry) => entry.configPath === 'subtitleSelection.enabled',
+  );
+  assert.equal(field?.category, 'behavior');
+  assert.equal(field?.restartBehavior, 'hot-reload');
+  const cleared = resolveConfig({
+    subtitleSelection: { enabled: true },
+    shortcuts: { openSubtitleSelection: null },
+  }).resolved;
+  assert.equal(resolveConfiguredShortcuts(cleared, DEFAULT_CONFIG).openSubtitleSelection, null);
+});
diff --git a/src/config/settings/registry.test.ts b/src/config/settings/registry.test.ts
index f965e8e3..7a8229ad 100644
--- a/src/config/settings/registry.test.ts
+++ b/src/config/settings/registry.test.ts
@@ -275,6 +275,9 @@ test('settings registry routes playback-related integrations into integrations',
   assert.equal(field('subsync.replace').section, 'Subtitle Sync');
   assert.equal(field('tsukihime.apiBaseUrl').category, 'integrations');
   assert.equal(field('tsukihime.apiBaseUrl').section, 'TsukiHime');
+  assert.equal(field('tmdb.apiKey').category, 'integrations');
+  assert.equal(field('tmdb.apiKey').section, 'TMDB');
+  assert.equal(field('tmdb.apiKey').secret, true);
 });
 
 test('settings registry puts feature toggles first, then other toggles alphabetically', () => {
@@ -298,10 +301,12 @@ test('settings registry puts feature toggles first, then other toggles alphabeti
   ];
   assert.equal(miningSections[0], 'AnkiConnect');
 
-  const kikuLapis = fields.filter((candidate) => candidate.section === 'Kiku/Lapis Features');
+  const kikuLapis = fields.filter(
+    (candidate) => candidate.section === 'Kiku/Lapis/Senren Features',
+  );
   assert.deepEqual(
-    kikuLapis.slice(0, 2).map((candidate) => candidate.configPath),
-    ['ankiConnect.isLapis.enabled', 'ankiConnect.isKiku.enabled'],
+    kikuLapis.slice(0, 3).map((candidate) => candidate.configPath),
+    ['ankiConnect.isLapis.enabled', 'ankiConnect.isKiku.enabled', 'ankiConnect.isSenren.enabled'],
   );
 });
 
@@ -352,6 +357,7 @@ test('settings registry marks safe live config paths as hot-reloadable', () => {
     'ankiConnect.deck',
     'ankiConnect.media.normalizeAudio',
     'ankiConnect.media.mirrorMpvVolume',
+    'ankiConnect.media.reviewTiming',
     'ankiConnect.knownWords.highlightEnabled',
     'ankiConnect.knownWords.refreshMinutes',
     'ankiConnect.knownWords.addMinedWordsImmediately',
@@ -361,11 +367,13 @@ test('settings registry marks safe live config paths as hot-reloadable', () => {
     'ankiConnect.nPlusOne.minSentenceWords',
     'ankiConnect.fields.word',
     'ankiConnect.fields.audio',
+    'ankiConnect.fields.wordAudio',
     'ankiConnect.fields.image',
     'ankiConnect.fields.sentence',
     'ankiConnect.fields.miscInfo',
     'ankiConnect.isLapis.sentenceCardModel',
     'ankiConnect.isKiku.fieldGrouping',
+    'ankiConnect.isSenren.fieldGrouping',
   ]) {
     assert.equal(field(path).restartBehavior, 'hot-reload', path);
   }
diff --git a/src/config/settings/registry.ts b/src/config/settings/registry.ts
index 9230da0c..032136d3 100644
--- a/src/config/settings/registry.ts
+++ b/src/config/settings/registry.ts
@@ -1,9 +1,9 @@
+import { getConfigHotReloadField } from '../hot-reload';
 import type { ResolvedConfig } from '../../types/config';
 import type {
   ConfigSettingsCategory,
   ConfigSettingsControl,
   ConfigSettingsField,
-  ConfigSettingsRestartBehavior,
 } from '../../types/settings';
 import { CONFIG_OPTION_REGISTRY, DEFAULT_CONFIG } from '../definitions';
 import {
@@ -93,7 +93,12 @@ const JSON_OBJECT_FIELDS = new Set([
   'subtitleSidebar.css',
 ]);
 
-export const SECRET_PATHS = new Set(['ai.apiKey', 'jimaku.apiKey', 'anilist.accessToken']);
+export const SECRET_PATHS = new Set([
+  'ai.apiKey',
+  'jimaku.apiKey',
+  'tmdb.apiKey',
+  'anilist.accessToken',
+]);
 
 const COLOR_SUFFIXES = new Set(['Color', 'color', 'backgroundColor', 'singleColor']);
 const SUBTITLE_CSS_MANAGED_CONFIG_PATHS = new Set([
@@ -131,10 +136,11 @@ const SECTION_ORDER = new Map<string, number>(
     'AnkiConnect',
     'Note Fields',
     'Media Capture',
-    'Kiku/Lapis Features',
+    'Kiku/Lapis/Senren Features',
     'Anki AI',
     'AnkiConnect Proxy',
     'Jimaku',
+    'TMDB',
     'Subtitle Sync',
     'MPV Keybindings',
     'Overlay Shortcuts',
@@ -163,6 +169,7 @@ const PATH_ORDER = new Map<string, number>(
     'ankiConnect.proxy.enabled',
     'ankiConnect.isLapis.enabled',
     'ankiConnect.isKiku.enabled',
+    'ankiConnect.isSenren.enabled',
     'subtitleStyle.knownWordColor',
     'ankiConnect.knownWords.matureThresholdDays',
     'subtitleStyle.knownWordMaturityColors.new',
@@ -221,6 +228,7 @@ const LABEL_OVERRIDES: Record<string, string> = {
   'ankiConnect.nPlusOne.enabled': 'Enabled',
   'ankiConnect.isLapis.enabled': 'Enable Lapis Features',
   'ankiConnect.isKiku.enabled': 'Enable Kiku Features',
+  'ankiConnect.isSenren.enabled': 'Enable Senren Features',
   'ankiConnect.lapisKiku.wordCardKind': 'Word Card Type',
   'stats.toggleKey': 'Toggle Stats Overlay',
   'shortcuts.openCharacterDictionaryManager': 'Open Character Dictionary Manager',
@@ -244,6 +252,7 @@ const LABEL_OVERRIDES: Record<string, string> = {
   'mpv.aniskipEnabled': 'Enable AniSkip',
   'mpv.aniskipButtonKey': 'AniSkip Button Key',
   'ankiConnect.media.mirrorMpvVolume': 'Mirror mpv Volume',
+  'ankiConnect.media.reviewTiming': 'Review Media Timing',
   'discordPresence.updateIntervalMs': 'Update Interval (ms)',
 };
 
@@ -251,7 +260,9 @@ const DESCRIPTION_OVERRIDES: Record<string, string> = {
   'ankiConnect.pollingRate':
     'Polling interval in milliseconds. Ignored while the local AnkiConnect proxy is enabled because push-based enrichment is used instead.',
   'ankiConnect.isKiku.enabled':
-    'Enable Kiku-specific mining behavior. Kiku supersedes Lapis: Lapis features still work, and Kiku adds duplicate handling and field grouping.',
+    'Enable Kiku-specific mining behavior. Kiku supersedes Lapis: Lapis features still work, and Kiku adds duplicate handling and field grouping. Mutually exclusive with Senren.',
+  'ankiConnect.isSenren.enabled':
+    'Enable Senren-specific duplicate handling: field grouping merges duplicates into Senren scene-switching markup (including miscInfo grouping). Mutually exclusive with Kiku; only one can be enabled at a time.',
   'ankiConnect.isLapis.enabled':
     'Enable Lapis-specific mining behavior and sentence-card model targeting. When Kiku is enabled, Lapis features still work and Kiku-specific features are added on top.',
   'ankiConnect.isLapis.sentenceCardModel':
@@ -322,6 +333,7 @@ function humanizePath(path: string): string {
     .replace(/\bmpv\b/i, 'mpv')
     .replace(/\byomitan\b/i, 'Yomitan')
     .replace(/\bjimaku\b/i, 'Jimaku')
+    .replace(/\btmdb\b/i, 'TMDB')
     .replace(/\banilist\b/i, 'AniList')
     .replace(/\banki\b/i, 'Anki');
   return spaced.charAt(0).toUpperCase() + spaced.slice(1);
@@ -407,9 +419,10 @@ function categoryAndSection(path: string): { category: ConfigSettingsCategory; s
   if (
     path.startsWith('ankiConnect.isKiku.') ||
     path.startsWith('ankiConnect.isLapis.') ||
+    path.startsWith('ankiConnect.isSenren.') ||
     path.startsWith('ankiConnect.lapisKiku.')
   ) {
-    return { category: 'mining-anki', section: 'Kiku/Lapis Features' };
+    return { category: 'mining-anki', section: 'Kiku/Lapis/Senren Features' };
   }
   if (path.startsWith('ankiConnect.ai.')) {
     return { category: 'mining-anki', section: 'Anki AI' };
@@ -436,12 +449,18 @@ function categoryAndSection(path: string): { category: ConfigSettingsCategory; s
   if (path.startsWith('mpv.') || path.startsWith('youtube.')) {
     return { category: 'behavior', section: topSection(path) };
   }
-  if (path.startsWith('jimaku.') || path.startsWith('tsukihime.')) {
+  if (path.startsWith('jimaku.') || path.startsWith('tsukihime.') || path.startsWith('tmdb.')) {
     return { category: 'integrations', section: topSection(path) };
   }
   if (path.startsWith('subsync.')) {
     return { category: 'integrations', section: topSection(path) };
   }
+  if (path.startsWith('subtitleSelection.')) {
+    return { category: 'behavior', section: 'Subtitle Selection' };
+  }
+  if (path.startsWith('subtitleGeneration.')) {
+    return { category: 'integrations', section: 'Japanese Subtitle Generation' };
+  }
   if (path === 'stats.toggleKey' || path === 'stats.markWatchedKey') {
     return { category: 'input', section: 'Overlay Shortcuts' };
   }
@@ -501,6 +520,7 @@ function topSection(path: string): string {
     subsync: 'Subtitle Sync',
     texthooker: 'Texthooker',
     tsukihime: 'TsukiHime',
+    tmdb: 'TMDB',
     updates: 'Updates',
     websocket: 'WebSocket server',
     yomitan: 'Yomitan',
@@ -614,6 +634,8 @@ function subsectionForPath(path: string): string | undefined {
       leaf === 'openRuntimeOptions' ||
       leaf === 'openJimaku' ||
       leaf === 'openTsukihime' ||
+      leaf === 'openSubtitleSelection' ||
+      leaf === 'openSubtitleGeneration' ||
       leaf === 'openSessionHelp' ||
       leaf === 'openControllerSelect' ||
       leaf === 'openControllerDebug'
@@ -683,50 +705,6 @@ function compareFields(a: ConfigSettingsField, b: ConfigSettingsField): number {
   return a.configPath.localeCompare(b.configPath);
 }
 
-function restartBehaviorForPath(path: string): ConfigSettingsRestartBehavior {
-  if (
-    path === 'keybindings' ||
-    pathStartsWith(path, 'shortcuts') ||
-    pathStartsWith(path, 'subtitleStyle') ||
-    pathStartsWith(path, 'subtitleSidebar') ||
-    path === 'secondarySub.defaultMode' ||
-    path === 'ankiConnect.deck' ||
-    path === 'ankiConnect.ai.enabled' ||
-    path === 'ankiConnect.media.normalizeAudio' ||
-    path === 'ankiConnect.media.mirrorMpvVolume' ||
-    path === 'ankiConnect.behavior.autoUpdateNewCards' ||
-    path === 'ankiConnect.knownWords.highlightEnabled' ||
-    path === 'ankiConnect.knownWords.refreshMinutes' ||
-    path === 'ankiConnect.knownWords.addMinedWordsImmediately' ||
-    path === 'ankiConnect.knownWords.matchMode' ||
-    path === 'ankiConnect.knownWords.decks' ||
-    path === 'ankiConnect.nPlusOne.enabled' ||
-    path === 'ankiConnect.nPlusOne.minSentenceWords' ||
-    path === 'ankiConnect.fields.word' ||
-    path === 'ankiConnect.fields.audio' ||
-    path === 'ankiConnect.fields.image' ||
-    path === 'ankiConnect.fields.sentence' ||
-    path === 'ankiConnect.fields.miscInfo' ||
-    path === 'ankiConnect.isLapis.sentenceCardModel' ||
-    path === 'ankiConnect.isKiku.fieldGrouping' ||
-    path === 'ankiConnect.lapisKiku.wordCardKind' ||
-    path === 'mpv.aniskipEnabled' ||
-    path === 'mpv.aniskipButtonKey' ||
-    path === 'stats.toggleKey' ||
-    path === 'stats.markWatchedKey' ||
-    path === 'logging.level' ||
-    path === 'logging.rotation' ||
-    pathStartsWith(path, 'logging.files') ||
-    pathStartsWith(path, 'notifications') ||
-    path === 'youtube.primarySubLanguages' ||
-    pathStartsWith(path, 'jimaku') ||
-    pathStartsWith(path, 'subsync')
-  ) {
-    return 'hot-reload';
-  }
-  return 'restart';
-}
-
 function fieldForLeaf(leaf: Leaf): ConfigSettingsField {
   const option = OPTION_BY_PATH.get(leaf.path);
   const { category, section } = categoryAndSection(leaf.path);
@@ -745,7 +723,7 @@ function fieldForLeaf(leaf: Leaf): ConfigSettingsField {
       ? { enumValues: option.settingsEnumValues ?? option.enumValues }
       : {}),
     ...(option?.enumLabels ? { enumLabels: option.enumLabels } : {}),
-    restartBehavior: restartBehaviorForPath(leaf.path),
+    restartBehavior: getConfigHotReloadField(leaf.path) ? 'hot-reload' : 'restart',
     advanced:
       leaf.path.startsWith('controller.') ||
       leaf.path.startsWith('immersionTracking.retention.') ||
diff --git a/src/core/services/__tests__/stats-server.test.ts b/src/core/services/__tests__/stats-server.test.ts
index bc9f3674..7e3bf1ed 100644
--- a/src/core/services/__tests__/stats-server.test.ts
+++ b/src/core/services/__tests__/stats-server.test.ts
@@ -5,8 +5,13 @@ import http from 'node:http';
 import os from 'node:os';
 import path from 'node:path';
 import type { AddressInfo } from 'node:net';
-import { createStatsApp, startStatsServer } from '../stats-server.js';
+import {
+  createStatsApp,
+  startNodeHttpServer,
+  startStatsServerWithRuntime,
+} from '../stats-server.js';
 import type { ImmersionTrackerService } from '../immersion-tracker-service.js';
+import { INCOMPATIBLE_PROVIDER_MERGE_MESSAGE } from '../immersion-tracker/anime-merge.js';
 import {
   clearRetimedSecondarySubtitleCache,
   resolveRetimedSecondarySubtitleTextFromSidecar,
@@ -307,6 +312,7 @@ function createMockTracker(
     getKanjiOccurrences: async () => OCCURRENCES,
     getAnimeLibrary: async () => ANIME_LIBRARY,
     getAnimeDetail: async (animeId: number) => (animeId === 1 ? ANIME_DETAIL : null),
+    hasAnime: async (animeId: number) => animeId === 1,
     getAnimeEpisodes: async () => ANIME_EPISODES,
     getAnimeAnilistEntries: async () => [],
     getAnimeWords: async () => ANIME_WORDS,
@@ -440,6 +446,73 @@ async function withFakeAnkiConnect<T>(
 }
 
 describe('stats server API routes', () => {
+  it('rejects untrusted mutation requests before merging anime', async () => {
+    let merges = 0;
+    const app = createStatsApp(
+      createMockTracker({
+        mergeAnime: async () => {
+          merges += 1;
+          return { survivingAnimeId: 1, mergedAnimeIds: [2], movedVideos: 1 };
+        },
+      }),
+    );
+    const rejectedHeaders: Record<string, string>[] = [
+      { Origin: 'https://attacker.example', 'Content-Type': 'text/plain' },
+      { Origin: 'https://attacker.example', 'Content-Type': 'application/json' },
+      { Origin: 'null', 'Content-Type': 'application/json' },
+      { Origin: 'http://localhost:4321', 'Content-Type': 'application/json' },
+      { Origin: 'http://localhost/', 'Content-Type': 'application/json' },
+      { 'Sec-Fetch-Site': 'cross-site', 'Content-Type': 'application/json' },
+      { Host: 'attacker.example', 'Content-Type': 'application/json' },
+    ];
+    for (const headers of rejectedHeaders) {
+      const response = await app.request('/api/stats/anime/1/merge', {
+        method: 'POST',
+        headers,
+        body: JSON.stringify({ sourceAnimeIds: [2] }),
+      });
+      assert.equal(response.status, 403, JSON.stringify(headers));
+    }
+    assert.equal(merges, 0);
+    for (const origin of [undefined, 'http://localhost']) {
+      const headers = new Headers({ 'Content-Type': 'application/json; charset=utf-8' });
+      if (origin) headers.set('Origin', origin);
+      const response = await app.request('/api/stats/anime/1/merge', {
+        method: 'POST',
+        headers,
+        body: JSON.stringify({ sourceAnimeIds: [2] }),
+      });
+      assert.equal(response.status, 200);
+    }
+    assert.equal(merges, 2);
+  });
+
+  it('requires JSON for mutation bodies and preserves bodyless deletion', async () => {
+    let deletions = 0;
+    const app = createStatsApp(
+      createMockTracker({
+        deleteSession: async () => {
+          deletions += 1;
+        },
+      }),
+    );
+    const invalid = await app.request('/api/stats/sessions/1', {
+      method: 'DELETE',
+      body: '{}',
+    });
+    assert.equal(invalid.status, 415);
+    assert.equal(deletions, 0);
+    const valid = await app.request('/api/stats/sessions/1', { method: 'DELETE' });
+    assert.equal(valid.status, 200);
+    assert.equal(deletions, 1);
+    const rebound = await app.request('http://attacker.example/api/stats/sessions/1', {
+      method: 'DELETE',
+      headers: { Origin: 'http://attacker.example' },
+    });
+    assert.equal(rebound.status, 403);
+    assert.equal(deletions, 1);
+  });
+
   it('GET /api/stats/overview returns overview data', async () => {
     const app = createStatsApp(createMockTracker());
     const res = await app.request('/api/stats/overview');
@@ -1004,6 +1077,23 @@ describe('stats server API routes', () => {
     assert.equal(seenLimit, 500);
   });
 
+  it('GET /api/stats/vocabulary floors fractional pagination limits', async () => {
+    let seenLimit = 0;
+    const app = createStatsApp(
+      createMockTracker({
+        getVocabularyStats: async (limit?: number) => {
+          seenLimit = limit ?? 0;
+          return VOCABULARY_STATS;
+        },
+      }),
+    );
+
+    const res = await app.request('/api/stats/vocabulary?limit=12.9');
+
+    assert.equal(res.status, 200);
+    assert.equal(seenLimit, 12);
+  });
+
   it('GET /api/stats/vocabulary passes excludePos to tracker', async () => {
     let seenArgs: unknown[] = [];
     const app = createStatsApp(
@@ -1132,7 +1222,7 @@ describe('stats server API routes', () => {
       body: JSON.stringify({ dryRun: false, lookbackDays: null }),
     });
 
-    assert.equal(res.status, 415);
+    assert.equal(res.status, 403);
     assert.equal(cleanupCalls, 0);
   });
 
@@ -1351,7 +1441,7 @@ describe('stats server API routes', () => {
       }),
     );
 
-    for (const anilistId of [-1, 0, 1.5, '12', true, undefined]) {
+    for (const anilistId of [-1, 0, 1.5, 9_007_199_254_740_992, '12', true, undefined]) {
       const res = await app.request('/api/stats/anime/1/anilist', {
         method: 'PATCH',
         headers: { 'Content-Type': 'application/json' },
@@ -1449,6 +1539,74 @@ describe('stats server API routes', () => {
     assert.equal(res.status, 404);
   });
 
+  it('resource routes reject fractional ids before calling dependencies', async () => {
+    const dependencyCalls: string[] = [];
+    const originalFetch = globalThis.fetch;
+    globalThis.fetch = async () => {
+      dependencyCalls.push('fetch');
+      return new Response('{}', { status: 200 });
+    };
+
+    try {
+      const app = createStatsApp(
+        createMockTracker({
+          getWordDetail: async () => {
+            dependencyCalls.push('getWordDetail');
+            return null;
+          },
+          getSessionEvents: async () => {
+            dependencyCalls.push('getSessionEvents');
+            return [];
+          },
+          getEpisodeSessions: async () => {
+            dependencyCalls.push('getEpisodeSessions');
+            return [];
+          },
+          getAnimeCoverArt: async () => {
+            dependencyCalls.push('getAnimeCoverArt');
+            return null;
+          },
+          ensureAnimeCoverArt: async () => {
+            dependencyCalls.push('ensureAnimeCoverArt');
+            return false;
+          },
+          setVideoWatched: async () => {
+            dependencyCalls.push('setVideoWatched');
+          },
+          reassignAnimeAnilist: async () => {
+            dependencyCalls.push('reassignAnimeAnilist');
+          },
+        }),
+      );
+
+      const responses = await Promise.all([
+        app.request('/api/stats/vocabulary/1.9/detail'),
+        app.request('/api/stats/sessions/1.9/events'),
+        app.request('/api/stats/episode/1.9/detail'),
+        app.request('/api/stats/anime/1.9/cover'),
+        app.request('/api/stats/media/1.9/watched', {
+          method: 'PATCH',
+          headers: { 'Content-Type': 'application/json' },
+          body: '{"watched":true}',
+        }),
+        app.request('/api/stats/anime/1.9/anilist', {
+          method: 'PATCH',
+          headers: { 'Content-Type': 'application/json' },
+          body: '{"anilistId":21858}',
+        }),
+        app.request('/api/stats/anki/browse?noteId=1.9', { method: 'POST' }),
+      ]);
+
+      assert.deepEqual(
+        responses.map((response) => response.status),
+        [400, 400, 400, 400, 400, 400, 400],
+      );
+      assert.deepEqual(dependencyCalls, []);
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+
   it('POST /api/stats/covers batches stored cover art and backfills missing anime art in the background', async () => {
     let ensureCoverArtCalls = 0;
     const ensureAnimeCoverArtCalls: number[] = [];
@@ -1505,6 +1663,58 @@ describe('stats server API routes', () => {
     assert.deepEqual(ensureAnimeCoverArtCalls, [99999]);
   });
 
+  it('JSON id lists reject malformed members before side effects', async () => {
+    const dependencyCalls: string[] = [];
+    const originalFetch = globalThis.fetch;
+    globalThis.fetch = async () => {
+      dependencyCalls.push('fetch');
+      return new Response('{}', { status: 200 });
+    };
+
+    try {
+      const app = createStatsApp(
+        createMockTracker({
+          deleteSessions: async () => {
+            dependencyCalls.push('deleteSessions');
+          },
+          mergeAnime: async () => {
+            dependencyCalls.push('mergeAnime');
+            return { survivingAnimeId: 7, mergedAnimeIds: [], movedVideos: 0 };
+          },
+          getAnimeCoverArt: async () => {
+            dependencyCalls.push('getAnimeCoverArt');
+            return null;
+          },
+          ensureAnimeCoverArt: async () => {
+            dependencyCalls.push('ensureAnimeCoverArt');
+            return false;
+          },
+        }),
+      );
+      const request = async (path: string, body: string, method = 'POST'): Promise<Response> =>
+        await app.request(path, {
+          method,
+          headers: { 'Content-Type': 'application/json' },
+          body,
+        });
+
+      const responses = await Promise.all([
+        request('/api/stats/sessions', '{"sessionIds":[4,1.9,7]}', 'DELETE'),
+        request('/api/stats/anime/7/merge', '{"sourceAnimeIds":[8,"9"]}'),
+        request('/api/stats/covers', '{"animeIds":[1,1.9]}'),
+        request('/api/stats/anki/notesInfo', '{"noteIds":[1,1.9]}'),
+      ]);
+
+      assert.deepEqual(
+        responses.map((response) => response.status),
+        [400, 400, 400, 400],
+      );
+      assert.deepEqual(dependencyCalls, []);
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+
   it('POST /api/stats/covers limits concurrent missing anime cover backfills', async () => {
     let activeBackfills = 0;
     let maxActiveBackfills = 0;
@@ -1762,6 +1972,60 @@ describe('stats server API routes', () => {
     });
   });
 
+  it('POST /api/stats/mine-card treats a zero media duration cap as unlimited', async () => {
+    await withTempDir(async (dir) => {
+      const sourcePath = path.join(dir, 'episode.mkv');
+      fs.writeFileSync(sourcePath, 'fake media');
+      const audioRanges: Array<{ start: number; end: number; padding: number | undefined }> = [];
+      const scenarios = [
+        { maxMediaDuration: 0, expectedEnd: 12 },
+        { maxMediaDuration: 1, expectedEnd: 11 },
+      ];
+
+      for (const scenario of scenarios) {
+        const app = createStatsApp(createMockTracker(), {
+          addYomitanNote: async () => null,
+          createMediaGenerator: () => ({
+            generateAudio: async (_path, start, end, padding) => {
+              audioRanges.push({ start, end, padding });
+              return Buffer.from('audio');
+            },
+            generateScreenshot: async () => null,
+            generateAnimatedImage: async () => null,
+          }),
+          ankiConnectConfig: {
+            deck: 'Mining',
+            media: {
+              generateAudio: true,
+              generateImage: false,
+              audioPadding: 0.25,
+              maxMediaDuration: scenario.maxMediaDuration,
+            },
+          },
+        });
+
+        const res = await app.request('/api/stats/mine-card?mode=word', {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({
+            sourcePath,
+            startMs: 10_000,
+            endMs: 12_000,
+            sentence: '猫を見た',
+            word: '猫',
+          }),
+        });
+
+        assert.equal(res.status, 502);
+        assert.deepEqual(audioRanges.at(-1), {
+          start: 10,
+          end: scenario.expectedEnd,
+          padding: 0.25,
+        });
+      }
+    });
+  });
+
   it('POST /api/stats/mine-card requires a non-empty word in word mode', async () => {
     await withTempDir(async (dir) => {
       const sourcePath = path.join(dir, 'episode.mkv');
@@ -3262,6 +3526,46 @@ Aligned English subtitle
     assert.equal(deleteCalls, 0);
   });
 
+  it('DELETE /api/stats/sessions rejects a partly invalid id list without deleting', async () => {
+    let deleteCalls = 0;
+    const app = createStatsApp(
+      createMockTracker({
+        deleteSessions: async () => {
+          deleteCalls += 1;
+        },
+      }),
+    );
+
+    const res = await app.request('/api/stats/sessions', {
+      method: 'DELETE',
+      headers: { 'Content-Type': 'application/json' },
+      body: '{"sessionIds":[4,1.9,7]}',
+    });
+
+    assert.equal(res.status, 400);
+    assert.equal(deleteCalls, 0);
+  });
+
+  it('DELETE /api/stats/sessions deduplicates valid ids', async () => {
+    let deletedSessionIds: number[] = [];
+    const app = createStatsApp(
+      createMockTracker({
+        deleteSessions: async (sessionIds: number[]) => {
+          deletedSessionIds = sessionIds;
+        },
+      }),
+    );
+
+    const res = await app.request('/api/stats/sessions', {
+      method: 'DELETE',
+      headers: { 'Content-Type': 'application/json' },
+      body: '{"sessionIds":[4,4,7]}',
+    });
+
+    assert.equal(res.status, 200);
+    assert.deepEqual(deletedSessionIds, [4, 7]);
+  });
+
   it('DELETE /api/stats/anime/:animeId deletes the whole library entry', async () => {
     let deletedAnimeId: number | null = null;
     const app = createStatsApp(
@@ -3295,6 +3599,33 @@ Aligned English subtitle
     assert.equal(deleteCalls, 0);
   });
 
+  it('DELETE /api/stats/anime/:animeId rejects malformed anime ids before deleting', async () => {
+    let deletedAnimeId: number | null = null;
+    const app = createStatsApp(
+      createMockTracker({
+        deleteAnime: async (animeId: number) => {
+          deletedAnimeId = animeId;
+        },
+      }),
+    );
+
+    for (const animeId of [
+      '1.9',
+      '1.0',
+      '1e2',
+      '9007199254740992',
+      '1%0A',
+      '%201',
+      '01',
+      '+1',
+      '0x1',
+    ]) {
+      const res = await app.request(`/api/stats/anime/${animeId}`, { method: 'DELETE' });
+      assert.equal(res.status, 400, `accepted malformed anime id: ${animeId}`);
+    }
+    assert.equal(deletedAnimeId, null);
+  });
+
   it('POST /api/stats/anime/:animeId/merge folds the given entries into the target', async () => {
     let merged: { targetAnimeId: number; sourceAnimeIds: number[] } | null = null;
     const app = createStatsApp(
@@ -3400,6 +3731,25 @@ Aligned English subtitle
     assert.equal(res.status, 404);
   });
 
+  it('POST /api/stats/anime/:animeId/merge rejects mixed AniList and TMDB entries as 409', async () => {
+    const app = createStatsApp(
+      createMockTracker({
+        mergeAnime: async () => {
+          throw new Error(INCOMPATIBLE_PROVIDER_MERGE_MESSAGE);
+        },
+      } as Partial<ImmersionTrackerService>),
+    );
+
+    const res = await app.request('/api/stats/anime/7/merge', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: '{"sourceAnimeIds":[8]}',
+    });
+
+    assert.equal(res.status, 409);
+    assert.deepEqual(await res.json(), { error: INCOMPATIBLE_PROVIDER_MERGE_MESSAGE });
+  });
+
   it('PATCH /api/stats/media/:videoId/anime reports an unknown target as 404', async () => {
     const app = createStatsApp(
       createMockTracker({
@@ -3737,102 +4087,335 @@ Aligned English subtitle
     assert.equal(ensureCalls, 1);
   });
 
-  it('starts the stats server with Bun.serve', () => {
-    type BunRuntime = {
-      Bun: {
-        serve: (options: { fetch: unknown; port: number; hostname: string }) => {
-          stop: () => void;
-        };
-      };
-    };
-
-    const bun = globalThis as typeof globalThis & BunRuntime;
-    const originalServe = bun.Bun.serve;
-    let servedWith: { fetch: unknown; port: number; hostname: string } | null = null;
+  it('starts and stops the stats server with Bun.serve', async () => {
+    const servedOptions: Array<{ fetch: unknown; port: number; hostname: string }> = [];
     let stopCalls = 0;
-
-    bun.Bun.serve = (options: { fetch: unknown; port: number; hostname: string }) => {
-      servedWith = options;
-      return {
-        stop: () => {
-          stopCalls += 1;
-        },
-      };
-    };
-
-    try {
-      const server = startStatsServer({
+    const server = await startStatsServerWithRuntime(
+      {
         port: 3210,
         staticDir: fs.mkdtempSync(path.join(os.tmpdir(), 'subminer-stats-server-start-')),
         tracker: createMockTracker(),
-      });
+      },
+      {
+        bunServe: (options) => {
+          servedOptions.push(options);
+          return {
+            stop: () => {
+              stopCalls += 1;
+            },
+          };
+        },
+      },
+    );
 
-      if (servedWith === null) {
-        throw new Error('expected Bun.serve to be called');
-      }
-
-      const servedOptions = servedWith as {
-        fetch: unknown;
-        port: number;
-        hostname: string;
-      };
-      assert.equal(servedOptions.port, 3210);
-      assert.equal(servedOptions.hostname, '127.0.0.1');
-      assert.equal(typeof servedOptions.fetch, 'function');
-
-      server.close();
-      assert.equal(stopCalls, 1);
-    } finally {
-      bun.Bun.serve = originalServe;
+    const servedWith = servedOptions[0];
+    if (!servedWith) {
+      throw new Error('expected Bun.serve to be called');
     }
+
+    assert.equal(servedWith.port, 3210);
+    assert.equal(servedWith.hostname, '127.0.0.1');
+    assert.equal(typeof servedWith.fetch, 'function');
+
+    await Promise.all([server.close(), server.close()]);
+    assert.equal(stopCalls, 1);
   });
 
-  it('falls back to node:http when Bun.serve is unavailable', () => {
-    type BunRuntime = {
-      Bun: {
-        serve?: (options: { fetch: unknown; port: number; hostname: string }) => {
-          stop: () => void;
-        };
-      };
-    };
-
-    const bun = globalThis as typeof globalThis & BunRuntime;
-    const originalServe = bun.Bun.serve;
-    const originalCreateServer = http.createServer;
-    let listenedWith: { port: number; hostname: string } | null = null;
+  it('waits for node:http listening and converts startup errors into rejections', async () => {
+    const app = createStatsApp(createMockTracker());
+    const listeningServer = http.createServer();
     let closeCalls = 0;
-    bun.Bun.serve = undefined;
-    (
-      http as typeof http & {
-        createServer: typeof http.createServer;
-      }
-    ).createServer = (() =>
-      ({
-        listen: (port: number, hostname: string) => {
-          listenedWith = { port, hostname };
-        },
-        close: () => {
+    Object.defineProperties(listeningServer, {
+      listen: {
+        value: () => listeningServer,
+      },
+      close: {
+        value: (callback?: (error?: Error) => void) => {
           closeCalls += 1;
+          callback?.();
+          return listeningServer;
         },
-      }) as unknown as ReturnType<typeof http.createServer>) as typeof http.createServer;
+      },
+    });
+
+    let startupSettled = false;
+    const startup = startNodeHttpServer(
+      app,
+      {
+        port: 3210,
+        staticDir: fs.mkdtempSync(path.join(os.tmpdir(), 'subminer-stats-server-node-events-')),
+        tracker: createMockTracker(),
+      },
+      () => listeningServer,
+    );
+    void startup.finally(() => {
+      startupSettled = true;
+    });
+    await Promise.resolve();
+    assert.equal(startupSettled, false);
+
+    listeningServer.emit('listening');
+    const handle = await startup;
+    await Promise.all([handle.close(), handle.close()]);
+    assert.equal(closeCalls, 1);
+
+    const failingServer = http.createServer();
+    Object.defineProperty(failingServer, 'listen', {
+      value: () => failingServer,
+    });
+    const failedStartup = startNodeHttpServer(
+      app,
+      {
+        port: 3210,
+        staticDir: fs.mkdtempSync(path.join(os.tmpdir(), 'subminer-stats-server-node-error-')),
+        tracker: createMockTracker(),
+      },
+      () => failingServer,
+    );
+    failingServer.emit('error', Object.assign(new Error('address in use'), { code: 'EADDRINUSE' }));
+    await assert.rejects(
+      failedStartup,
+      (error: NodeJS.ErrnoException) => error.code === 'EADDRINUSE',
+    );
+  });
+
+  it('starts, rejects address conflicts, and stops through real node:http sockets', async () => {
+    const app = createStatsApp(createMockTracker());
+    const server = await startNodeHttpServer(app, {
+      port: 0,
+      staticDir: fs.mkdtempSync(path.join(os.tmpdir(), 'subminer-stats-server-node-')),
+      tracker: createMockTracker(),
+    });
+    await Promise.all([server.close(), server.close()]);
+
+    const blocker = http.createServer();
+    await new Promise<void>((resolve, reject) => {
+      blocker.once('error', reject);
+      blocker.listen(0, '127.0.0.1', resolve);
+    });
+    const address = blocker.address();
+    if (!address || typeof address === 'string') {
+      throw new Error('expected blocker to listen on a TCP port');
+    }
 
     try {
-      const server = startStatsServer({
-        port: 0,
-        staticDir: fs.mkdtempSync(path.join(os.tmpdir(), 'subminer-stats-server-node-')),
-        tracker: createMockTracker(),
-      });
-
-      assert.deepEqual(listenedWith, { port: 0, hostname: '127.0.0.1' });
-      server.close();
-      assert.equal(closeCalls, 1);
+      await assert.rejects(
+        startNodeHttpServer(app, {
+          port: address.port,
+          staticDir: fs.mkdtempSync(path.join(os.tmpdir(), 'subminer-stats-server-node-error-')),
+          tracker: createMockTracker(),
+        }),
+        (error: NodeJS.ErrnoException) => error.code === 'EADDRINUSE',
+      );
     } finally {
-      bun.Bun.serve = originalServe;
-      (
-        http as typeof http & {
-          createServer: typeof http.createServer;
-        }
-      ).createServer = originalCreateServer;
+      await new Promise<void>((resolve, reject) => {
+        blocker.close((error) => {
+          if (error) reject(error);
+          else resolve();
+        });
+      });
     }
   });
+
+  it('enforces request safety through node:http without rejecting bodyless DELETEs', async () => {
+    await withTempDir(async (staticDir) => {
+      let deletions = 0;
+      const tracker = createMockTracker({
+        deleteSession: async () => {
+          deletions += 1;
+        },
+      });
+      const listener = http.createServer();
+      const server = await startNodeHttpServer(
+        createStatsApp(tracker),
+        { port: 0, staticDir, tracker },
+        (handler) => {
+          listener.on('request', handler);
+          return listener;
+        },
+      );
+      try {
+        const address = listener.address();
+        assert.ok(address && typeof address !== 'string');
+        const origin = `http://127.0.0.1:${address.port}`;
+        const url = `${origin}/api/stats/sessions/1`;
+        for (const headers of [undefined, { 'Content-Length': '0' }]) {
+          const response = await fetch(url, { method: 'DELETE', headers });
+          assert.equal(response.status, 200);
+          await response.arrayBuffer();
+        }
+        assert.equal(deletions, 2);
+        for (const headers of [
+          new Headers({ Origin: 'https://attacker.example' }),
+          new Headers({ Origin: 'null' }),
+          new Headers({ Host: 'attacker.example' }),
+          new Headers({ 'Sec-Fetch-Site': 'same-site' }),
+        ]) {
+          const response = await fetch(url, { method: 'DELETE', headers });
+          assert.equal(response.status, 403, JSON.stringify(headers));
+          await response.arrayBuffer();
+        }
+        const invalid = await fetch(url, { method: 'DELETE', body: '{}' });
+        assert.equal(invalid.status, 415);
+        await invalid.arrayBuffer();
+        assert.equal(deletions, 2);
+        const valid = await fetch(url, {
+          method: 'DELETE',
+          headers: { Origin: origin, 'Content-Type': 'application/json' },
+          body: '{}',
+        });
+        assert.equal(valid.status, 200);
+        await valid.arrayBuffer();
+        assert.equal(deletions, 3);
+      } finally {
+        await server.close();
+      }
+    });
+  });
+});
+
+it('TMDB reassignment returns 404 for a missing library entry before fetching details', async () => {
+  const assignments: number[] = [];
+  let fetches = 0;
+  const app = createStatsApp(
+    createMockTracker({
+      reassignAnimeTmdb: async (animeId: number) => {
+        assignments.push(animeId);
+        return { animeId, mergedAnimeIds: [] };
+      },
+    }),
+    {
+      tmdbClient: {
+        search: async () => [],
+        getDetails: async () => {
+          fetches += 1;
+          return {
+            tmdbId: 12,
+            tmdbType: 'tv',
+            titleEnglish: 'Drama',
+            titleNative: null,
+            description: null,
+            posterUrl: null,
+            episodesTotal: 10,
+            year: null,
+            originalLanguage: 'ja',
+            isAnimation: false,
+            allTitles: ['Drama'],
+          };
+        },
+      },
+    },
+  );
+  const request = (animeId: number) =>
+    app.request(`/api/stats/anime/${animeId}/tmdb`, {
+      method: 'PATCH',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ tmdbId: 12, tmdbType: 'tv' }),
+    });
+  assert.equal((await request(99999)).status, 404);
+  assert.equal(fetches, 0);
+  assert.deepEqual(assignments, []);
+  const response = await request(1);
+  assert.equal(response.status, 200);
+  assert.deepEqual(await response.json(), { ok: true });
+  assert.equal(fetches, 1);
+  assert.deepEqual(assignments, [1]);
+});
+
+for (const outcome of ['success', 'unavailable', 'throws', 'no-field'] as const) {
+  it(`stats word mining updates full sentence furigana without media (${outcome})`, async () => {
+    await withTempDir(async (dir) => {
+      const sourcePath = path.join(dir, 'episode.mkv');
+      fs.writeFileSync(sourcePath, 'fake media');
+      await withFakeAnkiConnect(
+        async (requests, url) => {
+          let calls = 0;
+          const app = createStatsApp(createMockTracker(), {
+            ankiConnectConfig: {
+              url,
+              deck: 'Mining',
+              media: { generateAudio: false, generateImage: false },
+            },
+            addYomitanNote: async () => 12345,
+            generateSentenceFurigana: async (text, word) => {
+              calls++;
+              assert.equal(text, '猫を見た。');
+              assert.equal(word, '猫');
+              if (outcome === 'throws') throw new Error('parser unavailable');
+              return outcome === 'success' ? '<b> 猫[ねこ]</b>を 見[み]た。' : null;
+            },
+          });
+          const response = await app.request('/api/stats/mine-card?mode=word', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+              sourcePath,
+              startMs: 1000,
+              endMs: 2000,
+              sentence: '猫を見た。',
+              word: '猫',
+            }),
+          });
+          assert.equal(response.status, 200);
+          const fields = requests.find((request) => request.action === 'updateNoteFields')?.params
+            ?.note?.fields;
+          assert.equal(fields?.Sentence, '<b>猫</b>を見た。');
+          assert.equal(
+            fields?.sentencefurigana,
+            outcome === 'no-field'
+              ? undefined
+              : outcome === 'success'
+                ? '<b> 猫[ねこ]</b>を 見[み]た。'
+                : '',
+          );
+          assert.equal(calls, outcome === 'no-field' ? 0 : 1);
+        },
+        {
+          notesInfoFields: {
+            Sentence: { value: '猫' },
+            ...(outcome === 'no-field' ? {} : { sentencefurigana: { value: ' 猫[ねこ]' } }),
+          },
+        },
+      );
+    });
+  });
+}
+
+it('stats word mining skips furigana highlighting when highlightWord is disabled', async () => {
+  await withTempDir(async (dir) => {
+    const sourcePath = path.join(dir, 'episode.mkv');
+    fs.writeFileSync(sourcePath, 'fake media');
+    await withFakeAnkiConnect(
+      async (_requests, url) => {
+        const highlights: Array<string | undefined> = [];
+        const app = createStatsApp(createMockTracker(), {
+          ankiConnectConfig: {
+            url,
+            deck: 'Mining',
+            media: { generateAudio: false, generateImage: false },
+            behavior: { highlightWord: false },
+          },
+          addYomitanNote: async () => 12345,
+          generateSentenceFurigana: async (_text, highlightedText) => {
+            highlights.push(highlightedText);
+            return ' 猫[ねこ]を 見[み]た。';
+          },
+        });
+        const response = await app.request('/api/stats/mine-card?mode=word', {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({
+            sourcePath,
+            startMs: 1000,
+            endMs: 2000,
+            sentence: '猫を見た。',
+            word: '猫',
+          }),
+        });
+        assert.equal(response.status, 200);
+        assert.deepEqual(highlights, [undefined]);
+      },
+      { notesInfoFields: { Sentence: { value: '猫' }, SentenceFurigana: { value: ' 猫[ねこ]' } } },
+    );
+  });
 });
diff --git a/src/core/services/anilist/anilist-update-queue.test.ts b/src/core/services/anilist/anilist-update-queue.test.ts
index 37ba54c8..e4776be7 100644
--- a/src/core/services/anilist/anilist-update-queue.test.ts
+++ b/src/core/services/anilist/anilist-update-queue.test.ts
@@ -27,6 +27,83 @@ function createLogger() {
   };
 }
 
+test('anilist retry queue migrates stream keys and rejects URL-derived searches', () => {
+  const queueFile = createTempQueueFile();
+  const loggerState = createLogger();
+  const key = 'https://example.com/Videos/item/stream?api_key=test-secret::2';
+  fs.writeFileSync(
+    queueFile,
+    JSON.stringify({
+      pending: [
+        {
+          key,
+          title: 'My Anime',
+          episode: 2,
+          createdAt: 1,
+          attemptCount: 0,
+          nextAttemptAt: 1,
+          lastError: null,
+        },
+      ],
+      deadLetter: [],
+    }),
+  );
+  const queue = createAnilistUpdateQueue(queueFile, loggerState.logger);
+  assert.equal(queue.nextReady()?.key, 'jellyfin://example.com/item/item::2');
+  assert.equal(fs.readFileSync(queueFile, 'utf8').includes('test-secret'), false);
+  queue.enqueue('unsafe', 'stream?api_key=test-secret', 3);
+  assert.equal(queue.getSnapshot().pending, 1);
+  queue.markSuccess(key);
+  assert.equal(queue.getSnapshot().pending, 0);
+});
+
+test('anilist retry queue discards empty normalized identities on load and enqueue', () => {
+  const queueFile = createTempQueueFile();
+  const loggerState = createLogger();
+  const invalidKeys = [
+    '',
+    '  ',
+    '::3',
+    'stream?api_key=secret::3',
+    'stream%3Fapi_key%3Dsecret::3',
+    'https://[invalid::3',
+  ];
+  const item = {
+    title: 'My Anime',
+    episode: 3,
+    createdAt: 1,
+    attemptCount: 0,
+    nextAttemptAt: 1,
+    lastError: null,
+  };
+  const validKey = 'https://example.com/Videos/item/stream?api_key=secret::3';
+  fs.writeFileSync(
+    queueFile,
+    JSON.stringify({
+      pending: [...invalidKeys, validKey].map((key) => ({ ...item, key })),
+      deadLetter: invalidKeys.map((key) => ({ ...item, key })),
+    }),
+  );
+  const queue = createAnilistUpdateQueue(queueFile, loggerState.logger);
+  assert.deepEqual(queue.getSnapshot(), { pending: 1, ready: 1, deadLetter: 0 });
+  const persisted = fs.readFileSync(queueFile, 'utf8');
+  assert.deepEqual(JSON.parse(persisted), {
+    pending: [{ ...item, key: 'jellyfin://example.com/item/item::3' }],
+    deadLetter: [],
+  });
+  for (const key of invalidKeys) {
+    queue.enqueue(key, 'My Anime', 3);
+    queue.markFailure(key, 'invalid');
+    queue.markSuccess(key);
+  }
+  assert.equal(fs.readFileSync(queueFile, 'utf8'), persisted);
+  queue.markFailure(validKey, 'retry', 10);
+  assert.equal(queue.nextReady(30_010)?.attemptCount, 1);
+  queue.markSuccess(validKey);
+  queue.enqueue(validKey, 'My Anime', 3);
+  assert.equal(queue.nextReady()?.key, 'jellyfin://example.com/item/item::3');
+});
+
 test('anilist update queue enqueues, snapshots, and dequeues success', () => {
   const queueFile = createTempQueueFile();
   const loggerState = createLogger();
diff --git a/src/core/services/anilist/anilist-update-queue.ts b/src/core/services/anilist/anilist-update-queue.ts
index 6d2f117d..0a1bc20d 100644
--- a/src/core/services/anilist/anilist-update-queue.ts
+++ b/src/core/services/anilist/anilist-update-queue.ts
@@ -1,5 +1,13 @@
 import * as fs from 'fs';
 import { ensureDirForFile } from '../../../shared/fs-utils';
+import { sanitizeMediaTitle, toMediaIdentityPath } from '../../../shared/media-identity';
+
+function normalizeAnilistRetryKey(key: string): string {
+  const parts = key.match(/^(.*)::(\d+)$/s);
+  const identity = toMediaIdentityPath(parts ? (parts[1] ?? '') : key);
+  if (!identity) return '';
+  return parts ? `${identity}::${parts[2]}` : identity;
+}
 
 const INITIAL_BACKOFF_MS = 30_000;
 const MAX_BACKOFF_MS = 6 * 60 * 60 * 1000;
@@ -105,6 +113,9 @@ export function createAnilistUpdateQueue(
             isValidPersistedMediaId(item.mediaId) &&
             (typeof item.lastError === 'string' || item.lastError === null),
         )
+        .filter((item) => sanitizeMediaTitle(item.title) !== null)
+        .map((item) => ({ ...item, key: normalizeAnilistRetryKey(item.key) }))
+        .filter((item) => item.key !== '')
         .slice(0, MAX_ITEMS);
       deadLetter = parsedDeadLetter
         .filter(
@@ -120,7 +131,11 @@ export function createAnilistUpdateQueue(
             isValidPersistedMediaId(item.mediaId) &&
             (typeof item.lastError === 'string' || item.lastError === null),
         )
+        .filter((item) => sanitizeMediaTitle(item.title) !== null)
+        .map((item) => ({ ...item, key: normalizeAnilistRetryKey(item.key) }))
+        .filter((item) => item.key !== '')
         .slice(0, MAX_ITEMS);
+      if (JSON.stringify({ pending, deadLetter }) !== JSON.stringify(parsed)) persist();
     } catch (error) {
       logger.error('Failed to load AniList retry queue.', error);
     }
@@ -136,6 +151,9 @@ export function createAnilistUpdateQueue(
       season: number | null = null,
       mediaId: number | null = null,
     ): void {
+      if (!sanitizeMediaTitle(title)) return;
+      key = normalizeAnilistRetryKey(key);
+      if (!key) return;
       const existing =
         pending.find((item) => item.key === key) || deadLetter.find((item) => item.key === key);
       if (existing) {
@@ -165,6 +183,8 @@ export function createAnilistUpdateQueue(
     },
 
     markSuccess(key: string): void {
+      key = normalizeAnilistRetryKey(key);
+      if (!key) return;
       const before = pending.length;
       pending = pending.filter((item) => item.key !== key);
       if (pending.length !== before) {
@@ -173,6 +193,8 @@ export function createAnilistUpdateQueue(
     },
 
     markFailure(key: string, reason: string, nowMs: number = Date.now()): void {
+      key = normalizeAnilistRetryKey(key);
+      if (!key) return;
       const item = pending.find((candidate) => candidate.key === key);
       if (!item) {
         return;
diff --git a/src/core/services/anilist/anilist-updater.test.ts b/src/core/services/anilist/anilist-updater.test.ts
index d5e961f9..adbd9886 100644
--- a/src/core/services/anilist/anilist-updater.test.ts
+++ b/src/core/services/anilist/anilist-updater.test.ts
@@ -140,6 +140,62 @@ test('guessAnilistMediaInfo preserves useful guessit alternative title for ambig
   });
 });
 
+test('guessAnilistMediaInfo uses the display title for authenticated streams', async () => {
+  const targets: string[] = [];
+  const result = await guessAnilistMediaInfo(
+    'https://jellyfin.example/Videos/item/stream?static=true&api_key=test-secret',
+    'My Anime S02E03',
+    {
+      runGuessit: async (target) => {
+        targets.push(target);
+        throw new Error('use fallback parser');
+      },
+    },
+  );
+  assert.deepEqual(targets, ['My Anime S02E03']);
+  assert.deepEqual(result, {
+    title: 'My Anime',
+    season: 2,
+    episode: 3,
+    source: 'fallback',
+  });
+});
+
+test('guessAnilistMediaInfo preserves slashes in display titles', async () => {
+  const title = 'Fate/stay night S01E02';
+  for (const mediaPath of [null, title, 'https://example.com/stream?api_key=test-secret']) {
+    const targets: string[] = [];
+    await guessAnilistMediaInfo(mediaPath, title, {
+      runGuessit: async (target) => {
+        targets.push(target);
+        return JSON.stringify({ title: 'Fate/stay night', season: 1, episode: 2 });
+      },
+    });
+    assert.deepEqual(targets, [title]);
+  }
+});
+
+test('guessAnilistMediaInfo never parses stream URLs or their query-bearing filenames', async () => {
+  const unsafeInputs = [
+    'https://jellyfin.example/Videos/item/stream?static=true&api_key=test-secret',
+    'stream?static=true&api_key=test-secret&MediaSourceId=item',
+    'https://user:test-secret@example.com/video.mkv',
+  ];
+  for (const input of unsafeInputs) {
+    const targets: string[] = [];
+    const deps = {
+      runGuessit: async (target: string) => {
+        targets.push(target);
+        return JSON.stringify({ title: target });
+      },
+    };
+    assert.equal(await guessAnilistMediaInfo(input, null, deps), null);
+    assert.equal(await guessAnilistMediaInfo(null, input, deps), null);
+    assert.equal(await guessAnilistMediaInfo(input, input, deps), null);
+    assert.deepEqual(targets, []);
+  }
+});
+
 test('updateAnilistPostWatchProgress updates progress when behind', async () => {
   const originalFetch = globalThis.fetch;
   let call = 0;
diff --git a/src/core/services/anilist/anilist-updater.ts b/src/core/services/anilist/anilist-updater.ts
index 21149fc2..4e0e35c8 100644
--- a/src/core/services/anilist/anilist-updater.ts
+++ b/src/core/services/anilist/anilist-updater.ts
@@ -2,6 +2,7 @@ import * as childProcess from 'child_process';
 import * as path from 'path';
 
 import { parseMediaInfo } from '../../../jimaku/utils';
+import { resolveMediaLookupTarget, sanitizeMediaTitle } from '../../../shared/media-identity';
 import type { AnilistRateLimiter } from './rate-limiter';
 import { resolveAnilistSeasonMedia } from './season-resolver';
 
@@ -230,8 +231,9 @@ export async function guessAnilistMediaInfo(
   mediaTitle: string | null,
   deps: GuessAnilistMediaInfoDeps = { runGuessit },
 ): Promise<AnilistMediaGuess | null> {
-  const target = mediaPath ?? mediaTitle;
-  const guessitTarget = mediaPath ? path.basename(mediaPath) : mediaTitle;
+  const target = resolveMediaLookupTarget(mediaPath, mediaTitle);
+  if (!target) return null;
+  const guessitTarget = target === sanitizeMediaTitle(mediaTitle) ? target : path.basename(target);
 
   if (guessitTarget && guessitTarget.trim().length > 0) {
     try {
@@ -259,8 +261,7 @@ export async function guessAnilistMediaInfo(
     }
   }
 
-  const fallbackTarget = mediaPath ?? mediaTitle;
-  const parsed = parseMediaInfo(fallbackTarget);
+  const parsed = parseMediaInfo(target);
   if (!parsed.title.trim()) {
     return null;
   }
diff --git a/src/core/services/anilist/cover-art-fetcher.test.ts b/src/core/services/anilist/cover-art-fetcher.test.ts
index d75ba7da..a23ed18c 100644
--- a/src/core/services/anilist/cover-art-fetcher.test.ts
+++ b/src/core/services/anilist/cover-art-fetcher.test.ts
@@ -552,3 +552,200 @@ test('fetchIfMissing re-resolves an unresolved season once AniList publishes the
     cleanupDbPath(dbPath);
   }
 });
+
+for (const linkedToAnilist of [false, true]) {
+  test(`TMDB fallback preserves AniList identity when linked=${linkedToAnilist}`, async () => {
+    const dbPath = makeDbPath();
+    const db = new Database(dbPath);
+    ensureSchema(db);
+    const videoId = getOrCreateVideoRecord(db, 'local:/tmp/hanzawa-01.mkv', {
+      canonicalTitle: 'Hanzawa Naoki - 01.mkv',
+      sourcePath: '/tmp/hanzawa-01.mkv',
+      sourceUrl: null,
+      sourceType: SOURCE_TYPE_LOCAL,
+    });
+    const animeId = getOrCreateAnimeRecord(db, {
+      parsedTitle: 'Hanzawa Naoki',
+      canonicalTitle: 'Hanzawa Naoki',
+      anilistId: linkedToAnilist ? 42 : null,
+      titleRomaji: null,
+      titleEnglish: null,
+      titleNative: null,
+      metadataJson: null,
+    });
+    linkVideoToAnimeRecord(db, videoId, {
+      animeId,
+      parsedBasename: null,
+      parsedTitle: 'Hanzawa Naoki',
+      parsedSeason: null,
+      parsedEpisode: 1,
+      parserSource: 'fallback',
+      parserConfidence: 1,
+      parseMetadataJson: null,
+    });
+
+    const fetchCalls: string[] = [];
+    const originalFetch = globalThis.fetch;
+    globalThis.fetch = (async (input: RequestInfo | URL) => {
+      const url = String(input);
+      fetchCalls.push(url);
+      if (url.startsWith('https://graphql.anilist.co')) {
+        return createJsonResponse({ data: { Page: { media: [] } } });
+      }
+      assert.equal(url, 'https://image.tmdb.org/t/p/w500/hanzawa.jpg');
+      return new Response(new Uint8Array([5, 6, 7]), {
+        status: 200,
+        headers: { 'Content-Type': 'image/jpeg' },
+      });
+    }) as typeof fetch;
+
+    const resolvedTitles: string[] = [];
+    try {
+      const fetcher = createCoverArtFetcher(
+        { acquire: async () => {}, recordResponse: () => {} },
+        console,
+        {
+          runGuessit: async () => {
+            throw new Error('guessit unavailable');
+          },
+          liveAction: {
+            async resolveByTitle(title) {
+              resolvedTitles.push(title);
+              if (title !== 'Hanzawa Naoki') return null;
+              return {
+                tmdbId: 61222,
+                tmdbType: 'tv',
+                titleEnglish: 'Hanzawa Naoki',
+                titleNative: '半沢直樹',
+                description: 'A banker fights back.',
+                posterUrl: 'https://image.tmdb.org/t/p/w500/hanzawa.jpg',
+                episodesTotal: 10,
+                year: 2013,
+                originalLanguage: 'ja',
+                isAnimation: false,
+                allTitles: ['Hanzawa Naoki', '半沢直樹'],
+              };
+            },
+            async resolveById() {
+              return null;
+            },
+          },
+        },
+      );
+
+      const fetched = await fetcher.fetchIfMissing(db, videoId, 'Hanzawa Naoki - 01.mkv');
+      const stored = getCoverArt(db, videoId);
+      const anime = db
+        .prepare(
+          'SELECT media_kind AS mediaKind, tmdb_id AS tmdbId, description FROM imm_anime WHERE anime_id = ?',
+        )
+        .get(animeId) as { mediaKind: string; tmdbId: number | null; description: string | null };
+
+      if (linkedToAnilist) {
+        assert.equal(fetched, false);
+        assert.equal(stored?.coverBlob, null);
+        assert.equal(stored?.coverUrl, null);
+        assert.equal(anime.mediaKind, 'anime');
+        assert.equal(anime.tmdbId, null);
+        assert.deepEqual(resolvedTitles, []);
+        const requestCount = fetchCalls.length;
+        assert.equal(await fetcher.fetchIfMissing(db, videoId, 'Hanzawa Naoki - 01.mkv'), false);
+        assert.equal(fetchCalls.length, requestCount);
+        return;
+      }
+      assert.equal(fetched, true);
+      // The raw fallback-parser title is tried first, then the tag-stripped one.
+      assert.deepEqual(resolvedTitles, ['Hanzawa Naoki - 01', 'Hanzawa Naoki']);
+      assert.equal(stored?.anilistId, null);
+      assert.equal(stored?.coverUrl, 'https://image.tmdb.org/t/p/w500/hanzawa.jpg');
+      assert.equal(Buffer.from(stored?.coverBlob ?? []).toString('hex'), '050607');
+      assert.equal(anime.mediaKind, 'live_action');
+      assert.equal(anime.tmdbId, 61222);
+      assert.equal(anime.description, 'A banker fights back.');
+      assert.ok(fetchCalls.some((url) => url.startsWith('https://graphql.anilist.co')));
+    } finally {
+      globalThis.fetch = originalFetch;
+      db.close();
+      cleanupDbPath(dbPath);
+    }
+  });
+}
+
+test('fetchIfMissing skips AniList for an entry already linked to TMDB', async () => {
+  const dbPath = makeDbPath();
+  const db = new Database(dbPath);
+  ensureSchema(db);
+  const videoId = getOrCreateVideoRecord(db, 'local:/tmp/hanzawa-02.mkv', {
+    canonicalTitle: 'Hanzawa Naoki - 02.mkv',
+    sourcePath: '/tmp/hanzawa-02.mkv',
+    sourceUrl: null,
+    sourceType: SOURCE_TYPE_LOCAL,
+  });
+  const animeId = getOrCreateAnimeRecord(db, {
+    parsedTitle: 'Hanzawa Naoki',
+    canonicalTitle: 'Hanzawa Naoki',
+    anilistId: null,
+    titleRomaji: null,
+    titleEnglish: null,
+    titleNative: null,
+    metadataJson: null,
+  });
+  linkVideoToAnimeRecord(db, videoId, {
+    animeId,
+    parsedBasename: null,
+    parsedTitle: 'Hanzawa Naoki',
+    parsedSeason: null,
+    parsedEpisode: 2,
+    parserSource: 'fallback',
+    parserConfidence: 1,
+    parseMetadataJson: null,
+  });
+  db.prepare(
+    "UPDATE imm_anime SET media_kind = 'live_action', tmdb_id = 61222, tmdb_type = 'tv' WHERE anime_id = ?",
+  ).run(animeId);
+
+  const originalFetch = globalThis.fetch;
+  globalThis.fetch = (async (input: RequestInfo | URL) => {
+    assert.equal(String(input), 'https://image.tmdb.org/t/p/w500/hanzawa.jpg');
+    return new Response(new Uint8Array([1]), { status: 200 });
+  }) as typeof fetch;
+
+  const byIdCalls: Array<[string, number]> = [];
+  try {
+    const fetcher = createCoverArtFetcher(
+      { acquire: async () => {}, recordResponse: () => {} },
+      console,
+      {
+        liveAction: {
+          async resolveByTitle() {
+            throw new Error('title search must not run for a linked entry');
+          },
+          async resolveById(tmdbType, tmdbId) {
+            byIdCalls.push([tmdbType, tmdbId]);
+            return {
+              tmdbId,
+              tmdbType,
+              titleEnglish: 'Hanzawa Naoki',
+              titleNative: null,
+              description: null,
+              posterUrl: 'https://image.tmdb.org/t/p/w500/hanzawa.jpg',
+              episodesTotal: 10,
+              year: null,
+              originalLanguage: 'ja',
+              isAnimation: false,
+              allTitles: [],
+            };
+          },
+        },
+      },
+    );
+
+    assert.equal(await fetcher.fetchIfMissing(db, videoId, 'Hanzawa Naoki - 02.mkv'), true);
+    assert.deepEqual(byIdCalls, [['tv', 61222]]);
+    assert.equal(getCoverArt(db, videoId)?.coverBlob?.length, 1);
+  } finally {
+    globalThis.fetch = originalFetch;
+    db.close();
+    cleanupDbPath(dbPath);
+  }
+});
diff --git a/src/core/services/anilist/cover-art-fetcher.ts b/src/core/services/anilist/cover-art-fetcher.ts
index ac7be780..10d20c40 100644
--- a/src/core/services/anilist/cover-art-fetcher.ts
+++ b/src/core/services/anilist/cover-art-fetcher.ts
@@ -16,6 +16,9 @@ import {
   type AnilistQueryExecutor,
   type AnilistSeasonResolution,
 } from './season-resolver';
+import { getVideoTmdbLink, linkAnimeToTmdbTitle } from '../immersion-tracker/live-action-link';
+import type { LiveActionMetadataResolver } from '../tmdb/live-action-resolver';
+import type { TmdbTitleDetails } from '../tmdb/tmdb-client';
 
 const ANILIST_GRAPHQL_URL = 'https://graphql.anilist.co';
 const NO_MATCH_RETRY_MS = 5 * 60 * 1000;
@@ -39,6 +42,8 @@ interface CoverArtCandidate {
 
 interface CoverArtFetcherOptions {
   runGuessit?: GuessAnilistMediaInfoDeps['runGuessit'];
+  /** Live-action fallback consulted when AniList has no match for a title. */
+  liveAction?: LiveActionMetadataResolver;
 }
 
 export function stripFilenameTags(raw: string): string {
@@ -152,6 +157,60 @@ export function createCoverArtFetcher(
     return true;
   };
 
+  const cacheNoMatch = (db: DatabaseSync, videoId: number): void => {
+    upsertCoverArt(db, videoId, {
+      anilistId: null,
+      coverUrl: null,
+      coverBlob: null,
+      titleRomaji: null,
+      titleEnglish: null,
+      episodesTotal: null,
+    });
+  };
+
+  // Links the video's library entry to the TMDB title and stores its poster.
+  const storeLiveActionArt = async (
+    db: DatabaseSync,
+    videoId: number,
+    details: TmdbTitleDetails,
+  ): Promise<boolean> => {
+    const row = db
+      .prepare(
+        `SELECT v.anime_id AS animeId, a.anilist_id AS anilistId
+                FROM imm_videos v LEFT JOIN imm_anime a ON a.anime_id = v.anime_id
+                WHERE v.video_id = ?`,
+      )
+      .get(videoId) as { animeId: number | null; anilistId: number | null } | undefined;
+    if (row?.anilistId != null) return false;
+    if (row?.animeId) {
+      const link = linkAnimeToTmdbTitle(db, row.animeId, details, { mode: 'auto' });
+      if (link.mergedAnimeIds.length > 0) {
+        logger.info(
+          'cover-art: folded library entries %s into %d (same TMDB title)',
+          link.mergedAnimeIds.join(','),
+          link.animeId,
+        );
+      }
+    }
+    const coverBlob = details.posterUrl ? await downloadImage(details.posterUrl) : null;
+    upsertCoverArt(db, videoId, {
+      anilistId: null,
+      coverUrl: details.posterUrl,
+      coverBlob,
+      titleRomaji: null,
+      titleEnglish: details.titleEnglish,
+      episodesTotal: details.episodesTotal,
+    });
+    logger.info(
+      'cover-art: linked videoId=%d to TMDB %s/%d "%s"',
+      videoId,
+      details.tmdbType,
+      details.tmdbId,
+      details.titleEnglish ?? details.titleNative ?? '',
+    );
+    return coverBlob !== null;
+  };
+
   const resolveCanonicalTitle = (
     db: DatabaseSync,
     videoId: number,
@@ -192,6 +251,16 @@ export function createCoverArtFetcher(
 
   return {
     async fetchIfMissing(db, videoId, canonicalTitle): Promise<boolean> {
+      const channel = db
+        .prepare(
+          `
+        SELECT 1 FROM imm_videos v
+        JOIN imm_anime a ON a.anime_id = v.anime_id
+        WHERE v.video_id = ? AND a.media_kind = 'youtube'
+      `,
+        )
+        .get(videoId);
+      if (channel) return false;
       const existing = getCoverArt(db, videoId);
       if (existing?.coverBlob) {
         return true;
@@ -225,18 +294,31 @@ export function createCoverArtFetcher(
         return false;
       }
 
+      // A live-action entry already knows its TMDB title; AniList has nothing
+      // to add and would only produce a spurious anime match.
+      const hasAnilistLink = Boolean(
+        db
+          .prepare(
+            `SELECT 1 FROM imm_videos v JOIN imm_anime a ON a.anime_id = v.anime_id
+         WHERE v.video_id = ? AND a.anilist_id IS NOT NULL`,
+          )
+          .get(videoId),
+      );
+      const tmdbLink = getVideoTmdbLink(db, videoId);
+      if (tmdbLink && !hasAnilistLink) {
+        const details = await options.liveAction?.resolveById(tmdbLink.tmdbType, tmdbLink.tmdbId);
+        if (details) {
+          return storeLiveActionArt(db, videoId, details);
+        }
+        cacheNoMatch(db, videoId);
+        return false;
+      }
+
       const effectiveTitle = resolveCanonicalTitle(db, videoId, canonicalTitle);
       const cleaned = stripFilenameTags(effectiveTitle);
       if (!cleaned) {
         logger.warn('cover-art: empty title after stripping tags for videoId=%d', videoId);
-        upsertCoverArt(db, videoId, {
-          anilistId: null,
-          coverUrl: null,
-          coverBlob: null,
-          titleRomaji: null,
-          titleEnglish: null,
-          episodesTotal: null,
-        });
+        cacheNoMatch(db, videoId);
         return false;
       }
 
@@ -294,15 +376,16 @@ export function createCoverArtFetcher(
 
       const selected = resolution?.media ?? null;
       if (!selected) {
-        logger.info('cover-art: no Anilist results for "%s", caching no-match', searchBase);
-        upsertCoverArt(db, videoId, {
-          anilistId: null,
-          coverUrl: null,
-          coverBlob: null,
-          titleRomaji: null,
-          titleEnglish: null,
-          episodesTotal: null,
-        });
+        if (options.liveAction && !hasAnilistLink) {
+          for (const searchTitle of searchTitles) {
+            const details = await options.liveAction.resolveByTitle(searchTitle);
+            if (details) {
+              return storeLiveActionArt(db, videoId, details);
+            }
+          }
+        }
+        logger.info('cover-art: no Anilist or TMDB results for "%s", caching no-match', searchBase);
+        cacheNoMatch(db, videoId);
         return false;
       }
 
diff --git a/src/core/services/anilist/season-resolver.test.ts b/src/core/services/anilist/season-resolver.test.ts
index a5e0b8cd..a58f8d23 100644
--- a/src/core/services/anilist/season-resolver.test.ts
+++ b/src/core/services/anilist/season-resolver.test.ts
@@ -116,6 +116,27 @@ function createExecutor(
   return { execute, searches, relationLookups };
 }
 
+test('AniList refuses URL-derived search titles before making a request', async () => {
+  let requests = 0;
+  for (const title of [
+    'https://example.com/stream?api_key=test-secret',
+    'stream?static=true&api_key=test-secret',
+    'stream static true api key test secret',
+  ]) {
+    const result = await resolveAnilistSeasonMedia(
+      { title },
+      {
+        execute: async () => {
+          requests += 1;
+          throw new Error('must not send URL-derived searches');
+        },
+      },
+    );
+    assert.equal(result, null);
+  }
+  assert.equal(requests, 0);
+});
+
 test('stripSeasonSuffix drops release-name season markers', () => {
   assert.equal(stripSeasonSuffix('Some Show Season 3'), 'Some Show');
   assert.equal(stripSeasonSuffix('Some Show S3'), 'Some Show');
diff --git a/src/core/services/anilist/season-resolver.ts b/src/core/services/anilist/season-resolver.ts
index 8bbf9b5d..76aeaa50 100644
--- a/src/core/services/anilist/season-resolver.ts
+++ b/src/core/services/anilist/season-resolver.ts
@@ -1,3 +1,5 @@
+import { sanitizeMediaTitle } from '../../../shared/media-identity';
+
 /**
  * AniList has no concept of "season N": sequels are separate media with their own
  * titles (Zoku, Kan, 2nd Season, ...). Searching "<title> Season 3" therefore returns
@@ -348,7 +350,9 @@ export async function resolveAnilistSeasonMedia(
   input: ResolveAnilistSeasonMediaInput,
   deps: ResolveAnilistSeasonMediaDeps,
 ): Promise<AnilistSeasonResolution | null> {
-  const searchTitle = stripSeasonSuffix(input.title).trim() || input.title.trim();
+  const safeTitle = sanitizeMediaTitle(input.title);
+  if (!safeTitle) return null;
+  const searchTitle = stripSeasonSuffix(safeTitle).trim() || safeTitle;
   if (!searchTitle) return null;
 
   const season =
diff --git a/src/core/services/anki-jimaku.ts b/src/core/services/anki-jimaku.ts
index 479b72e2..8ac3e47b 100644
--- a/src/core/services/anki-jimaku.ts
+++ b/src/core/services/anki-jimaku.ts
@@ -65,6 +65,7 @@ export interface AnkiJimakuIpcRuntimeOptions {
   getYoutubeMediaSourceUrl?: () => Promise<string | null | undefined> | string | null | undefined;
   showDesktopNotification: (title: string, options: { body?: string; icon?: string }) => void;
   showOverlayNotification?: (payload: OverlayNotificationPayload) => void;
+  dismissOverlayNotification?: (id: string) => void;
   createFieldGroupingCallback: () => (
     data: KikuFieldGroupingRequestData,
   ) => Promise<KikuFieldGroupingChoice>;
@@ -166,6 +167,7 @@ export function registerAnkiJimakuIpcRuntime(
           options.getCachedMediaPath,
           options.shouldRequireRemoteMediaCache,
           options.getYoutubeMediaSourceUrl,
+          options.dismissOverlayNotification,
         );
         integration.start();
         options.setAnkiIntegration(integration);
@@ -212,9 +214,10 @@ export function registerAnkiJimakuIpcRuntime(
     },
     getJimakuMediaInfo: () => options.parseMediaInfo(options.getCurrentMediaPath()),
     searchJimakuEntries: async (query) => {
-      logger.info(`[jimaku] search-entries query: "${query.query}"`);
+      const category = query.category ?? 'anime';
+      logger.info(`[jimaku] search-entries query: "${query.query}" category=${category}`);
       const response = await options.jimakuFetchJson<JimakuEntry[]>('/api/entries/search', {
-        anime: true,
+        anime: category === 'anime',
         query: query.query,
       });
       if (!response.ok) return response;
diff --git a/src/core/services/ass-text.test.ts b/src/core/services/ass-text.test.ts
index 216c23f8..f7d6edfa 100644
--- a/src/core/services/ass-text.test.ts
+++ b/src/core/services/ass-text.test.ts
@@ -10,6 +10,8 @@ import {
   isAssTemporalCommand,
   normalizePlainSubtitleText,
   parseAssEffectField,
+  removeLiveGlyphFragmentLines,
+  removeAssControlDebrisLines,
 } from './ass-text';
 
 test('assToPlainText drops vector drawing runs', () => {
@@ -74,6 +76,14 @@ test('assToPlainText normalizes CRLF before converting', () => {
   assert.equal(assToPlainText('一行目\r\n二行目'), '一行目\n二行目');
 });
 
+test('removeAssControlDebrisLines drops malformed spacer resets without eating dialogue', () => {
+  assert.equal(
+    removeAssControlDebrisLines('Visible line\n\\\n{\\fr0\n\\{\\frz287.5'),
+    'Visible line',
+  );
+  assert.equal(removeAssControlDebrisLines('本文{\\pos(1,2)'), '本文{\\pos(1,2)');
+});
+
 test('normalizePlainSubtitleText settles whitespace without decoding ASS', () => {
   // A brace reaching this layer is literal text mpv chose to show, not markup.
   assert.equal(normalizePlainSubtitleText('本文{\\pos(1,2)'), '本文{\\pos(1,2)');
@@ -193,3 +203,33 @@ test('isAnimatedAssEffectKind covers the stock animated effects only', () => {
   assert.equal(isAnimatedAssEffectKind('other'), false);
   assert.equal(isAnimatedAssEffectKind('none'), false);
 });
+
+test('removeLiveGlyphFragmentLines drops a per-glyph typesetting wall and its syllable', () => {
+  const wall = [...'wansdumretoikhI'].join('\n');
+  assert.equal(removeLiveGlyphFragmentLines(`${wall}\ntai`), '');
+});
+
+test('removeLiveGlyphFragmentLines keeps concurrent dialogue beside a glyph wall', () => {
+  const wall = [...'wansdumretoikhI'].join('\n');
+  assert.equal(removeLiveGlyphFragmentLines(`${wall}\nそれよりも　ノート…`), 'それよりも　ノート…');
+});
+
+test('removeLiveGlyphFragmentLines leaves ordinary short lines alone', () => {
+  const text = 'え\nはい。\nそうだな';
+  assert.equal(removeLiveGlyphFragmentLines(text), text);
+});
+
+test('normalizePlainSubtitleText folds cue-boundary blank lines for text consumers', () => {
+  // The display layer splits on the blank line before normalizing; everyone else --
+  // tokenizer, cache key, dedup gate, mined sentence -- wants the plain line form.
+  assert.equal(
+    normalizePlainSubtitleText('\u4e00\u884c\u76ee\n\n\u4e8c\u884c\u76ee'),
+    '\u4e00\u884c\u76ee\n\u4e8c\u884c\u76ee',
+  );
+  assert.equal(
+    normalizePlainSubtitleText('\u4e00\u884c\u76ee\n\n\u4e8c\u884c\u76ee', {
+      collapseLineBreaks: true,
+    }),
+    '\u4e00\u884c\u76ee \u4e8c\u884c\u76ee',
+  );
+});
diff --git a/src/core/services/ass-text.ts b/src/core/services/ass-text.ts
index ca05b7fd..edb30dda 100644
--- a/src/core/services/ass-text.ts
+++ b/src/core/services/ass-text.ts
@@ -91,6 +91,41 @@ export function assToPlainText(text: string, lineBreak: AssLineBreak = '\n'): st
   return resolveWhitespaceEscapes(stripAssMarkup(text.replace(/\r\n/g, '\n')), lineBreak);
 }
 
+const MALFORMED_ASS_ROTATION_RESET = /^\\?\{\\(?:fr|frx|fry|frz|fax|fay)[-+.0-9]*$/u;
+
+/**
+ * Drop non-rendering spacer events left as literal text by a malformed, unclosed ASS
+ * rotation reset. These events otherwise become repeated `\\` or `{\\fr0` subtitle
+ * lines after mpv-compatible decoding.
+ */
+export function removeAssControlDebrisLines(text: string): string {
+  return text
+    .split('\n')
+    .filter((line) => {
+      const compact = line.replace(/\s+/gu, '');
+      return compact !== '\\' && !MALFORMED_ASS_ROTATION_RESET.test(compact);
+    })
+    .join('\n');
+}
+
+const MIN_GLYPH_BURST_LINES = 6;
+const MAX_GLYPH_BURST_COMPANION_GLYPHS = 3;
+
+/**
+ * Per-glyph karaoke typesetting flattened into live text becomes a wall of
+ * single-character lines plus the short syllable currently being typed. No authored
+ * subtitle stacks this many one-glyph lines at once, so when the wall is present drop
+ * it and its short companion fragments while keeping any concurrent dialogue line.
+ */
+export function removeLiveGlyphFragmentLines(text: string): string {
+  const lines = text.split('\n');
+  const singleGlyphLines = lines.filter((line) => [...line.trim()].length === 1).length;
+  if (singleGlyphLines < MIN_GLYPH_BURST_LINES) return text;
+  return lines
+    .filter((line) => [...line.trim()].length > MAX_GLYPH_BURST_COMPANION_GLYPHS)
+    .join('\n');
+}
+
 export interface NormalizePlainSubtitleTextOptions {
   /** Fold every line break into a single space. */
   collapseLineBreaks?: boolean;
@@ -118,6 +153,10 @@ export function normalizePlainSubtitleText(
   );
   if (collapseLineBreaks) {
     normalized = normalized.replace(/\n/g, ' ').replace(/\s+/g, ' ');
+  } else {
+    // Simultaneous cues reach the display layer separated by a blank line; every other
+    // consumer wants the plain one-break-per-line form.
+    normalized = normalized.replace(/\n{2,}/g, '\n');
   }
 
   return trim ? normalized.trim() : normalized;
diff --git a/src/core/services/cli-command.test.ts b/src/core/services/cli-command.test.ts
index 5d23f3dd..b9c5e422 100644
--- a/src/core/services/cli-command.test.ts
+++ b/src/core/services/cli-command.test.ts
@@ -406,6 +406,17 @@ test('handleCliCommand ensures background stats server for second-instance --sta
   assert.equal(ensured.length, 1);
 });
 
+test('handleCliCommand reports unexpected background stats startup failures', async () => {
+  const startup = Promise.reject(new Error('startup unavailable'));
+  const { deps, calls, osd } = createDeps({ ensureBackgroundStatsServer: () => startup });
+
+  handleCliCommand(makeArgs({ start: true, background: true }), 'initial', deps);
+  await new Promise((resolve) => setImmediate(resolve));
+
+  assert.ok(calls.includes('error:ensureBackgroundStatsServer failed:'));
+  assert.ok(osd.includes('Stats server startup failed: startup unavailable'));
+});
+
 test('handleCliCommand does not ensure background stats server for foreground --start', () => {
   const ensured: number[] = [];
   const { deps } = createDeps({
diff --git a/src/core/services/cli-command.ts b/src/core/services/cli-command.ts
index 35b1a7e4..ea6b7a35 100644
--- a/src/core/services/cli-command.ts
+++ b/src/core/services/cli-command.ts
@@ -107,7 +107,7 @@ export interface CliCommandServiceDeps {
     mode: NonNullable<CliArgs['youtubeMode']>;
     source: CliCommandSource;
   }) => Promise<void>;
-  ensureBackgroundStatsServer?: () => void;
+  ensureBackgroundStatsServer?: () => Promise<void> | void;
   printHelp: () => void;
   hasMainWindow: () => boolean;
   getMultiCopyTimeoutMs: () => number;
@@ -188,7 +188,7 @@ interface AnilistCliRuntime {
 interface AppCliRuntime {
   stop: () => void;
   hasMainWindow: () => boolean;
-  ensureBackgroundStatsServer?: () => void;
+  ensureBackgroundStatsServer?: () => Promise<void> | void;
   runUpdateCommand: CliCommandServiceDeps['runUpdateCommand'];
   runEnsureLinuxRuntimePluginAssetsCommand: CliCommandServiceDeps['runEnsureLinuxRuntimePluginAssetsCommand'];
   runYoutubePlaybackFlow: CliCommandServiceDeps['runYoutubePlaybackFlow'];
@@ -400,7 +400,14 @@ export function handleCliCommand(
   }
 
   if (args.start && args.background) {
-    deps.ensureBackgroundStatsServer?.();
+    runAsyncWithOsd(
+      async () => {
+        await deps.ensureBackgroundStatsServer?.();
+      },
+      deps,
+      'ensureBackgroundStatsServer',
+      'Stats server startup failed',
+    );
   }
 
   if (args.sessionAction) {
diff --git a/src/core/services/config-hot-reload.test.ts b/src/core/services/config-hot-reload.test.ts
index 38fcfcb6..65f52844 100644
--- a/src/core/services/config-hot-reload.test.ts
+++ b/src/core/services/config-hot-reload.test.ts
@@ -1,12 +1,47 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
 import { DEFAULT_CONFIG, deepCloneConfig } from '../../config';
+import { buildConfigSettingsRegistry, getConfigValueAtPath } from '../../config/settings/registry';
 import {
   classifyConfigHotReloadDiff,
   createConfigHotReloadRuntime,
   type ConfigHotReloadRuntimeDeps,
 } from './config-hot-reload';
 
+test('every LIVE settings field is classified without a restart warning', () => {
+  for (const field of buildConfigSettingsRegistry(DEFAULT_CONFIG)) {
+    if (field.restartBehavior !== 'hot-reload') continue;
+    const next = deepCloneConfig(DEFAULT_CONFIG);
+    const segments = field.configPath.split('.');
+    const leaf = segments.pop();
+    assert.ok(leaf);
+    const parent = segments.length ? getConfigValueAtPath(next, segments.join('.')) : next;
+    assert.ok(parent && typeof parent === 'object', field.configPath);
+    // The classifier compares structure; validation of field values is tested separately.
+    Object.defineProperty(parent, leaf, {
+      value: getConfigValueAtPath(next, field.configPath) === null ? 'changed' : null,
+      enumerable: true,
+    });
+    const diff = classifyConfigHotReloadDiff(DEFAULT_CONFIG, next);
+    assert.deepEqual(diff.restartRequiredFields, [], field.configPath);
+    assert.ok(diff.hotReloadFields.length > 0, field.configPath);
+  }
+});
+
+test('live notifications and subtitle generation changes preserve unrelated restart warnings', () => {
+  const next = deepCloneConfig(DEFAULT_CONFIG);
+  next.notifications.overlayPosition = 'top';
+  next.subtitleGeneration.threads += 1;
+  next.websocket.port += 1;
+
+  const diff = classifyConfigHotReloadDiff(DEFAULT_CONFIG, next);
+  assert.deepEqual(
+    new Set(diff.hotReloadFields),
+    new Set(['notifications.overlayPosition', 'subtitleGeneration.threads']),
+  );
+  assert.deepEqual(diff.restartRequiredFields, ['websocket.port']);
+});
+
 test('classifyConfigHotReloadDiff separates hot and restart-required fields', () => {
   const prev = deepCloneConfig(DEFAULT_CONFIG);
   const next = deepCloneConfig(DEFAULT_CONFIG);
@@ -15,7 +50,7 @@ test('classifyConfigHotReloadDiff separates hot and restart-required fields', ()
 
   const diff = classifyConfigHotReloadDiff(prev, next);
   assert.deepEqual(diff.hotReloadFields, ['subtitleStyle']);
-  assert.deepEqual(diff.restartRequiredFields, ['websocket']);
+  assert.deepEqual(diff.restartRequiredFields, ['websocket.port']);
 });
 
 test('classifyConfigHotReloadDiff treats safe nested config paths as hot-reloadable', () => {
@@ -33,6 +68,7 @@ test('classifyConfigHotReloadDiff treats safe nested config paths as hot-reloada
   next.ankiConnect.deck = 'Mining';
   next.ankiConnect.media.normalizeAudio = !prev.ankiConnect.media.normalizeAudio;
   next.ankiConnect.media.mirrorMpvVolume = !prev.ankiConnect.media.mirrorMpvVolume;
+  next.ankiConnect.media.reviewTiming = !prev.ankiConnect.media.reviewTiming;
   next.ankiConnect.behavior.autoUpdateNewCards = !prev.ankiConnect.behavior.autoUpdateNewCards;
   next.ankiConnect.knownWords.highlightEnabled = !prev.ankiConnect.knownWords.highlightEnabled;
   next.ankiConnect.knownWords.refreshMinutes = prev.ankiConnect.knownWords.refreshMinutes + 5;
@@ -69,6 +105,7 @@ test('classifyConfigHotReloadDiff treats safe nested config paths as hot-reloada
       'ankiConnect.deck',
       'ankiConnect.media.normalizeAudio',
       'ankiConnect.media.mirrorMpvVolume',
+      'ankiConnect.media.reviewTiming',
       'ankiConnect.behavior.autoUpdateNewCards',
       'ankiConnect.knownWords.highlightEnabled',
       'ankiConnect.knownWords.refreshMinutes',
@@ -99,7 +136,11 @@ test('classifyConfigHotReloadDiff keeps unsafe nested siblings restart-required'
   const diff = classifyConfigHotReloadDiff(prev, next);
 
   assert.deepEqual(diff.hotReloadFields, []);
-  assert.deepEqual(diff.restartRequiredFields, ['ankiConnect', 'stats']);
+  assert.deepEqual(diff.restartRequiredFields, [
+    'ankiConnect.url',
+    'ankiConnect.ai.model',
+    'stats.serverPort',
+  ]);
 });
 
 test('config hot reload runtime debounces rapid watch events', () => {
diff --git a/src/core/services/config-hot-reload.ts b/src/core/services/config-hot-reload.ts
index 4da9ca27..9cdaed05 100644
--- a/src/core/services/config-hot-reload.ts
+++ b/src/core/services/config-hot-reload.ts
@@ -1,3 +1,4 @@
+import { getConfigHotReloadField } from '../../config/hot-reload';
 import { type ReloadConfigStrictResult } from '../../config';
 import type { ConfigValidationWarning } from '../../types';
 import type { ResolvedConfig } from '../../types';
@@ -33,10 +34,6 @@ function isRecord(value: unknown): value is Record<string, unknown> {
   return value !== null && typeof value === 'object' && !Array.isArray(value);
 }
 
-function pathStartsWith(path: string, prefix: string): boolean {
-  return path === prefix || path.startsWith(`${prefix}.`);
-}
-
 function collectChangedPaths(prev: unknown, next: unknown, prefix = ''): string[] {
   if (isEqual(prev, next)) {
     return [];
@@ -52,58 +49,6 @@ function collectChangedPaths(prev: unknown, next: unknown, prefix = ''): string[
   );
 }
 
-const HOT_RELOAD_ROOTS = ['subtitleStyle', 'keybindings', 'shortcuts', 'subtitleSidebar'] as const;
-
-const HOT_RELOAD_EXACT_OR_PREFIX_PATHS = [
-  'secondarySub.defaultMode',
-  'mpv.aniskipEnabled',
-  'mpv.aniskipButtonKey',
-  'ankiConnect.ai.enabled',
-  'stats.toggleKey',
-  'stats.markWatchedKey',
-  'logging.level',
-  'logging.rotation',
-  'logging.files',
-  'youtube.primarySubLanguages',
-  'jimaku',
-  'subsync',
-  'ankiConnect.deck',
-  'ankiConnect.media.normalizeAudio',
-  'ankiConnect.media.mirrorMpvVolume',
-  'ankiConnect.behavior.autoUpdateNewCards',
-  'ankiConnect.knownWords.highlightEnabled',
-  'ankiConnect.knownWords.refreshMinutes',
-  'ankiConnect.knownWords.addMinedWordsImmediately',
-  'ankiConnect.knownWords.matchMode',
-  'ankiConnect.knownWords.decks',
-  'ankiConnect.nPlusOne.enabled',
-  'ankiConnect.nPlusOne.minSentenceWords',
-  'ankiConnect.fields.word',
-  'ankiConnect.fields.audio',
-  'ankiConnect.fields.image',
-  'ankiConnect.fields.sentence',
-  'ankiConnect.fields.miscInfo',
-  'ankiConnect.isLapis.sentenceCardModel',
-  'ankiConnect.isKiku.fieldGrouping',
-  'ankiConnect.lapisKiku.wordCardKind',
-] as const;
-
-function hotReloadFieldForChangedPath(path: string): string | null {
-  for (const root of HOT_RELOAD_ROOTS) {
-    if (pathStartsWith(path, root)) {
-      return root;
-    }
-  }
-
-  for (const hotPath of HOT_RELOAD_EXACT_OR_PREFIX_PATHS) {
-    if (pathStartsWith(path, hotPath)) {
-      return hotPath === 'jimaku' || hotPath === 'subsync' ? path : hotPath;
-    }
-  }
-
-  return null;
-}
-
 function classifyDiff(prev: ResolvedConfig, next: ResolvedConfig): ConfigHotReloadDiff {
   const hotReloadFields: string[] = [];
   const restartRequiredFields: string[] = [];
@@ -111,33 +56,11 @@ function classifyDiff(prev: ResolvedConfig, next: ResolvedConfig): ConfigHotRelo
   const changedPaths = collectChangedPaths(prev, next);
 
   for (const path of changedPaths) {
-    const hotReloadField = hotReloadFieldForChangedPath(path);
+    const hotReloadField = getConfigHotReloadField(path);
     if (hotReloadField) {
       hotReloadFieldSet.add(hotReloadField);
-    }
-  }
-
-  const keys = new Set([
-    ...(Object.keys(prev) as Array<keyof ResolvedConfig>),
-    ...(Object.keys(next) as Array<keyof ResolvedConfig>),
-  ]);
-
-  for (const key of keys) {
-    if (
-      key === 'subtitleStyle' ||
-      key === 'keybindings' ||
-      key === 'shortcuts' ||
-      key === 'subtitleSidebar'
-    ) {
-      continue;
-    }
-
-    const changedPathsForKey = changedPaths.filter((path) => pathStartsWith(path, String(key)));
-    const hasRestartRequiredChange = changedPathsForKey.some(
-      (path) => !hotReloadFieldForChangedPath(path),
-    );
-    if (hasRestartRequiredChange) {
-      restartRequiredFields.push(String(key));
+    } else {
+      restartRequiredFields.push(path);
     }
   }
 
diff --git a/src/core/services/discord-presence.test.ts b/src/core/services/discord-presence.test.ts
index 4932555f..57149b46 100644
--- a/src/core/services/discord-presence.test.ts
+++ b/src/core/services/discord-presence.test.ts
@@ -91,6 +91,21 @@ test('buildDiscordPresenceActivity shows media title regardless of style', () =>
   }
 });
 
+test('buildDiscordPresenceActivity rejects stream URLs supplied as titles', () => {
+  for (const mediaTitle of [
+    'https://example.com/stream?api_key=test-secret',
+    'stream?api_key=test-secret',
+  ]) {
+    const activity = buildDiscordPresenceActivity(baseConfig, {
+      ...baseSnapshot,
+      mediaPath: 'https://example.com/stream?api_key=test-secret',
+      mediaTitle,
+    });
+    assert.equal(activity.details, 'Unknown media');
+    assert.equal(JSON.stringify(activity).includes('test-secret'), false);
+  }
+});
+
 test('buildDiscordPresenceActivity never falls back to remote stream URLs', () => {
   const payload = buildDiscordPresenceActivity(baseConfig, {
     ...baseSnapshot,
diff --git a/src/core/services/discord-presence.ts b/src/core/services/discord-presence.ts
index 991eb2c4..9cf3859a 100644
--- a/src/core/services/discord-presence.ts
+++ b/src/core/services/discord-presence.ts
@@ -1,5 +1,6 @@
 import type { DiscordPresenceStylePreset } from '../../types/integrations';
 import type { ResolvedConfig } from '../../types';
+import { sanitizeMediaTitle } from '../../shared/media-identity';
 
 export interface DiscordPresenceSnapshot {
   mediaTitle: string | null;
@@ -140,7 +141,7 @@ export function buildDiscordPresenceActivity(
   const style = resolvePresenceStyle(config.presenceStyle);
   const status = buildStatus(snapshot);
   const title = sanitizeText(
-    snapshot.mediaTitle,
+    sanitizeMediaTitle(snapshot.mediaTitle),
     fallbackTitleFromMediaPath(snapshot.mediaPath) || 'Unknown media',
   );
   const details =
diff --git a/src/core/services/hyprland-window-placement.test.ts b/src/core/services/hyprland-window-placement.test.ts
index 79e194ac..ea6fc36e 100644
--- a/src/core/services/hyprland-window-placement.test.ts
+++ b/src/core/services/hyprland-window-placement.test.ts
@@ -156,6 +156,107 @@ test('buildHyprlandPlacementDispatches does not pin already floating overlay win
   );
 });
 
+test('Hyprland placement keeps a recovery dialog above the input-catching overlay', () => {
+  for (const configProvider of ['hyprlang', 'lua']) {
+    for (const retryBounds of [false, true]) {
+      // Bottom to top, as when Hyprland opens its recovery dialog over playback.
+      const stack = ['0xmpv', '0xoverlay', '0xdialog'];
+      const clients = [
+        {
+          address: '0xoverlay',
+          pid: 456,
+          title: 'SubMiner Overlay',
+          floating: true,
+          workspace: { id: 1 },
+          at: [10, 20],
+          size: [100, 100],
+        },
+        {
+          address: '0xdialog',
+          class: 'hyprland-dialog',
+          mapped: true,
+          hidden: false,
+          workspace: { id: 1 },
+        },
+      ];
+      let clientReads = 0;
+      const status = ensureHyprlandWindowFloatingByTitleWithStatus({
+        title: 'SubMiner Overlay',
+        platform: 'linux',
+        env: { HYPRLAND_INSTANCE_SIGNATURE: 'abc' },
+        pid: 456,
+        bounds: retryBounds ? { x: 0, y: 0, width: 1280, height: 720 } : undefined,
+        execFileSync: (_command, args) => {
+          if (args.join(' ') === '-j clients') {
+            clientReads += 1;
+            return JSON.stringify(clients);
+          }
+          if (args.join(' ') === '-j status') return JSON.stringify({ configProvider });
+          if (args.join(' ').match(/alterzorder|alter_zorder/)) {
+            const address = args.join(' ').match(/address:(0x\w+)/)?.[1];
+            assert.ok(address);
+            stack.splice(stack.indexOf(address), 1);
+            stack.push(address);
+          }
+          return '';
+        },
+      });
+      assert.equal(status.dispatched, true);
+      assert.equal(clientReads, retryBounds ? 2 : 1);
+      assert.deepEqual(stack, ['0xmpv', '0xoverlay', '0xdialog'], configProvider);
+    }
+  }
+});
+
+test('Hyprland placement only promotes mapped dialogs on the placed window workspace', () => {
+  const calls: string[] = [];
+  const dialog = {
+    class: 'hyprland-dialog',
+    mapped: true,
+    hidden: false,
+    workspace: { id: 1 },
+  };
+  const clients = [
+    {
+      address: '0xoverlay',
+      pid: 456,
+      title: 'SubMiner Overlay',
+      floating: true,
+      workspace: { id: 1 },
+    },
+    { ...dialog, address: '0xhidden', hidden: true },
+    { ...dialog, address: '0xunmapped', mapped: false },
+    { ...dialog, address: '0xother', workspace: { id: 2 } },
+    { ...dialog, address: '0xordinary', class: 'terminal' },
+    { ...dialog, address: '0xinitial', class: '', initialClass: 'hyprland-dialog' },
+  ];
+  for (const promote of [true, false]) {
+    calls.length = 0;
+    ensureHyprlandWindowFloatingByTitleWithStatus({
+      title: 'SubMiner Overlay',
+      platform: 'linux',
+      env: { HYPRLAND_INSTANCE_SIGNATURE: 'abc' },
+      pid: 456,
+      promote,
+      execFileSync: (_command, args) => {
+        if (args.join(' ') === '-j clients') return JSON.stringify(clients);
+        if (args.join(' ') === '-j status') return JSON.stringify({ configProvider: 'hyprlang' });
+        calls.push(args.join(' '));
+        return '';
+      },
+    });
+    assert.deepEqual(
+      calls,
+      promote
+        ? [
+            'dispatch alterzorder top,address:0xoverlay',
+            'dispatch alterzorder top,address:0xinitial',
+          ]
+        : [],
+    );
+  }
+});
+
 test('buildHyprlandPlacementDispatches can update placement without raising z-order', () => {
   const buildDispatches = buildHyprlandPlacementDispatches as (
     client: Parameters<typeof buildHyprlandPlacementDispatches>[0],
diff --git a/src/core/services/hyprland-window-placement.ts b/src/core/services/hyprland-window-placement.ts
index 16fd217a..6a4bf0a5 100644
--- a/src/core/services/hyprland-window-placement.ts
+++ b/src/core/services/hyprland-window-placement.ts
@@ -3,14 +3,17 @@ import { execFileSync } from 'node:child_process';
 export interface HyprlandPlacementClient {
   address?: string;
   at?: [number, number];
+  class?: string;
   floating?: boolean;
   hidden?: boolean;
+  initialClass?: string;
   initialTitle?: string;
   mapped?: boolean;
   pid?: number;
   pinned?: boolean;
   size?: [number, number];
   title?: string;
+  workspace?: { id: number };
 }
 
 export interface HyprlandPlacementBounds {
@@ -25,7 +28,11 @@ export interface HyprlandPlacementDispatchOptions {
   promote?: boolean;
 }
 
-type ExecFileSync = typeof execFileSync;
+type ExecFileSync = (
+  file: string,
+  args: string[],
+  options: NonNullable<Parameters<typeof execFileSync>[2]>,
+) => ReturnType<typeof execFileSync>;
 export type HyprlandConfigProvider = 'hyprlang' | 'lua';
 
 export function shouldAttemptHyprlandWindowPlacement(
@@ -154,6 +161,33 @@ function luaWindowDispatch(name: string, windowAddress: string, fields: string[]
   ];
 }
 
+// Compositor recovery dialogs must remain clickable even when an overlay still owns input.
+function buildHyprlandDialogPromotionDispatches(
+  clients: HyprlandPlacementClient[],
+  placedClient: HyprlandPlacementClient,
+  configProvider: HyprlandConfigProvider,
+): string[][] {
+  if (typeof placedClient.workspace?.id !== 'number') return [];
+  return clients.flatMap((client) => {
+    if (
+      !client.address ||
+      client.address === placedClient.address ||
+      client.mapped === false ||
+      client.hidden === true ||
+      client.workspace?.id !== placedClient.workspace?.id ||
+      (client.class !== 'hyprland-dialog' && client.initialClass !== 'hyprland-dialog')
+    ) {
+      return [];
+    }
+    const windowAddress = `address:${client.address}`;
+    return [
+      configProvider === 'lua'
+        ? luaWindowDispatch('alter_zorder', windowAddress, ['mode = "top"'])
+        : ['dispatch', 'alterzorder', `top,${windowAddress}`],
+    ];
+  });
+}
+
 function luaWindowSetProp(windowAddress: string, prop: string, value: string): string[] {
   return luaWindowDispatch('set_prop', windowAddress, [
     `prop = ${luaString(prop)}`,
@@ -331,12 +365,16 @@ export function ensureHyprlandWindowFloatingByTitleWithStatus(options: {
       configProvider,
       promote: options.promote,
     });
+    if (options.promote !== false) {
+      dispatches.push(...buildHyprlandDialogPromotionDispatches(clients, client, configProvider));
+    }
     for (const args of dispatches) {
       run('hyprctl', args, { stdio: 'ignore' });
     }
     if (shouldVerifyBounds) {
       try {
-        const refreshedClient = findHyprlandWindowForPlacement(readHyprlandPlacementClients(run), {
+        const refreshedClients = readHyprlandPlacementClients(run);
+        const refreshedClient = findHyprlandWindowForPlacement(refreshedClients, {
           pid: options.pid ?? process.pid,
           title: options.title,
         });
@@ -345,10 +383,20 @@ export function ensureHyprlandWindowFloatingByTitleWithStatus(options: {
           targetBounds &&
           clientMatchesPlacementBounds(refreshedClient, targetBounds) === false
         ) {
-          for (const args of buildHyprlandPlacementDispatches(refreshedClient, targetBounds, {
+          const retryDispatches = buildHyprlandPlacementDispatches(refreshedClient, targetBounds, {
             configProvider,
             promote: options.promote,
-          })) {
+          });
+          if (options.promote !== false) {
+            retryDispatches.push(
+              ...buildHyprlandDialogPromotionDispatches(
+                refreshedClients,
+                refreshedClient,
+                configProvider,
+              ),
+            );
+          }
+          for (const args of retryDispatches) {
             run('hyprctl', args, { stdio: 'ignore' });
           }
         }
diff --git a/src/core/services/immersion-tracker-service.test.ts b/src/core/services/immersion-tracker-service.test.ts
index ae995172..0e30740f 100644
--- a/src/core/services/immersion-tracker-service.test.ts
+++ b/src/core/services/immersion-tracker-service.test.ts
@@ -3003,7 +3003,27 @@ test('startup repairs existing Jellyfin stream video links to metadata rows', as
     const titledStreamUrl =
       'http://jellyfin.local/Videos/item-10/stream?static=true&api_key=secret-token&MediaSourceId=ms-2';
     tracker.handleMediaChange(titledStreamUrl, 'KonoSuba S01E06 Decision! Class Rep');
+    tracker.handleMediaTitleUpdate('stream?static=true&api_key=secret-token');
     tracker.handleMediaChange(null, null);
+    // Safety must hold before metadata registration or a startup repair can run.
+    const liveDb = (tracker as unknown as { db: DatabaseSync }).db;
+    const persistedRows = liveDb.prepare('SELECT * FROM imm_videos').all();
+    assert.equal(JSON.stringify(persistedRows).includes('secret-token'), false);
+    assert.equal(JSON.stringify(persistedRows).includes('/stream'), false);
+    // Recreate the old on-disk representation to retain coverage of startup repair.
+    liveDb
+      .prepare(
+        'UPDATE imm_videos SET video_key = ?, source_url = ?, canonical_title = ? WHERE source_url = ?',
+      )
+      .run(
+        `remote:${streamUrl}`,
+        streamUrl,
+        'stream?static=true&api_key=secret-token',
+        'jellyfin://jellyfin.local/item/item-9',
+      );
+    liveDb
+      .prepare('UPDATE imm_videos SET video_key = ?, source_url = ? WHERE source_url = ?')
+      .run(`remote:${titledStreamUrl}`, titledStreamUrl, 'jellyfin://jellyfin.local/item/item-10');
     tracker.recordJellyfinPlaybackMetadata({
       mediaPath: 'http://jellyfin.local/Videos/item-9/stream?static=true&api_key=secret-token',
       displayTitle: 'Frieren S01E09 Aura the Guillotine',
@@ -3105,6 +3125,91 @@ test('startup repairs existing Jellyfin stream video links to metadata rows', as
   }
 });
 
+test('startup clears leaked parser metadata on safely titled anime without changing assignments', async () => {
+  const dbPath = makeDbPath();
+  let tracker: ImmersionTrackerService | null = null;
+  try {
+    const Ctor = await loadTrackerCtor();
+    tracker = new Ctor({ dbPath });
+    tracker.recordJellyfinPlaybackMetadata({
+      mediaPath: 'https://jellyfin.example/Videos/item/stream?api_key=test-secret',
+      displayTitle: 'My Anime S01E01',
+      itemTitle: 'Episode 1',
+      seriesTitle: 'My Anime',
+      seasonNumber: 1,
+      episodeNumber: 1,
+      itemId: 'item',
+    });
+    const db = (tracker as unknown as { db: DatabaseSync }).db;
+    db.prepare('UPDATE imm_anime SET metadata_json = ?').run(
+      JSON.stringify({
+        filename: 'stream?api_key=test-secret',
+        source: 'guessit',
+      }),
+    );
+    const before = db.prepare('SELECT video_id, anime_id FROM imm_videos').all();
+    tracker.destroy();
+    tracker = new Ctor({ dbPath });
+    const repairedDb = (tracker as unknown as { db: DatabaseSync }).db;
+    assert.deepEqual(repairedDb.prepare('SELECT video_id, anime_id FROM imm_videos').all(), before);
+    assert.deepEqual(
+      repairedDb.prepare('SELECT canonical_title, metadata_json FROM imm_anime').all(),
+      [{ canonical_title: 'My Anime Season 1', metadata_json: null }],
+    );
+  } finally {
+    tracker?.destroy();
+    cleanupDbPath(dbPath);
+  }
+});
+
+test('Jellyfin metadata cleanup requires both an API key and a stream marker', async () => {
+  const dbPath = makeDbPath();
+  let tracker: ImmersionTrackerService | null = null;
+  try {
+    const Ctor = await loadTrackerCtor();
+    tracker = new Ctor({ dbPath });
+    const db = (tracker as unknown as { db: DatabaseSync }).db;
+    const timestamp = toDbTimestamp(trackerNowMs());
+    const cases = [
+      { filename: 'stream?api_key=secret', leaked: true },
+      { filename: '/STREAM?API_KEY=secret', leaked: true },
+      { filename: '/Videos/item?api_key=secret', leaked: true },
+      { filename: '/Videos/item?ApiKey=secret', leaked: true },
+      { filename: 'MediaSourceId=item api key secret', leaked: true },
+      { filename: 'An API Key Story', leaked: false },
+      { filename: 'api_key=ordinary-metadata', leaked: false },
+      { filename: 'stream?quality=high', leaked: false },
+      { filename: '/Videos/item', leaked: false },
+      { filename: 'MediaSourceId=item', leaked: false },
+    ];
+    for (const [index, entry] of cases.entries()) {
+      db.prepare(
+        `
+        INSERT INTO imm_anime (
+          normalized_title_key, canonical_title, metadata_json, CREATED_DATE, LAST_UPDATE_DATE
+        ) VALUES (?, ?, ?, ?, ?)
+      `,
+      ).run(
+        `show-${index}`,
+        `Show ${index}`,
+        JSON.stringify({ filename: entry.filename }),
+        timestamp,
+        timestamp,
+      );
+    }
+    repairJellyfinStreamVideoLinks(db);
+    assert.deepEqual(
+      db.prepare('SELECT metadata_json FROM imm_anime ORDER BY anime_id').all(),
+      cases.map(({ filename, leaked }) => ({
+        metadata_json: leaked ? null : JSON.stringify({ filename }),
+      })),
+    );
+  } finally {
+    tracker?.destroy();
+    cleanupDbPath(dbPath);
+  }
+});
+
 test('Jellyfin link repair removes merged leaked anime rows and sanitizes orphan video titles', async () => {
   const dbPath = makeDbPath();
   let tracker: ImmersionTrackerService | null = null;
@@ -5290,3 +5395,91 @@ test('getVocabularySummary keeps different known-word snapshots independent', as
     cleanupDbPath(dbPath);
   }
 });
+
+for (const provider of ['anilist', 'tmdb'] as const) {
+  test(`${provider} reassignment keeps metadata and artwork on download failure, then replaces or clears both`, async () => {
+    const dbPath = makeDbPath();
+    const originalFetch = globalThis.fetch;
+    let tracker: ImmersionTrackerService | null = null;
+    try {
+      const Ctor = await loadTrackerCtor();
+      tracker = new Ctor({ dbPath });
+      const { db } = tracker as unknown as { db: DatabaseSync };
+      db.exec(`
+        INSERT INTO imm_anime(anime_id, normalized_title_key, canonical_title, CREATED_DATE, LAST_UPDATE_DATE)
+          VALUES (1, 'show', 'Show', 1000, 1000);
+        INSERT INTO imm_videos(video_id, video_key, canonical_title, source_type, anime_id, duration_ms, CREATED_DATE, LAST_UPDATE_DATE)
+          VALUES (1, 'local:/tmp/show.mkv', 'Show', 1, 1, 0, 1000, 1000);
+      `);
+      const tmdb = {
+        tmdbId: 12,
+        tmdbType: 'tv' as const,
+        titleEnglish: 'Drama',
+        titleNative: null,
+        description: 'New description',
+        episodesTotal: 10,
+      };
+      globalThis.fetch = async () => new Response(new Uint8Array([1, 2, 3]));
+      if (provider === 'anilist') {
+        await tracker.reassignAnimeTmdb(1, { ...tmdb, posterUrl: 'https://images.test/old' });
+      } else {
+        await tracker.reassignAnimeAnilist(1, {
+          anilistId: 42,
+          coverUrl: 'https://images.test/old',
+        });
+      }
+      assert.equal(await tracker.hasAnime(1), true);
+      assert.equal(await tracker.hasAnime(999), false);
+      const readMetadata = () =>
+        db.prepare('SELECT * FROM imm_anime WHERE anime_id = 1').get() as {
+          media_kind: string;
+          anilist_id: number | null;
+          tmdb_id: number | null;
+        };
+      const before = readMetadata();
+      const oldArt = await tracker.getAnimeCoverArt(1);
+      const snapshot = (value: unknown) =>
+        JSON.stringify(value, (key, item: unknown) => (key === '_metadata' ? undefined : item));
+      const reassign = (url: string | null) =>
+        provider === 'anilist'
+          ? tracker!.reassignAnimeAnilist(1, { anilistId: 99, coverUrl: url })
+          : tracker!.reassignAnimeTmdb(1, { ...tmdb, posterUrl: url });
+      for (const failure of ['http', 'network']) {
+        globalThis.fetch = async () => {
+          if (failure === 'network') throw new Error('offline');
+          return new Response(null, { status: 503 });
+        };
+        await assert.rejects(reassign('https://images.test/new'));
+        assert.equal(snapshot(readMetadata()), snapshot(before));
+        assert.equal(snapshot(await tracker.getAnimeCoverArt(1)), snapshot(oldArt));
+      }
+      globalThis.fetch = async () => new Response(new Uint8Array([9, 8, 7]));
+      if (provider === 'anilist') {
+        // Retained sessions without lifetime summaries exercise the bootstrap
+        // inside the reassignment transaction.
+        db.exec(`INSERT INTO imm_sessions(session_uuid, video_id, started_at_ms, ended_at_ms,
+          status, active_watched_ms, CREATED_DATE, LAST_UPDATE_DATE)
+          VALUES ('retained-session', 1, '1000', '2000', 2, 1000, 1000, 2000)`);
+      }
+      await reassign('https://images.test/new');
+      const detail = readMetadata();
+      assert.equal(detail.media_kind, provider === 'anilist' ? 'anime' : 'live_action');
+      assert.equal(detail.anilist_id, provider === 'anilist' ? 99 : null);
+      assert.equal(detail.tmdb_id, provider === 'tmdb' ? 12 : null);
+      if (provider === 'anilist') {
+        assert.equal((await tracker.getAnimeDetail(1))?.totalActiveMs, 1000);
+      }
+      assert.deepEqual(
+        new Uint8Array((await tracker.getAnimeCoverArt(1))!.coverBlob!),
+        new Uint8Array([9, 8, 7]),
+      );
+      await reassign(null);
+      assert.equal(await tracker.getAnimeCoverArt(1), null);
+      assert.equal(readMetadata().media_kind, detail.media_kind);
+    } finally {
+      globalThis.fetch = originalFetch;
+      tracker?.destroy();
+      cleanupDbPath(dbPath);
+    }
+  });
+}
diff --git a/src/core/services/immersion-tracker-service.ts b/src/core/services/immersion-tracker-service.ts
index 74f34bea..98f44b0b 100644
--- a/src/core/services/immersion-tracker-service.ts
+++ b/src/core/services/immersion-tracker-service.ts
@@ -1,6 +1,7 @@
 import path from 'node:path';
 import * as fs from 'node:fs';
 import { createLogger } from '../../logger';
+import { sanitizeMediaTitle, toMediaIdentityPath } from '../../shared/media-identity';
 import { MediaGenerator } from '../../media-generator';
 import type { CoverArtFetcher } from './anilist/cover-art-fetcher';
 import { getLocalVideoMetadata, guessAnimeVideoMetadata } from './immersion-tracker/metadata';
@@ -32,6 +33,7 @@ import {
   applySessionLifetimeSummary,
   reconcileStaleActiveSessions,
   rebuildLifetimeSummaries as rebuildLifetimeSummaryTables,
+  rebuildLifetimeSummariesInTransaction,
   recomputeLifetimeAnimeFromMedia,
   recomputeLifetimeGlobalFromSummaries,
   repairLifetimeSummariesFromMedia,
@@ -89,6 +91,7 @@ import {
 } from './immersion-tracker/query-library';
 import {
   cleanupVocabularyStats,
+  clearAnimeCoverArt,
   getVideoDurationMs,
   markVideoWatched,
   upsertCoverArt,
@@ -114,7 +117,7 @@ import {
   dismissAnimeMergeRecommendation,
   getAnimeMergeRecommendations,
   repairLegacySeasonlessAnimeRows,
-  resolveAnimeAnilistConflict,
+  resolveAnimeAnilistConflictInTransaction,
   type AnimeMergeRecommendation,
 } from './immersion-tracker/anime-season-repair';
 import {
@@ -123,6 +126,11 @@ import {
   type AnimeMergeSummary,
   type VideoMoveSummary,
 } from './immersion-tracker/anime-merge';
+import {
+  linkAnimeToTmdbTitleInTransaction,
+  type LiveActionLinkResult,
+  type LiveActionTitleInput,
+} from './immersion-tracker/live-action-link';
 import {
   buildVideoKey,
   deriveCanonicalTitle,
@@ -356,7 +364,7 @@ function normalizeMetadataInt(value: number | null | undefined): number | null {
 function buildJellyfinStatsMediaPath(mediaPath: string, itemId: string): string {
   const normalizedItemId = normalizeText(itemId);
   if (!normalizedItemId) {
-    return mediaPath;
+    return toMediaIdentityPath(mediaPath);
   }
   try {
     const parsed = new URL(mediaPath);
@@ -368,6 +376,7 @@ function buildJellyfinStatsMediaPath(mediaPath: string, itemId: string): string
 
 const JELLYFIN_MEDIA_ALIAS_QUERY_KEYS = [
   'api_key',
+  'ApiKey',
   'StartTimeTicks',
   'AudioStreamIndex',
   'SubtitleStreamIndex',
@@ -817,6 +826,10 @@ export class ImmersionTrackerService {
     return getAnimeDetail(this.db, animeId);
   }
 
+  async hasAnime(animeId: number): Promise<boolean> {
+    return Boolean(this.db.prepare('SELECT 1 FROM imm_anime WHERE anime_id = ?').get(animeId));
+  }
+
   async getAnimeEpisodes(animeId: number): Promise<AnimeEpisodeRow[]> {
     return getAnimeEpisodes(this.db, animeId);
   }
@@ -1015,19 +1028,31 @@ export class ImmersionTrackerService {
       coverUrl?: string | null;
     },
   ): Promise<void> {
+    const coverBlob = await this.downloadReplacementCover(info.coverUrl);
     this.requireWriteQueueDrained('reassigning an AniList entry');
-    // The user is acting on this entry, so it is the one that survives when
-    // another row already claims the same AniList id.
-    const repair = resolveAnimeAnilistConflict(this.db, animeId, info.anilistId, {
-      survivor: 'target',
-      matchConfidence: 'manual',
-    });
-    if (repair.anilistAssignmentBlocked) return;
-    this.db
-      .prepare(
-        `
+    this.db.exec('BEGIN IMMEDIATE');
+    try {
+      this.db
+        .prepare('UPDATE imm_anime SET tmdb_id = NULL, tmdb_type = NULL WHERE anime_id = ?')
+        .run(animeId);
+      // The user is acting on this entry, so it is the one that survives when
+      // another row already claims the same AniList id.
+      const repair = resolveAnimeAnilistConflictInTransaction(this.db, animeId, info.anilistId, {
+        survivor: 'target',
+        matchConfidence: 'manual',
+      });
+      if (repair.anilistAssignmentBlocked) {
+        this.db.exec('ROLLBACK');
+        return;
+      }
+      this.db
+        .prepare(
+          `
       UPDATE imm_anime
       SET anilist_id = ?,
+          media_kind = 'anime',
+          tmdb_id = NULL,
+          tmdb_type = NULL,
           title_romaji = COALESCE(?, title_romaji),
           title_english = COALESCE(?, title_english),
           title_native = COALESCE(?, title_native),
@@ -1036,46 +1061,32 @@ export class ImmersionTrackerService {
           LAST_UPDATE_DATE = ?
       WHERE anime_id = ?
     `,
-      )
-      .run(
-        info.anilistId,
-        info.titleRomaji ?? null,
-        info.titleEnglish ?? null,
-        info.titleNative ?? null,
-        info.episodesTotal ?? null,
-        info.description !== undefined ? 1 : 0,
-        info.description ?? null,
-        nowMs(),
-        animeId,
-      );
-    // Empty lifetime tables still need the retained-session bootstrap. Once a
-    // media ledger exists, only the redistributed and explicitly edited anime
-    // can have changed.
-    if (shouldBackfillLifetimeSummaries(this.db)) {
-      repairLifetimeSummariesFromMedia(this.db);
-    } else {
-      const affectedAnimeIds = new Set(repair.affectedAnimeIds);
-      affectedAnimeIds.add(animeId);
-      recomputeLifetimeAnimeFromMedia(this.db, [...affectedAnimeIds]);
-      recomputeLifetimeGlobalFromSummaries(this.db);
-    }
-
-    // Update cover art for all videos in this anime
-    if (info.coverUrl) {
-      const videos = this.db
-        .prepare('SELECT video_id FROM imm_videos WHERE anime_id = ?')
-        .all(animeId) as Array<{ video_id: number }>;
-      let coverBlob: Buffer | null = null;
-      try {
-        const res = await fetch(info.coverUrl);
-        if (res.ok) {
-          coverBlob = Buffer.from(await res.arrayBuffer());
-        }
-      } catch {
-        /* ignore */
+        )
+        .run(
+          info.anilistId,
+          info.titleRomaji ?? null,
+          info.titleEnglish ?? null,
+          info.titleNative ?? null,
+          info.episodesTotal ?? null,
+          info.description !== undefined ? 1 : 0,
+          info.description ?? null,
+          nowMs(),
+          animeId,
+        );
+      // Empty lifetime tables still need the retained-session bootstrap. Once a
+      // media ledger exists, only the redistributed and explicitly edited anime
+      // can have changed.
+      if (shouldBackfillLifetimeSummaries(this.db)) {
+        rebuildLifetimeSummariesInTransaction(this.db);
+      } else {
+        const affectedAnimeIds = new Set(repair.affectedAnimeIds);
+        affectedAnimeIds.add(animeId);
+        recomputeLifetimeAnimeFromMedia(this.db, [...affectedAnimeIds]);
+        recomputeLifetimeGlobalFromSummaries(this.db);
       }
-      for (const v of videos) {
-        upsertCoverArt(this.db, v.video_id, {
+
+      if (info.coverUrl) {
+        this.applyCoverArtToAnimeVideos(animeId, {
           anilistId: info.anilistId,
           coverUrl: info.coverUrl,
           coverBlob,
@@ -1083,7 +1094,85 @@ export class ImmersionTrackerService {
           titleEnglish: info.titleEnglish ?? null,
           episodesTotal: info.episodesTotal ?? null,
         });
+      } else {
+        clearAnimeCoverArt(this.db, animeId);
       }
+      this.db.exec('COMMIT');
+    } catch (error) {
+      this.db.exec('ROLLBACK');
+      throw error;
+    }
+  }
+
+  /**
+   * Link a library entry to a TMDB title chosen in the dashboard. Every other
+   * entry pointing at the same title is folded into this one, and its poster
+   * replaces the art of every episode.
+   */
+  async reassignAnimeTmdb(
+    animeId: number,
+    details: LiveActionTitleInput & { posterUrl: string | null },
+  ): Promise<LiveActionLinkResult> {
+    const coverBlob = await this.downloadReplacementCover(details.posterUrl);
+    this.requireWriteQueueDrained('linking a TMDB title');
+    this.db.exec('BEGIN IMMEDIATE');
+    try {
+      const result = linkAnimeToTmdbTitleInTransaction(this.db, animeId, details, {
+        mode: 'manual',
+      });
+      if (details.posterUrl) {
+        this.applyCoverArtToAnimeVideos(result.animeId, {
+          anilistId: null,
+          coverUrl: details.posterUrl,
+          coverBlob,
+          titleRomaji: null,
+          titleEnglish: details.titleEnglish,
+          episodesTotal: details.episodesTotal,
+        });
+      } else {
+        // The user chose this title deliberately, so art from the previous link
+        // must not keep standing in for it.
+        clearAnimeCoverArt(this.db, result.animeId);
+      }
+      this.db.exec('COMMIT');
+      return result;
+    } catch (error) {
+      this.db.exec('ROLLBACK');
+      throw error;
+    }
+  }
+
+  private async downloadReplacementCover(url: string | null | undefined): Promise<Buffer | null> {
+    if (!url) return null;
+    const response = await fetch(url);
+    if (!response.ok) throw new Error(`Cover download failed: ${response.status}`);
+    return Buffer.from(await response.arrayBuffer());
+  }
+
+  /** Stores the downloaded replacement against every episode of the entry. */
+  private applyCoverArtToAnimeVideos(
+    animeId: number,
+    art: {
+      anilistId: number | null;
+      coverUrl: string;
+      coverBlob: Buffer | null;
+      titleRomaji: string | null;
+      titleEnglish: string | null;
+      episodesTotal: number | null;
+    },
+  ): void {
+    const videos = this.db
+      .prepare('SELECT video_id FROM imm_videos WHERE anime_id = ?')
+      .all(animeId) as Array<{ video_id: number }>;
+    for (const v of videos) {
+      upsertCoverArt(this.db, v.video_id, {
+        anilistId: art.anilistId,
+        coverUrl: art.coverUrl,
+        coverBlob: art.coverBlob,
+        titleRomaji: art.titleRomaji,
+        titleEnglish: art.titleEnglish,
+        episodesTotal: art.episodesTotal,
+      });
     }
   }
 
@@ -1520,11 +1609,11 @@ export class ImmersionTrackerService {
     }
 
     const displayTitle =
-      normalizeText(metadata.displayTitle) ||
-      normalizeText(metadata.itemTitle) ||
+      normalizeText(sanitizeMediaTitle(metadata.displayTitle)) ||
+      normalizeText(sanitizeMediaTitle(metadata.itemTitle)) ||
       deriveCanonicalTitle(normalizedPath);
-    const itemTitle = normalizeText(metadata.itemTitle) || displayTitle;
-    const seriesTitle = normalizeText(metadata.seriesTitle);
+    const itemTitle = normalizeText(sanitizeMediaTitle(metadata.itemTitle)) || displayTitle;
+    const seriesTitle = normalizeText(sanitizeMediaTitle(metadata.seriesTitle));
     const libraryTitle = seriesTitle || itemTitle;
     const seasonNumber = normalizeMetadataInt(metadata.seasonNumber);
     const episodeNumber = normalizeMetadataInt(metadata.episodeNumber);
@@ -1611,8 +1700,8 @@ export class ImmersionTrackerService {
     const normalizedPath =
       buildJellyfinMediaPathAliasCandidates(rawPath)
         .map((alias) => this.mediaPathAliases.get(alias))
-        .find((alias): alias is string => Boolean(alias)) ?? rawPath;
-    const normalizedTitle = normalizeText(mediaTitle);
+        .find((alias): alias is string => Boolean(alias)) ?? toMediaIdentityPath(rawPath);
+    const normalizedTitle = normalizeText(sanitizeMediaTitle(mediaTitle));
     this.logger.info(
       `handleMediaChange called with path=${normalizedPath || '<empty>'} title=${normalizedTitle || '<empty>'}`,
     );
@@ -1670,7 +1759,7 @@ export class ImmersionTrackerService {
 
   handleMediaTitleUpdate(mediaTitle: string | null): void {
     if (!this.sessionState) return;
-    const normalizedTitle = normalizeText(mediaTitle);
+    const normalizedTitle = normalizeText(sanitizeMediaTitle(mediaTitle));
     if (!normalizedTitle) return;
     this.currentVideoKey = normalizedTitle;
     this.updateVideoTitleForActiveSession(normalizedTitle);
diff --git a/src/core/services/immersion-tracker/__tests__/anime-merge.test.ts b/src/core/services/immersion-tracker/__tests__/anime-merge.test.ts
index 96250e0b..1dbdac83 100644
--- a/src/core/services/immersion-tracker/__tests__/anime-merge.test.ts
+++ b/src/core/services/immersion-tracker/__tests__/anime-merge.test.ts
@@ -13,7 +13,11 @@ import {
   getOrCreateAnimeRecord,
   linkVideoToAnimeRecord,
 } from '../storage.js';
-import { mergeAnimeRecords, moveVideoToAnime } from '../anime-merge.js';
+import {
+  MEDIA_KIND_MISMATCH_MESSAGE,
+  mergeAnimeRecords,
+  moveVideoToAnime,
+} from '../anime-merge.js';
 import {
   dismissAnimeMergeRecommendation,
   getAnimeMergeRecommendations,
@@ -940,3 +944,36 @@ test('automatic AniList update onto an entry that already links elsewhere does n
     );
   });
 });
+
+test('merge and move refuse to mix anime entries with YouTube channels', () => {
+  withDb((db) => {
+    insertAnime(db, { animeId: 1, key: 'some anime', title: 'Some Anime', anilistId: 555 });
+    insertAnime(db, { animeId: 2, key: 'youtube channel uc123', title: 'Channel' });
+    db.prepare("UPDATE imm_anime SET media_kind = 'youtube' WHERE anime_id = 2").run();
+    insertEpisode(db, { videoId: 10, animeId: 1 });
+    insertEpisode(db, { videoId: 20, animeId: 2 });
+
+    assert.throws(() => mergeAnimeRecords(db, 1, [2]), { message: MEDIA_KIND_MISMATCH_MESSAGE });
+    assert.throws(() => mergeAnimeRecords(db, 2, [1]), { message: MEDIA_KIND_MISMATCH_MESSAGE });
+    assert.throws(() => moveVideoToAnime(db, 20, 1), { message: MEDIA_KIND_MISMATCH_MESSAGE });
+    assert.throws(() => moveVideoToAnime(db, 10, 2), { message: MEDIA_KIND_MISMATCH_MESSAGE });
+
+    const rows = db
+      .prepare(
+        'SELECT anime_id AS animeId, media_kind AS mediaKind FROM imm_anime ORDER BY anime_id',
+      )
+      .all() as Array<{ animeId: number; mediaKind: string }>;
+    assert.deepEqual(rows, [
+      { animeId: 1, mediaKind: 'anime' },
+      { animeId: 2, mediaKind: 'youtube' },
+    ]);
+    assert.equal(
+      (
+        db.prepare('SELECT anime_id AS animeId FROM imm_videos WHERE video_id = 20').get() as {
+          animeId: number;
+        }
+      ).animeId,
+      2,
+    );
+  });
+});
diff --git a/src/core/services/immersion-tracker/__tests__/live-action-link.test.ts b/src/core/services/immersion-tracker/__tests__/live-action-link.test.ts
new file mode 100644
index 00000000..ebddde0f
--- /dev/null
+++ b/src/core/services/immersion-tracker/__tests__/live-action-link.test.ts
@@ -0,0 +1,309 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import test from 'node:test';
+import { Database } from '../sqlite.js';
+import type { DatabaseSync } from '../sqlite.js';
+import { applyPragmas, ensureSchema, getOrCreateAnimeRecord } from '../storage.js';
+import { repairLegacySeasonlessAnimeRows } from '../anime-season-repair.js';
+import { mergeAnimeRecords, mergeAnimeRecordsInTransaction } from '../anime-merge.js';
+import { getVideoTmdbLink, linkAnimeToTmdbTitle } from '../live-action-link.js';
+import { getAnimeCoverArt, getCoverArt } from '../query-library.js';
+import { clearAnimeCoverArt, upsertCoverArt } from '../query-maintenance.js';
+
+const BASE_MS = 1_700_000_000_000;
+
+function withDb(work: (db: DatabaseSync) => void): void {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'subminer-live-action-link-'));
+  const db = new Database(path.join(dir, 'immersion.sqlite'));
+  try {
+    applyPragmas(db);
+    ensureSchema(db);
+    work(db);
+  } finally {
+    db.close();
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+function insertAnime(
+  db: DatabaseSync,
+  animeId: number,
+  title: string,
+  anilistId: number | null = null,
+) {
+  db.prepare(
+    `INSERT INTO imm_anime(anime_id, normalized_title_key, canonical_title, anilist_id, CREATED_DATE, LAST_UPDATE_DATE)
+     VALUES (?, ?, ?, ?, ?, ?)`,
+  ).run(animeId, title.toLowerCase(), title, anilistId, BASE_MS, BASE_MS);
+}
+
+function insertEpisode(db: DatabaseSync, videoId: number, animeId: number, season: number | null) {
+  db.prepare(
+    `INSERT INTO imm_videos(video_id, video_key, anime_id, canonical_title, source_type, parsed_title, parsed_season, parsed_episode, watched, duration_ms, CREATED_DATE, LAST_UPDATE_DATE)
+     VALUES (?, ?, ?, ?, 1, 'Hanzawa Naoki', ?, ?, 1, 1440000, ?, ?)`,
+  ).run(
+    videoId,
+    `local:/tmp/${videoId}.mkv`,
+    animeId,
+    `Ep ${videoId}`,
+    season,
+    videoId,
+    BASE_MS,
+    BASE_MS,
+  );
+  db.prepare(
+    `INSERT INTO imm_lifetime_media(video_id, total_sessions, total_active_ms, total_cards, completed, first_watched_ms, last_watched_ms, CREATED_DATE, LAST_UPDATE_DATE)
+     VALUES (?, 1, 1000, 0, 1, ?, ?, ?, ?)`,
+  ).run(videoId, String(BASE_MS), String(BASE_MS + 1000), BASE_MS, BASE_MS);
+}
+
+interface AnimeRowView {
+  mediaKind: string;
+  tmdbId: number | null;
+  tmdbType: string | null;
+  anilistId: number | null;
+  titleEnglish: string | null;
+  titleNative: string | null;
+  description: string | null;
+}
+
+// Copies the selected columns so the driver's row metadata does not leak into
+// deep-equality assertions.
+function animeRow(db: DatabaseSync, animeId: number): AnimeRowView | undefined {
+  const row = db
+    .prepare(
+      `SELECT media_kind AS mediaKind, tmdb_id AS tmdbId, tmdb_type AS tmdbType, anilist_id AS anilistId,
+              title_english AS titleEnglish, title_native AS titleNative, description
+       FROM imm_anime WHERE anime_id = ?`,
+    )
+    .get(animeId) as AnimeRowView | undefined;
+  if (!row) return undefined;
+  const { mediaKind, tmdbId, tmdbType, anilistId, titleEnglish, titleNative, description } = row;
+  return { mediaKind, tmdbId, tmdbType, anilistId, titleEnglish, titleNative, description };
+}
+
+function animeCount(db: DatabaseSync): number {
+  return (db.prepare('SELECT COUNT(*) AS n FROM imm_anime').get() as { n: number }).n;
+}
+
+function videoOwner(db: DatabaseSync, videoId: number): number | null {
+  return (
+    db.prepare('SELECT anime_id AS animeId FROM imm_videos WHERE video_id = ?').get(videoId) as {
+      animeId: number | null;
+    }
+  ).animeId;
+}
+
+const HANZAWA = {
+  tmdbId: 61222,
+  tmdbType: 'tv' as const,
+  titleEnglish: 'Hanzawa Naoki',
+  titleNative: '半沢直樹',
+  description: 'A banker fights back.',
+  episodesTotal: 10,
+};
+
+test('a manual link overwrites metadata, drops the AniList link, and folds other holders in', () => {
+  withDb((db) => {
+    insertAnime(db, 1, 'Hanzawa Naoki', 4242);
+    insertAnime(db, 2, 'Hanzawa Naoki Season 2');
+    insertEpisode(db, 1, 1, 1);
+    insertEpisode(db, 2, 2, 2);
+    db.prepare(
+      `UPDATE imm_anime SET media_kind = 'live_action', tmdb_id = ?, tmdb_type = 'tv', description = 'old' WHERE anime_id = 2`,
+    ).run(HANZAWA.tmdbId);
+
+    const result = linkAnimeToTmdbTitle(db, 1, HANZAWA, { mode: 'manual' });
+
+    assert.deepEqual(result, { animeId: 1, mergedAnimeIds: [2] });
+    assert.deepEqual(animeRow(db, 1), {
+      mediaKind: 'live_action',
+      tmdbId: 61222,
+      tmdbType: 'tv',
+      anilistId: null,
+      titleEnglish: 'Hanzawa Naoki',
+      titleNative: '半沢直樹',
+      description: 'A banker fights back.',
+    });
+    assert.equal(animeRow(db, 2), undefined);
+    assert.equal(animeCount(db), 1);
+    assert.equal(videoOwner(db, 2), 1);
+    assert.deepEqual(getVideoTmdbLink(db, 2), { animeId: 1, tmdbId: 61222, tmdbType: 'tv' });
+  });
+});
+
+test('an automatic link joins the entry that already owns the title and only fills gaps', () => {
+  withDb((db) => {
+    insertAnime(db, 1, 'Hanzawa Naoki');
+    insertEpisode(db, 1, 1, 1);
+    linkAnimeToTmdbTitle(db, 1, { ...HANZAWA, description: 'kept' }, { mode: 'manual' });
+    const newcomer = getOrCreateAnimeRecord(db, {
+      parsedTitle: 'Hanzawa Naoki',
+      canonicalTitle: 'Hanzawa Naoki',
+      seasonScope: 2,
+      anilistId: null,
+      titleRomaji: null,
+      titleEnglish: null,
+      titleNative: null,
+      metadataJson: null,
+    });
+    insertEpisode(db, 2, newcomer, 2);
+
+    const result = linkAnimeToTmdbTitle(db, newcomer, HANZAWA, { mode: 'auto' });
+
+    assert.deepEqual(result, { animeId: 1, mergedAnimeIds: [newcomer] });
+    assert.equal(animeRow(db, 1)?.description, 'kept');
+    assert.equal(animeCount(db), 1);
+    assert.equal(videoOwner(db, 2), 1);
+    // The merged-away season title is remembered, so the next episode of that
+    // season lands on the survivor without a detour through a new row.
+    const again = getOrCreateAnimeRecord(db, {
+      parsedTitle: 'Hanzawa Naoki',
+      canonicalTitle: 'Hanzawa Naoki',
+      seasonScope: 2,
+      anilistId: null,
+      titleRomaji: null,
+      titleEnglish: null,
+      titleNative: null,
+      metadataJson: null,
+    });
+    assert.equal(again, 1);
+  });
+});
+
+test('startup season repair leaves multi-season live-action entries alone', () => {
+  withDb((db) => {
+    insertAnime(db, 1, 'Hanzawa Naoki');
+    insertEpisode(db, 1, 1, 1);
+    insertEpisode(db, 2, 1, 2);
+    linkAnimeToTmdbTitle(db, 1, HANZAWA, { mode: 'manual' });
+
+    repairLegacySeasonlessAnimeRows(db);
+
+    assert.equal(animeCount(db), 1);
+    assert.equal(videoOwner(db, 1), 1);
+    assert.equal(videoOwner(db, 2), 1);
+    assert.equal(getVideoTmdbLink(db, 2)?.animeId, 1);
+  });
+});
+
+test('getVideoTmdbLink is null for anime entries and unlinked videos', () => {
+  withDb((db) => {
+    insertAnime(db, 1, 'Some Anime', 77);
+    insertEpisode(db, 1, 1, 1);
+    assert.equal(getVideoTmdbLink(db, 1), null);
+    assert.equal(getVideoTmdbLink(db, 99), null);
+  });
+});
+
+test('clearAnimeCoverArt drops every episode cover of the entry and its orphaned blob', () => {
+  withDb((db) => {
+    insertAnime(db, 1, 'Hanzawa Naoki');
+    insertAnime(db, 2, 'Other Show');
+    insertEpisode(db, 1, 1, 1);
+    insertEpisode(db, 2, 1, 1);
+    insertEpisode(db, 3, 2, 1);
+    const shared = Buffer.from([1, 2, 3]);
+    for (const videoId of [1, 2]) {
+      upsertCoverArt(db, videoId, {
+        anilistId: 4242,
+        coverUrl: 'https://images.test/a.jpg',
+        coverBlob: shared,
+        titleRomaji: null,
+        titleEnglish: null,
+        episodesTotal: null,
+      });
+    }
+    upsertCoverArt(db, 3, {
+      anilistId: 99,
+      coverUrl: 'https://images.test/b.jpg',
+      coverBlob: Buffer.from([9]),
+      titleRomaji: null,
+      titleEnglish: null,
+      episodesTotal: null,
+    });
+
+    clearAnimeCoverArt(db, 1);
+
+    assert.equal(getAnimeCoverArt(db, 1), null);
+    assert.equal(getCoverArt(db, 3)?.coverBlob?.length, 1);
+    const blobs = (
+      db.prepare('SELECT COUNT(*) AS n FROM imm_cover_art_blobs').get() as { n: number }
+    ).n;
+    assert.equal(blobs, 1);
+  });
+});
+
+for (const targetId of [1, 2, 3]) {
+  test(`merge rejects mixed providers before moving any source into entry ${targetId}`, () => {
+    withDb((db) => {
+      insertAnime(db, 1, 'Anime', 77);
+      insertAnime(db, 2, 'Drama');
+      insertAnime(db, 3, 'Unlinked');
+      insertEpisode(db, 1, 1, 1);
+      insertEpisode(db, 2, 2, 1);
+      db.exec(
+        "UPDATE imm_anime SET media_kind = 'live_action', tmdb_id = 12, tmdb_type = 'tv' WHERE anime_id = 2",
+      );
+      for (const merge of [mergeAnimeRecords, mergeAnimeRecordsInTransaction]) {
+        assert.throws(
+          () => merge(db, targetId, [3, 1, 2]),
+          /AniList-linked and TMDB-linked library entries cannot be merged/,
+        );
+        assert.equal(animeCount(db), 3);
+        assert.equal(videoOwner(db, 1), 1);
+        assert.equal(videoOwner(db, 2), 2);
+      }
+    });
+  });
+}
+
+for (const mode of ['manual', 'auto'] as const) {
+  test(`TMDB ${mode} linking rolls back the merge when the survivor update fails`, () => {
+    withDb((db) => {
+      insertAnime(db, 1, 'New entry');
+      insertAnime(db, 2, 'Existing entry');
+      insertEpisode(db, 1, 1, 1);
+      insertEpisode(db, 2, 2, 2);
+      db.prepare(
+        "UPDATE imm_anime SET tmdb_id = ?, tmdb_type = 'tv', media_kind = 'live_action' WHERE anime_id = 2",
+      ).run(HANZAWA.tmdbId);
+      db.exec(`CREATE TRIGGER reject_link BEFORE UPDATE ON imm_anime
+        WHEN NEW.description = 'A banker fights back.'
+        BEGIN SELECT RAISE(ABORT, 'rejected survivor update'); END`);
+      assert.throws(
+        () => linkAnimeToTmdbTitle(db, 1, HANZAWA, { mode }),
+        /rejected survivor update/,
+      );
+      assert.equal(animeCount(db), 2);
+      assert.equal(videoOwner(db, 1), 1);
+      assert.equal(videoOwner(db, 2), 2);
+      assert.equal(animeRow(db, 1)?.tmdbId, null);
+      assert.equal(animeRow(db, 2)?.tmdbId, HANZAWA.tmdbId);
+    });
+  });
+}
+
+for (const mode of ['manual', 'auto'] as const) {
+  test(`${mode} TMDB linking refreshes completion totals without merging records`, () => {
+    withDb((db) => {
+      insertAnime(db, 1, 'Hanzawa Naoki');
+      insertEpisode(db, 1, 1, 1);
+      const completed = () =>
+        (
+          db
+            .prepare('SELECT anime_completed AS count FROM imm_lifetime_global WHERE global_id = 1')
+            .get() as { count: number }
+        ).count;
+      assert.equal(completed(), 0);
+      const result = linkAnimeToTmdbTitle(db, 1, { ...HANZAWA, episodesTotal: 1 }, { mode });
+      assert.deepEqual(result.mergedAnimeIds, []);
+      assert.equal(completed(), 1);
+      linkAnimeToTmdbTitle(db, 1, { ...HANZAWA, episodesTotal: 2 }, { mode: 'manual' });
+      assert.equal(completed(), 0);
+      assert.equal(animeCount(db), 1);
+    });
+  });
+}
diff --git a/src/core/services/immersion-tracker/anime-merge-recommendations.ts b/src/core/services/immersion-tracker/anime-merge-recommendations.ts
index 6ac0c096..1ad96e97 100644
--- a/src/core/services/immersion-tracker/anime-merge-recommendations.ts
+++ b/src/core/services/immersion-tracker/anime-merge-recommendations.ts
@@ -27,7 +27,7 @@ function getAnimeTitles(db: DatabaseSync, animeId: number): AnimeTitleRow | null
     .prepare(
       `SELECT canonical_title, title_romaji, title_english, title_native
        FROM imm_anime
-       WHERE anime_id = ?`,
+       WHERE anime_id = ? AND media_kind = 'anime'`,
     )
     .get(animeId) as AnimeTitleRow | null;
 }
@@ -77,6 +77,7 @@ export function shouldRecommendAnilistConflict(
   conflictAnimeId: number,
   options: AnimeConflictRecommendationOptions,
 ): boolean {
+  if (!getAnimeTitles(db, targetAnimeId) || !getAnimeTitles(db, conflictAnimeId)) return false;
   if (options.survivor === 'target' || options.matchConfidence === 'manual') return false;
   if (
     !animeSeasonsAreMergeCompatible(
@@ -99,6 +100,8 @@ export function recordAnimeMergeRecommendation(
   secondCandidateAnimeId: number,
   anilistId: number,
 ): void {
+  if (!getAnimeTitles(db, firstCandidateAnimeId) || !getAnimeTitles(db, secondCandidateAnimeId))
+    return;
   const firstAnimeId = Math.min(firstCandidateAnimeId, secondCandidateAnimeId);
   const secondAnimeId = Math.max(firstCandidateAnimeId, secondCandidateAnimeId);
   const timestamp = toDbTimestamp(nowMs());
@@ -141,6 +144,8 @@ export function getAnimeMergeRecommendations(db: DatabaseSync): AnimeMergeRecomm
                 second_anime_id AS secondAnimeId
          FROM imm_anime_merge_recommendations
          WHERE status = 'pending'
+           AND first_anime_id IN (SELECT anime_id FROM imm_anime WHERE media_kind = 'anime')
+           AND second_anime_id IN (SELECT anime_id FROM imm_anime WHERE media_kind = 'anime')
          ORDER BY recommendation_id ASC`,
       )
       .all() as Array<{
diff --git a/src/core/services/immersion-tracker/anime-merge.ts b/src/core/services/immersion-tracker/anime-merge.ts
index 7c347297..6a2ac897 100644
--- a/src/core/services/immersion-tracker/anime-merge.ts
+++ b/src/core/services/immersion-tracker/anime-merge.ts
@@ -1,3 +1,4 @@
+import { shareTitleNamespace, type MediaKind } from '../../../shared/media-kind';
 import type { DatabaseSync } from './sqlite';
 import { recomputeLifetimeAnimeAggregatesInTransaction } from './lifetime';
 import { toDbTimestamp } from './query-shared';
@@ -5,6 +6,12 @@ import { nowMs } from './time';
 
 /** Thrown when a move names an episode or destination entry that is not there. */
 export const UNKNOWN_MOVE_TARGET_MESSAGE = 'Unknown episode or target library entry';
+/** Thrown when a merge would combine an AniList-linked entry with a TMDB-linked one. */
+export const INCOMPATIBLE_PROVIDER_MERGE_MESSAGE =
+  'AniList-linked and TMDB-linked library entries cannot be merged together';
+/** Thrown when a merge or move would mix a YouTube channel with an anime or live-action entry. */
+export const MEDIA_KIND_MISMATCH_MESSAGE =
+  'YouTube channels cannot be combined with anime or live-action entries';
 
 export interface AnimeMergeSummary {
   /** Library entry that owns every moved episode once the merge finishes. */
@@ -30,6 +37,9 @@ interface AnimeMetadataRow {
   title_native: string | null;
   episodes_total: number | null;
   description: string | null;
+  media_kind: string;
+  tmdb_id: number | null;
+  tmdb_type: string | null;
 }
 
 function emptyMergeSummary(survivingAnimeId: number): AnimeMergeSummary {
@@ -52,7 +62,8 @@ function readAnimeMetadata(db: DatabaseSync, animeId: number): AnimeMetadataRow
   return (db
     .prepare(
       `
-        SELECT normalized_title_key, anilist_id, title_romaji, title_english, title_native, episodes_total, description
+        SELECT normalized_title_key, anilist_id, title_romaji, title_english, title_native, episodes_total, description,
+               media_kind, tmdb_id, tmdb_type
         FROM imm_anime
         WHERE anime_id = ?
       `,
@@ -60,8 +71,11 @@ function readAnimeMetadata(db: DatabaseSync, animeId: number): AnimeMetadataRow
     .get(animeId) ?? null) as AnimeMetadataRow | null;
 }
 
-function animeExists(db: DatabaseSync, animeId: number): boolean {
-  return Boolean(db.prepare('SELECT 1 FROM imm_anime WHERE anime_id = ?').get(animeId));
+function readMediaKind(db: DatabaseSync, animeId: number): MediaKind | null {
+  const row = db
+    .prepare('SELECT media_kind AS mediaKind FROM imm_anime WHERE anime_id = ?')
+    .get(animeId) as { mediaKind: MediaKind } | undefined;
+  return row?.mediaKind ?? null;
 }
 
 function hasAnimeReferences(db: DatabaseSync, animeId: number): boolean {
@@ -131,6 +145,12 @@ function absorbAnimeMetadata(
         title_native = COALESCE(title_native, ?),
         episodes_total = COALESCE(episodes_total, ?),
         description = COALESCE(description, ?),
+        tmdb_id = COALESCE(tmdb_id, ?),
+        tmdb_type = CASE WHEN tmdb_id IS NULL THEN ? ELSE tmdb_type END,
+        media_kind = CASE
+          WHEN anilist_id IS NULL AND tmdb_id IS NULL AND ? IS NOT NULL THEN ?
+          ELSE media_kind
+        END,
         LAST_UPDATE_DATE = ?
       WHERE anime_id = ?
     `,
@@ -141,6 +161,10 @@ function absorbAnimeMetadata(
     source.title_native,
     source.episodes_total,
     source.description,
+    source.tmdb_id,
+    source.tmdb_type,
+    source.tmdb_id,
+    source.media_kind,
     updatedAt,
     targetAnimeId,
   );
@@ -161,10 +185,23 @@ export function mergeAnimeRecordsInTransaction(
   sourceAnimeIds: number[],
 ): AnimeMergeSummary {
   const summary = emptyMergeSummary(targetAnimeId);
-  if (!animeExists(db, targetAnimeId)) {
+  const targetKind = readMediaKind(db, targetAnimeId);
+  if (targetKind === null) {
     return summary;
   }
 
+  // Validate the whole group before moving anything, including when the
+  // unlinked target would inherit conflicting providers from two sources.
+  const metadata = [targetAnimeId, ...new Set(sourceAnimeIds)].map((id) =>
+    readAnimeMetadata(db, id),
+  );
+  if (
+    metadata.some((row) => row?.anilist_id != null) &&
+    metadata.some((row) => row?.tmdb_id != null)
+  ) {
+    throw new Error(INCOMPATIBLE_PROVIDER_MERGE_MESSAGE);
+  }
+
   const updatedAt = toDbTimestamp(nowMs());
   const sourceVideosStmt = db.prepare(
     'SELECT video_id AS videoId FROM imm_videos WHERE anime_id = ?',
@@ -195,8 +232,13 @@ export function mergeAnimeRecordsInTransaction(
   const dropAnimeStmt = db.prepare('DELETE FROM imm_anime WHERE anime_id = ?');
 
   for (const sourceAnimeId of new Set(sourceAnimeIds)) {
-    if (sourceAnimeId === targetAnimeId || !animeExists(db, sourceAnimeId)) {
-      continue;
+    if (sourceAnimeId === targetAnimeId) continue;
+    const sourceKind = readMediaKind(db, sourceAnimeId);
+    if (sourceKind === null) continue;
+    // A channel folded into an anime would only be recreated on the next
+    // watch, because title lookups never cross namespaces; refuse instead.
+    if (!shareTitleNamespace(sourceKind, targetKind)) {
+      throw new Error(MEDIA_KIND_MISMATCH_MESSAGE);
     }
 
     const sourceMetadata = readAnimeMetadata(db, sourceAnimeId);
@@ -257,11 +299,16 @@ export function moveVideoToAnime(
     const videoRow = db
       .prepare('SELECT anime_id AS animeId FROM imm_videos WHERE video_id = ?')
       .get(videoId) as { animeId: number | null } | null;
-    if (!videoRow || !animeExists(db, targetAnimeId)) {
+    const targetKind = readMediaKind(db, targetAnimeId);
+    if (!videoRow || targetKind === null) {
       throw new Error(UNKNOWN_MOVE_TARGET_MESSAGE);
     }
 
     const previousAnimeId = videoRow.animeId;
+    const previousKind = previousAnimeId === null ? null : readMediaKind(db, previousAnimeId);
+    if (previousKind !== null && !shareTitleNamespace(previousKind, targetKind)) {
+      throw new Error(MEDIA_KIND_MISMATCH_MESSAGE);
+    }
     if (previousAnimeId === targetAnimeId) {
       db.prepare(
         'UPDATE imm_videos SET anime_assignment_locked = 1, LAST_UPDATE_DATE = ? WHERE video_id = ?',
diff --git a/src/core/services/immersion-tracker/anime-season-repair.ts b/src/core/services/immersion-tracker/anime-season-repair.ts
index ced3ed18..4d33d3aa 100644
--- a/src/core/services/immersion-tracker/anime-season-repair.ts
+++ b/src/core/services/immersion-tracker/anime-season-repair.ts
@@ -134,7 +134,7 @@ function getAnimeRow(db: DatabaseSync, animeId: number): AnimeRow | null {
           episodes_total,
           description
         FROM imm_anime
-        WHERE anime_id = ?
+        WHERE anime_id = ? AND media_kind != 'youtube'
       `,
     )
     .get(animeId) as AnimeRow | null;
@@ -335,7 +335,8 @@ export function repairLegacySeasonlessAnimeRows(db: DatabaseSync): AnimeSeasonRe
           SELECT a.anime_id AS animeId
           FROM imm_anime a
           JOIN imm_videos v ON v.anime_id = a.anime_id
-          WHERE v.parsed_title IS NOT NULL
+          WHERE a.media_kind = 'anime'
+            AND v.parsed_title IS NOT NULL
             AND TRIM(v.parsed_title) != ''
             AND v.parsed_season IS NOT NULL
             AND v.parsed_season > 0
@@ -372,6 +373,23 @@ export function resolveAnimeAnilistConflict(
   anilistId: number,
   options: AnimeAnilistConflictOptions = {},
 ): AnimeSeasonRepairSummary {
+  return runInTransaction(db, () =>
+    resolveAnimeAnilistConflictInTransaction(db, targetAnimeId, anilistId, options),
+  );
+}
+
+/** Caller owns the write transaction. */
+export function resolveAnimeAnilistConflictInTransaction(
+  db: DatabaseSync,
+  targetAnimeId: number,
+  anilistId: number,
+  options: AnimeAnilistConflictOptions = {},
+): AnimeSeasonRepairSummary {
+  if (!getAnimeRow(db, targetAnimeId)) {
+    const summary = emptySummary();
+    summary.anilistAssignmentBlocked = true;
+    return summary;
+  }
   const conflict = db
     .prepare(
       `
@@ -386,85 +404,88 @@ export function resolveAnimeAnilistConflict(
   if (!conflict) {
     return emptySummary();
   }
+  if (!getAnimeRow(db, conflict.animeId)) {
+    const summary = emptySummary();
+    summary.anilistAssignmentBlocked = true;
+    return summary;
+  }
 
-  return runInTransaction(db, () => {
-    const targetRow = getAnimeRow(db, targetAnimeId);
-    if (
-      options.survivor !== 'target' &&
-      targetRow?.anilist_id != null &&
-      targetRow.anilist_id !== anilistId
-    ) {
-      // An automatic lookup disagreeing with an existing explicit link is a
-      // mis-resolution, not evidence that either row should move or merge. The
-      // colliding id must not be assigned either: another row owns it and
-      // imm_anime.anilist_id is UNIQUE.
-      const summary = emptySummary(1);
-      summary.anilistAssignmentBlocked = true;
-      return summary;
-    }
-    const isManual = options.survivor === 'target' || options.matchConfidence === 'manual';
-    if (!isManual && hasDismissedAnimeMergeRecommendation(db, targetAnimeId, conflict.animeId)) {
-      const summary = emptySummary(1);
-      summary.anilistAssignmentBlocked = true;
-      return summary;
-    }
-    const targetSeasons = getParsedSeasonsForAnime(db, targetAnimeId);
-    const conflictSeasons = getParsedSeasonsForAnime(db, conflict.animeId);
-    if (
-      !isManual &&
-      targetSeasons.size === 1 &&
-      conflictSeasons.size === 1 &&
-      [...targetSeasons][0] !== [...conflictSeasons][0]
-    ) {
-      const summary = emptySummary(1);
-      summary.anilistAssignmentBlocked = true;
-      return summary;
-    }
-    if (canMergeAnilistConflict(db, targetAnimeId, conflict.animeId, anilistId, options)) {
-      const survivingAnimeId = options.survivor === 'target' ? targetAnimeId : conflict.animeId;
-      const absorbedAnimeId = survivingAnimeId === targetAnimeId ? conflict.animeId : targetAnimeId;
-      const merge = mergeAnimeRecordsInTransaction(db, survivingAnimeId, [absorbedAnimeId]);
-      const summary = emptySummary(1);
-      summary.movedVideos = merge.movedVideos;
-      summary.deletedAnimeRows = merge.mergedAnimeIds.length;
-      if (merge.mergedAnimeIds.length > 0) {
-        summary.repaired = 1;
-        // Only reported once a row really absorbed the other, so callers never
-        // follow this to an anime id that was never written.
-        summary.survivingAnimeId = survivingAnimeId;
-        summary.affectedAnimeIds.push(survivingAnimeId, absorbedAnimeId);
-      }
-      // Lifetime summaries are rebuilt by the caller off this summary, the same
-      // as the redistribution path below.
-      return summary;
+  const targetRow = getAnimeRow(db, targetAnimeId);
+  if (
+    options.survivor !== 'target' &&
+    targetRow?.anilist_id != null &&
+    targetRow.anilist_id !== anilistId
+  ) {
+    // An automatic lookup disagreeing with an existing explicit link is a
+    // mis-resolution, not evidence that either row should move or merge. The
+    // colliding id must not be assigned either: another row owns it and
+    // imm_anime.anilist_id is UNIQUE.
+    const summary = emptySummary(1);
+    summary.anilistAssignmentBlocked = true;
+    return summary;
+  }
+  const isManual = options.survivor === 'target' || options.matchConfidence === 'manual';
+  if (!isManual && hasDismissedAnimeMergeRecommendation(db, targetAnimeId, conflict.animeId)) {
+    const summary = emptySummary(1);
+    summary.anilistAssignmentBlocked = true;
+    return summary;
+  }
+  const targetSeasons = getParsedSeasonsForAnime(db, targetAnimeId);
+  const conflictSeasons = getParsedSeasonsForAnime(db, conflict.animeId);
+  if (
+    !isManual &&
+    targetSeasons.size === 1 &&
+    conflictSeasons.size === 1 &&
+    [...targetSeasons][0] !== [...conflictSeasons][0]
+  ) {
+    const summary = emptySummary(1);
+    summary.anilistAssignmentBlocked = true;
+    return summary;
+  }
+  if (canMergeAnilistConflict(db, targetAnimeId, conflict.animeId, anilistId, options)) {
+    const survivingAnimeId = options.survivor === 'target' ? targetAnimeId : conflict.animeId;
+    const absorbedAnimeId = survivingAnimeId === targetAnimeId ? conflict.animeId : targetAnimeId;
+    const merge = mergeAnimeRecordsInTransaction(db, survivingAnimeId, [absorbedAnimeId]);
+    const summary = emptySummary(1);
+    summary.movedVideos = merge.movedVideos;
+    summary.deletedAnimeRows = merge.mergedAnimeIds.length;
+    if (merge.mergedAnimeIds.length > 0) {
+      summary.repaired = 1;
+      // Only reported once a row really absorbed the other, so callers never
+      // follow this to an anime id that was never written.
+      summary.survivingAnimeId = survivingAnimeId;
+      summary.affectedAnimeIds.push(survivingAnimeId, absorbedAnimeId);
     }
+    // Lifetime summaries are rebuilt by the caller off this summary, the same
+    // as the redistribution path below.
+    return summary;
+  }
 
-    if (shouldRecommendAnilistConflict(db, targetAnimeId, conflict.animeId, options)) {
-      recordAnimeMergeRecommendation(db, targetAnimeId, conflict.animeId, anilistId);
-      const summary = emptySummary(1);
-      summary.mergeRecommended = true;
-      return summary;
-    }
+  if (shouldRecommendAnilistConflict(db, targetAnimeId, conflict.animeId, options)) {
+    recordAnimeMergeRecommendation(db, targetAnimeId, conflict.animeId, anilistId);
+    const summary = emptySummary(1);
+    summary.mergeRecommended = true;
+    return summary;
+  }
 
-    const isExactAutomaticMatch =
-      options.matchConfidence === 'exact' ||
-      (options.matchConfidence === undefined &&
-        hasExactStoredTitleMatch(db, targetAnimeId, conflict.animeId));
-    if (!isManual && !isExactAutomaticMatch) {
-      // Redistribution dismantles the id's current owner and hands the id to
-      // the target. On a weak automatic match that owner is usually the
-      // correctly linked card (e.g. a legitimate multi-season entry), so
-      // splitting it here is exactly the fuzzy false merge this gate exists to
-      // stop. Only exact or manual evidence may fall through.
-      const summary = emptySummary(1);
-      summary.anilistAssignmentBlocked = true;
-      return summary;
-    }
+  const isExactAutomaticMatch =
+    options.matchConfidence === 'exact' ||
+    (options.matchConfidence === undefined &&
+      hasExactStoredTitleMatch(db, targetAnimeId, conflict.animeId));
+  if (!isManual && !isExactAutomaticMatch) {
+    // Redistribution dismantles the id's current owner and hands the id to
+    // the target. On a weak automatic match that owner is usually the
+    // correctly linked card (e.g. a legitimate multi-season entry), so
+    // splitting it here is exactly the fuzzy false merge this gate exists to
+    // stop. Only exact or manual evidence may fall through.
+    const summary = emptySummary(1);
+    summary.anilistAssignmentBlocked = true;
+    return summary;
+  }
 
-    return redistributeAnimeRowByParsedSeasonsInTransaction(db, conflict.animeId, {
-      transferAnilistToAnimeId: targetAnimeId,
-      overwriteTargetAnilist: true,
-    });
+  return redistributeAnimeRowByParsedSeasonsInTransaction(db, conflict.animeId, {
+    transferAnilistToAnimeId: targetAnimeId,
+    overwriteTargetAnilist: true,
   });
 }
 
diff --git a/src/core/services/immersion-tracker/jellyfin-link-repair.ts b/src/core/services/immersion-tracker/jellyfin-link-repair.ts
index 0eeed92a..95d341c4 100644
--- a/src/core/services/immersion-tracker/jellyfin-link-repair.ts
+++ b/src/core/services/immersion-tracker/jellyfin-link-repair.ts
@@ -82,7 +82,7 @@ function parseLegacyJellyfinStreamUrl(value: string | null): URL | null {
     ) {
       return null;
     }
-    if (!url.searchParams.has('api_key')) {
+    if (!url.searchParams.has('api_key') && !url.searchParams.has('ApiKey')) {
       return null;
     }
     return url;
@@ -130,13 +130,13 @@ function repairLeakedJellyfinAnimeTitles(db: DatabaseSync, currentTimestamp: str
               SELECT v.canonical_title
               FROM imm_videos v
               WHERE v.anime_id = a.anime_id
-                AND v.canonical_title NOT LIKE '%api_key=%'
+                AND v.canonical_title NOT LIKE '%api_key=%' AND v.canonical_title NOT LIKE '%ApiKey=%'
                 AND lower(v.canonical_title) NOT LIKE '%api key%'
               ORDER BY v.LAST_UPDATE_DATE DESC, v.video_id DESC
               LIMIT 1
             ) AS linked_video_title
           FROM imm_anime a
-          WHERE a.canonical_title LIKE '%api_key=%'
+          WHERE a.canonical_title LIKE '%api_key=%' OR a.canonical_title LIKE '%ApiKey=%'
              OR lower(a.canonical_title) LIKE '%api key%'
              OR lower(a.normalized_title_key) LIKE '%api key%'
         `,
@@ -244,11 +244,11 @@ function repairLeakedJellyfinVideoParseMetadata(
           LAST_UPDATE_DATE = ?
         WHERE source_type = 2
           AND (
-            parsed_basename LIKE '%api_key=%'
+            parsed_basename LIKE '%api_key=%' OR parsed_basename LIKE '%ApiKey=%'
             OR lower(parsed_basename) LIKE '%api key%'
-            OR parsed_title LIKE '%api_key=%'
+            OR parsed_title LIKE '%api_key=%' OR parsed_title LIKE '%ApiKey=%'
             OR lower(parsed_title) LIKE '%api key%'
-            OR parse_metadata_json LIKE '%api_key=%'
+            OR parse_metadata_json LIKE '%api_key=%' OR parse_metadata_json LIKE '%ApiKey=%'
             OR lower(parse_metadata_json) LIKE '%api key%'
           )
       `,
@@ -257,6 +257,30 @@ function repairLeakedJellyfinVideoParseMetadata(
   return updated.changes;
 }
 
+function repairLeakedJellyfinAnimeParseMetadata(
+  db: DatabaseSync,
+  currentTimestamp: string,
+): number {
+  const updated = db
+    .prepare(
+      `
+    UPDATE imm_anime
+    SET metadata_json = NULL, LAST_UPDATE_DATE = ?
+    WHERE (
+      metadata_json LIKE '%api_key=%' OR metadata_json LIKE '%ApiKey=%'
+      OR lower(metadata_json) LIKE '%api key%'
+    ) AND (
+      lower(metadata_json) LIKE '%stream?%'
+      OR lower(metadata_json) LIKE '%/stream?%'
+      OR lower(metadata_json) LIKE '%/videos/%'
+      OR lower(metadata_json) LIKE '%mediasourceid%'
+    )
+  `,
+    )
+    .run(currentTimestamp);
+  return updated.changes;
+}
+
 export function repairJellyfinStreamVideoLinks(db: DatabaseSync): JellyfinLinkRepairSummary {
   const candidates = db
     .prepare(
@@ -271,11 +295,11 @@ export function repairJellyfinStreamVideoLinks(db: DatabaseSync): JellyfinLinkRe
         FROM imm_videos
         WHERE source_type = 2
           AND (
-            video_key LIKE '%api_key=%'
+            video_key LIKE '%api_key=%' OR video_key LIKE '%ApiKey=%'
             OR lower(video_key) LIKE '%api key%'
-            OR source_url LIKE '%api_key=%'
+            OR source_url LIKE '%api_key=%' OR source_url LIKE '%ApiKey=%'
             OR lower(source_url) LIKE '%api key%'
-            OR canonical_title LIKE '%api_key=%'
+            OR canonical_title LIKE '%api_key=%' OR canonical_title LIKE '%ApiKey=%'
             OR lower(canonical_title) LIKE '%api key%'
           )
       `,
@@ -290,7 +314,8 @@ export function repairJellyfinStreamVideoLinks(db: DatabaseSync): JellyfinLinkRe
     const currentTimestamp = toDbTimestamp(nowMs());
     const repaired =
       repairLeakedJellyfinAnimeTitles(db, currentTimestamp) +
-      repairLeakedJellyfinVideoParseMetadata(db, currentTimestamp);
+      repairLeakedJellyfinVideoParseMetadata(db, currentTimestamp) +
+      repairLeakedJellyfinAnimeParseMetadata(db, currentTimestamp);
     summary.repaired += repaired;
     return summary;
   }
@@ -422,6 +447,7 @@ export function repairJellyfinStreamVideoLinks(db: DatabaseSync): JellyfinLinkRe
     }
     summary.repaired += repairLeakedJellyfinAnimeTitles(db, currentTimestamp);
     summary.repaired += repairLeakedJellyfinVideoParseMetadata(db, currentTimestamp);
+    summary.repaired += repairLeakedJellyfinAnimeParseMetadata(db, currentTimestamp);
     db.exec('COMMIT');
   } catch (error) {
     db.exec('ROLLBACK');
diff --git a/src/core/services/immersion-tracker/lexical-rollups.test.ts b/src/core/services/immersion-tracker/lexical-rollups.test.ts
index 8fae14c8..60ce4daf 100644
--- a/src/core/services/immersion-tracker/lexical-rollups.test.ts
+++ b/src/core/services/immersion-tracker/lexical-rollups.test.ts
@@ -306,9 +306,11 @@ test('vocabulary charts use complete top-word and lexical rollup data', () => {
       `INSERT INTO imm_words(headword, word, reading, first_seen, last_seen, frequency)
        VALUES (?, ?, '', 1700000000, 1700000000, ?)`,
     );
+    db.exec('BEGIN');
     for (let index = 0; index < 501; index += 1) {
       insertWord.run(`語${index}`, `語${index}`, index === 500 ? 10_000 : 1);
     }
+    db.exec('COMMIT');
 
     const charts = getVocabularyChartData(db);
 
diff --git a/src/core/services/immersion-tracker/live-action-link.ts b/src/core/services/immersion-tracker/live-action-link.ts
new file mode 100644
index 00000000..78bfb7f7
--- /dev/null
+++ b/src/core/services/immersion-tracker/live-action-link.ts
@@ -0,0 +1,179 @@
+import type { DatabaseSync } from './sqlite';
+import type { TmdbMediaType } from '../../../shared/media-kind';
+import { mergeAnimeRecordsInTransaction } from './anime-merge';
+import { recomputeLifetimeAnimeAggregatesInTransaction } from './lifetime';
+import { toDbTimestamp } from './query-shared';
+import { nowMs } from './time';
+
+export interface LiveActionTitleInput {
+  tmdbId: number;
+  tmdbType: TmdbMediaType;
+  titleEnglish: string | null;
+  titleNative: string | null;
+  description: string | null;
+  episodesTotal: number | null;
+}
+
+export interface LiveActionLinkResult {
+  /** Library entry that carries the TMDB link once the call finishes. */
+  animeId: number;
+  /** Entries folded into `animeId` because they pointed at the same TMDB title. */
+  mergedAnimeIds: number[];
+}
+
+export interface LiveActionLinkOptions {
+  /**
+   * `manual`: the user picked this title, so stored titles are overwritten and
+   * every other holder of the TMDB id is folded into this entry.
+   * `auto`: an exact filename match, so gaps are filled and the entry joins an
+   * existing holder rather than displacing it.
+   */
+  mode: 'manual' | 'auto';
+}
+
+export interface VideoTmdbLink {
+  animeId: number;
+  tmdbId: number;
+  tmdbType: TmdbMediaType;
+}
+
+function findOtherTmdbHolders(
+  db: DatabaseSync,
+  animeId: number,
+  input: Pick<LiveActionTitleInput, 'tmdbId' | 'tmdbType'>,
+): number[] {
+  return (
+    db
+      .prepare(
+        `SELECT anime_id AS animeId
+         FROM imm_anime
+         WHERE tmdb_id = ? AND tmdb_type = ? AND anime_id != ?
+         ORDER BY anime_id ASC`,
+      )
+      .all(input.tmdbId, input.tmdbType, animeId) as Array<{ animeId: number }>
+  ).map((row) => row.animeId);
+}
+
+/**
+ * Link a library entry to a TMDB title. Unlike AniList, a TMDB show spans all
+ * of its seasons, so entries that resolve to the same title are one show and
+ * are merged regardless of the season each was parsed with.
+ */
+export function linkAnimeToTmdbTitle(
+  db: DatabaseSync,
+  animeId: number,
+  input: LiveActionTitleInput,
+  options: LiveActionLinkOptions,
+): LiveActionLinkResult {
+  db.exec('BEGIN IMMEDIATE');
+  try {
+    const result = linkAnimeToTmdbTitleInTransaction(db, animeId, input, options);
+    db.exec('COMMIT');
+    return result;
+  } catch (error) {
+    db.exec('ROLLBACK');
+    throw error;
+  }
+}
+
+/** Caller owns the write transaction, including any artwork replacement. */
+export function linkAnimeToTmdbTitleInTransaction(
+  db: DatabaseSync,
+  animeId: number,
+  input: LiveActionTitleInput,
+  options: LiveActionLinkOptions,
+): LiveActionLinkResult {
+  const target = db.prepare('SELECT anilist_id FROM imm_anime WHERE anime_id = ?').get(animeId) as
+    | { anilist_id: number | null }
+    | undefined;
+  if (!target) throw new Error('Unknown library entry');
+  if (target.anilist_id !== null) {
+    if (options.mode === 'auto')
+      throw new Error('Cannot automatically replace an AniList identity');
+    // An explicit reassignment changes providers before compatible rows merge.
+    db.prepare('UPDATE imm_anime SET anilist_id = NULL WHERE anime_id = ?').run(animeId);
+  }
+  const others = findOtherTmdbHolders(db, animeId, input);
+  let survivor = animeId;
+  let mergedAnimeIds: number[] = [];
+  if (others.length > 0) {
+    if (options.mode === 'manual') {
+      mergedAnimeIds = mergeAnimeRecordsInTransaction(db, animeId, others).mergedAnimeIds;
+    } else {
+      // Keep the entry the user already sees; the newcomer is the transient
+      // "Show Season 3" row that a fresh season folder just created.
+      survivor = others[0]!;
+      mergedAnimeIds = mergeAnimeRecordsInTransaction(db, survivor, [
+        animeId,
+        ...others.slice(1),
+      ]).mergedAnimeIds;
+    }
+  }
+
+  const updatedAt = toDbTimestamp(nowMs());
+  if (options.mode === 'manual') {
+    db.prepare(
+      `UPDATE imm_anime
+       SET media_kind = 'live_action',
+           tmdb_id = ?,
+           tmdb_type = ?,
+           anilist_id = NULL,
+           title_romaji = NULL,
+           title_english = ?,
+           title_native = ?,
+           episodes_total = ?,
+           description = ?,
+           LAST_UPDATE_DATE = ?
+       WHERE anime_id = ?`,
+    ).run(
+      input.tmdbId,
+      input.tmdbType,
+      input.titleEnglish,
+      input.titleNative,
+      input.episodesTotal,
+      input.description,
+      updatedAt,
+      survivor,
+    );
+  } else {
+    db.prepare(
+      `UPDATE imm_anime
+       SET media_kind = 'live_action',
+           tmdb_id = ?,
+           tmdb_type = ?,
+           title_english = COALESCE(title_english, ?),
+           title_native = COALESCE(title_native, ?),
+           episodes_total = COALESCE(episodes_total, ?),
+           description = COALESCE(description, ?),
+           LAST_UPDATE_DATE = ?
+       WHERE anime_id = ?`,
+    ).run(
+      input.tmdbId,
+      input.tmdbType,
+      input.titleEnglish,
+      input.titleNative,
+      input.episodesTotal,
+      input.description,
+      updatedAt,
+      survivor,
+    );
+  }
+  recomputeLifetimeAnimeAggregatesInTransaction(db);
+  return { animeId: survivor, mergedAnimeIds };
+}
+
+/** The TMDB link of the live-action entry a video belongs to, if any. */
+export function getVideoTmdbLink(db: DatabaseSync, videoId: number): VideoTmdbLink | null {
+  const row = db
+    .prepare(
+      `SELECT a.anime_id AS animeId, a.tmdb_id AS tmdbId, a.tmdb_type AS tmdbType
+       FROM imm_videos v
+       JOIN imm_anime a ON a.anime_id = v.anime_id
+       WHERE v.video_id = ?
+         AND a.media_kind = 'live_action'
+         AND a.tmdb_id IS NOT NULL
+         AND a.tmdb_type IN ('tv', 'movie')`,
+    )
+    .get(videoId) as VideoTmdbLink | undefined;
+  return row ? { animeId: row.animeId, tmdbId: row.tmdbId, tmdbType: row.tmdbType } : null;
+}
diff --git a/src/core/services/immersion-tracker/metadata.test.ts b/src/core/services/immersion-tracker/metadata.test.ts
index c2707532..da3c7c50 100644
--- a/src/core/services/immersion-tracker/metadata.test.ts
+++ b/src/core/services/immersion-tracker/metadata.test.ts
@@ -147,6 +147,25 @@ test('getLocalVideoMetadata derives title and falls back to null hash on read er
   assert.equal(hashFallbackMetadata.hashSha256, null);
 });
 
+test('stream stats parsing preserves display titles and never persists transport credentials', async () => {
+  const targets: string[] = [];
+  const parsed = await guessAnimeVideoMetadata(
+    'https://jellyfin.example/Videos/item/stream?api_key=test-secret',
+    'Fate/stay night S01E02',
+    {
+      runGuessit: async (target) => {
+        targets.push(target);
+        return JSON.stringify({ title: 'Fate/stay night', season: 1, episode: 2 });
+      },
+    },
+  );
+  assert.deepEqual(targets, ['Fate/stay night S01E02']);
+  assert.equal(parsed?.parsedBasename, 'Fate/stay night S01E02');
+  assert.equal(parsed?.parsedTitle, 'Fate/stay night');
+  assert.equal(JSON.stringify(parsed).includes('test-secret'), false);
+  assert.equal(JSON.stringify(parsed).includes('/stream'), false);
+});
+
 test('guessAnimeVideoMetadata uses guessit basename output first when available', async () => {
   const seenTargets: string[] = [];
   const parsed = await guessAnimeVideoMetadata(
diff --git a/src/core/services/immersion-tracker/metadata.ts b/src/core/services/immersion-tracker/metadata.ts
index 3b09ce07..02868f36 100644
--- a/src/core/services/immersion-tracker/metadata.ts
+++ b/src/core/services/immersion-tracker/metadata.ts
@@ -3,6 +3,7 @@ import { spawn as nodeSpawn } from 'node:child_process';
 import * as fs from 'node:fs';
 import path from 'node:path';
 import { parseMediaInfo } from '../../../jimaku/utils';
+import { resolveMediaLookupTarget, sanitizeMediaTitle } from '../../../shared/media-identity';
 import {
   guessAnilistMediaInfo,
   runGuessit,
@@ -184,6 +185,7 @@ export async function guessAnimeVideoMetadata(
   mediaTitle: string | null,
   deps: GuessAnimeVideoMetadataDeps = {},
 ): Promise<ParsedAnimeVideoGuess | null> {
+  const lookupTarget = resolveMediaLookupTarget(mediaPath, mediaTitle);
   const parsed = await guessAnilistMediaInfo(mediaPath, mediaTitle, {
     runGuessit: deps.runGuessit ?? runGuessit,
   });
@@ -191,7 +193,12 @@ export async function guessAnimeVideoMetadata(
     return null;
   }
 
-  const parsedBasename = mediaPath ? path.basename(mediaPath) : null;
+  const parsedBasename =
+    lookupTarget === sanitizeMediaTitle(mediaTitle)
+      ? lookupTarget
+      : lookupTarget
+        ? path.basename(lookupTarget)
+        : null;
   if (parsed.source === 'guessit') {
     return {
       parsedBasename,
@@ -207,7 +214,7 @@ export async function guessAnimeVideoMetadata(
     };
   }
 
-  const fallbackInfo = parseMediaInfo(mediaPath ?? mediaTitle);
+  const fallbackInfo = parseMediaInfo(lookupTarget);
   return {
     parsedBasename: parsedBasename ?? fallbackInfo.filename ?? null,
     parsedTitle: parsed.title,
diff --git a/src/core/services/immersion-tracker/query-library.ts b/src/core/services/immersion-tracker/query-library.ts
index 69240462..bfa4a672 100644
--- a/src/core/services/immersion-tracker/query-library.ts
+++ b/src/core/services/immersion-tracker/query-library.ts
@@ -33,7 +33,11 @@ export function getAnimeLibrary(db: DatabaseSync): AnimeLibraryRow[] {
     SELECT
       a.anime_id AS animeId,
       a.canonical_title AS canonicalTitle,
+      a.media_kind AS mediaKind,
       a.anilist_id AS anilistId,
+      a.media_kind AS mediaKind,
+      a.tmdb_id AS tmdbId,
+      a.tmdb_type AS tmdbType,
       COALESCE(lm.total_sessions, 0) AS totalSessions,
       COALESCE(lm.total_active_ms, 0) AS totalActiveMs,
       COALESCE(lm.total_cards, 0) AS totalCards,
@@ -63,7 +67,11 @@ export function getAnimeDetail(db: DatabaseSync, animeId: number): AnimeDetailRo
     SELECT
       a.anime_id AS animeId,
       a.canonical_title AS canonicalTitle,
+      a.media_kind AS mediaKind,
       a.anilist_id AS anilistId,
+      a.media_kind AS mediaKind,
+      a.tmdb_id AS tmdbId,
+      a.tmdb_type AS tmdbType,
       a.title_romaji AS titleRomaji,
       a.title_english AS titleEnglish,
       a.title_native AS titleNative,
diff --git a/src/core/services/immersion-tracker/query-maintenance.ts b/src/core/services/immersion-tracker/query-maintenance.ts
index 09cf92e9..b91e9615 100644
--- a/src/core/services/immersion-tracker/query-maintenance.ts
+++ b/src/core/services/immersion-tracker/query-maintenance.ts
@@ -331,6 +331,29 @@ export async function cleanupVocabularyStats(
   };
 }
 
+/**
+ * Drop the cached art of every episode in a library entry. Used when a manual
+ * relink points at a title with no artwork, so the previous link's cover does
+ * not keep standing in for it.
+ */
+export function clearAnimeCoverArt(db: DatabaseSync, animeId: number): void {
+  const rows = db
+    .prepare(
+      `SELECT m.cover_blob_hash AS coverBlobHash
+       FROM imm_media_art m
+       JOIN imm_videos v ON v.video_id = m.video_id
+       WHERE v.anime_id = ?`,
+    )
+    .all(animeId) as Array<{ coverBlobHash: string | null }>;
+  if (rows.length === 0) return;
+  db.prepare(
+    'DELETE FROM imm_media_art WHERE video_id IN (SELECT video_id FROM imm_videos WHERE anime_id = ?)',
+  ).run(animeId);
+  for (const hash of new Set(rows.map((row) => row.coverBlobHash))) {
+    cleanupUnusedCoverArtBlobHash(db, hash);
+  }
+}
+
 export function upsertCoverArt(
   db: DatabaseSync,
   videoId: number,
diff --git a/src/core/services/immersion-tracker/storage-session.test.ts b/src/core/services/immersion-tracker/storage-session.test.ts
index 07a21995..ff36deb8 100644
--- a/src/core/services/immersion-tracker/storage-session.test.ts
+++ b/src/core/services/immersion-tracker/storage-session.test.ts
@@ -3,7 +3,7 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import test from 'node:test';
-import { Database } from './sqlite';
+import { Database, type DatabaseSync } from './sqlite';
 import { getStatsExcludedWords, replaceStatsExcludedWords } from './query-lexical';
 import { finalizeSessionRecord, startSessionRecord } from './session';
 import {
@@ -87,6 +87,29 @@ test('applyPragmas sets the SQLite tuning defaults used by immersion tracking',
   }
 });
 
+test('applyPragmas installs the busy timeout before WAL negotiation', () => {
+  const statements: string[] = [];
+  const db: DatabaseSync = {
+    exec(source) {
+      statements.push(source);
+      return db;
+    },
+    prepare() {
+      throw new Error('not used');
+    },
+    close() {
+      return db;
+    },
+  };
+
+  applyPragmas(db);
+
+  assert.deepEqual(statements.slice(0, 2), [
+    'PRAGMA busy_timeout = 2500',
+    'PRAGMA journal_mode = WAL',
+  ]);
+});
+
 test('ensureSchema creates immersion core tables', () => {
   const dbPath = makeDbPath();
   const db = new Database(dbPath);
diff --git a/src/core/services/immersion-tracker/storage.ts b/src/core/services/immersion-tracker/storage.ts
index 74286dff..533ec88d 100644
--- a/src/core/services/immersion-tracker/storage.ts
+++ b/src/core/services/immersion-tracker/storage.ts
@@ -1,3 +1,4 @@
+import { sameTitleNamespaceSql, type MediaKind } from '../../../shared/media-kind';
 import { createHash } from 'node:crypto';
 import path from 'node:path';
 import { parseMediaInfo } from '../../../jimaku/utils';
@@ -24,6 +25,7 @@ export interface TrackerPreparedStatements {
 }
 
 export interface AnimeRecordInput {
+  mediaKind?: MediaKind;
   parsedTitle: string;
   canonicalTitle: string;
   seasonScope?: number | null;
@@ -315,10 +317,12 @@ function migrateSessionEventTimestampsToText(db: DatabaseSync): void {
 }
 
 export function applyPragmas(db: DatabaseSync): void {
+  // Install the wait policy before WAL negotiation, which can briefly contend with
+  // another connection closing or checkpointing the same database.
+  db.exec('PRAGMA busy_timeout = 2500');
   db.exec('PRAGMA journal_mode = WAL');
   db.exec('PRAGMA synchronous = NORMAL');
   db.exec('PRAGMA foreign_keys = ON');
-  db.exec('PRAGMA busy_timeout = 2500');
   db.exec(`PRAGMA journal_size_limit = ${WAL_JOURNAL_SIZE_LIMIT_BYTES}`);
 }
 
@@ -567,6 +571,8 @@ function ensureSubtitleLineEventIndex(db: DatabaseSync): void {
 }
 
 export function getOrCreateAnimeRecord(db: DatabaseSync, input: AnimeRecordInput): number {
+  const mediaKind = input.mediaKind ?? 'anime';
+  const anilistId = mediaKind === 'anime' ? input.anilistId : null;
   const seasonScope = normalizeSeasonScope(input.seasonScope);
   const identityTitle = buildSeasonScopedAnimeTitle(input.parsedTitle, seasonScope);
   const canonicalTitle =
@@ -578,17 +584,28 @@ export function getOrCreateAnimeRecord(db: DatabaseSync, input: AnimeRecordInput
   }
 
   const byAnilistId =
-    input.anilistId !== null
-      ? (db.prepare('SELECT anime_id FROM imm_anime WHERE anilist_id = ?').get(input.anilistId) as {
+    anilistId !== null
+      ? (db
+          .prepare("SELECT anime_id FROM imm_anime WHERE anilist_id = ? AND media_kind = 'anime'")
+          .get(anilistId) as {
           anime_id: number;
         } | null)
       : null;
+  // Title lookups stay inside the kind's namespace: a parsed filename may land
+  // on a TMDB-linked live-action row, but never on a YouTube channel.
   const byNormalizedTitle = db
-    .prepare('SELECT anime_id FROM imm_anime WHERE normalized_title_key = ?')
-    .get(normalizedTitleKey) as { anime_id: number } | null;
+    .prepare(
+      `SELECT anime_id FROM imm_anime
+      WHERE normalized_title_key = ? AND ${sameTitleNamespaceSql()}`,
+    )
+    .get(normalizedTitleKey, mediaKind) as { anime_id: number } | null;
   const byTitleAlias = db
-    .prepare('SELECT anime_id FROM imm_anime_title_aliases WHERE normalized_title_key = ?')
-    .get(normalizedTitleKey) as { anime_id: number } | null;
+    .prepare(
+      `SELECT a.anime_id FROM imm_anime_title_aliases AS alias
+      JOIN imm_anime AS a ON a.anime_id = alias.anime_id
+      WHERE alias.normalized_title_key = ? AND ${sameTitleNamespaceSql('a.media_kind')}`,
+    )
+    .get(normalizedTitleKey, mediaKind) as { anime_id: number } | null;
   const existing = byAnilistId ?? byNormalizedTitle ?? byTitleAlias;
   if (existing?.anime_id) {
     // An alias remembers an intentionally merged-away spelling. Reusing it
@@ -599,7 +616,11 @@ export function getOrCreateAnimeRecord(db: DatabaseSync, input: AnimeRecordInput
         UPDATE imm_anime
         SET
           canonical_title = COALESCE(NULLIF(?, ''), canonical_title),
-          anilist_id = COALESCE(?, anilist_id),
+          anilist_id = CASE
+            WHEN ? = 'youtube' THEN NULL
+            WHEN tmdb_id IS NOT NULL THEN anilist_id
+            ELSE COALESCE(?, anilist_id)
+          END,
           title_romaji = COALESCE(?, title_romaji),
           title_english = COALESCE(?, title_english),
           title_native = COALESCE(?, title_native),
@@ -609,7 +630,8 @@ export function getOrCreateAnimeRecord(db: DatabaseSync, input: AnimeRecordInput
       `,
     ).run(
       canonicalTitleUpdate,
-      input.anilistId,
+      mediaKind,
+      anilistId,
       input.titleRomaji,
       input.titleEnglish,
       input.titleNative,
@@ -625,6 +647,7 @@ export function getOrCreateAnimeRecord(db: DatabaseSync, input: AnimeRecordInput
     .prepare(
       `
         INSERT INTO imm_anime(
+          media_kind,
           normalized_title_key,
           canonical_title,
           anilist_id,
@@ -634,13 +657,14 @@ export function getOrCreateAnimeRecord(db: DatabaseSync, input: AnimeRecordInput
           metadata_json,
           CREATED_DATE,
           LAST_UPDATE_DATE
-        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
       `,
     )
     .run(
+      input.mediaKind ?? 'anime',
       normalizedTitleKey,
       canonicalTitle,
-      input.anilistId,
+      anilistId,
       input.titleRomaji,
       input.titleEnglish,
       input.titleNative,
@@ -801,6 +825,7 @@ export function linkYoutubeVideoToAnimeRecord(
   }
 
   const animeId = getOrCreateAnimeRecord(db, {
+    mediaKind: 'youtube',
     parsedTitle: identity.parsedTitle,
     canonicalTitle: identity.canonicalTitle,
     anilistId: null,
@@ -873,6 +898,77 @@ function migrateLegacyAnimeMetadata(db: DatabaseSync): void {
   }
 }
 
+// SQLite cannot drop a table-level UNIQUE constraint or a column CHECK.
+// Rebuild with IDs intact and foreign keys disabled so dependent history and
+// manual assignments survive. Two shapes need it: the original
+// `normalized_title_key UNIQUE`, and the v0.19.6 `media_kind` column whose
+// CHECK only allowed 'anime' and 'youtube'.
+const LEGACY_TITLE_UNIQUE_RE = /normalized_title_key TEXT NOT NULL UNIQUE/i;
+const LEGACY_MEDIA_KIND_CHECK_RE = /\s*CHECK\s*\(\s*media_kind IN \('anime',\s*'youtube'\)\s*\)/i;
+
+function migrateAnimeTableConstraints(db: DatabaseSync): void {
+  const schema = db.prepare("SELECT sql FROM sqlite_master WHERE name = 'imm_anime'").get() as {
+    sql: string;
+  };
+  if (LEGACY_TITLE_UNIQUE_RE.test(schema.sql) || LEGACY_MEDIA_KIND_CHECK_RE.test(schema.sql)) {
+    const foreignKeys = db.prepare('PRAGMA foreign_keys').get() as { foreign_keys: number };
+    const sequence = db
+      .prepare("SELECT seq FROM sqlite_sequence WHERE name = 'imm_anime'")
+      .get() as { seq: number } | null;
+    db.exec('PRAGMA foreign_keys = OFF');
+    try {
+      db.exec('BEGIN IMMEDIATE');
+      db.exec(
+        schema.sql
+          .replace(
+            /CREATE TABLE (?:IF NOT EXISTS )?["`]?imm_anime["`]?/i,
+            'CREATE TABLE imm_anime_new',
+          )
+          .replace(LEGACY_TITLE_UNIQUE_RE, 'normalized_title_key TEXT NOT NULL')
+          .replace(LEGACY_MEDIA_KIND_CHECK_RE, ''),
+      );
+      db.exec(`INSERT INTO imm_anime_new SELECT * FROM imm_anime;
+        DROP TABLE imm_anime;
+        ALTER TABLE imm_anime_new RENAME TO imm_anime;`);
+      if (sequence) {
+        db.prepare("UPDATE sqlite_sequence SET seq = MAX(seq, ?) WHERE name = 'imm_anime'").run(
+          sequence.seq,
+        );
+      }
+      db.exec('COMMIT');
+    } catch (error) {
+      db.exec('ROLLBACK');
+      throw error;
+    } finally {
+      db.exec(`PRAGMA foreign_keys = ${foreignKeys.foreign_keys}`);
+    }
+  }
+  // v0.19.6 scoped titles per kind; anime and live-action now share one
+  // namespace (an entry moves between them when relinked), YouTube is separate.
+  db.exec(`DROP INDEX IF EXISTS idx_anime_kind_title;
+    CREATE UNIQUE INDEX IF NOT EXISTS idx_anime_namespace_title
+    ON imm_anime((media_kind = 'youtube'), normalized_title_key)`);
+}
+
+// Older builds can create channel rows with the default anime kind even after
+// the schema upgrade. Repair classification on every startup without moving videos.
+function classifyYoutubeChannels(db: DatabaseSync): void {
+  db.exec(`
+    UPDATE imm_anime
+    SET media_kind = 'youtube', anilist_id = NULL
+    WHERE media_kind = 'anime'
+      AND NOT EXISTS (SELECT 1 FROM imm_anime AS channel
+        WHERE channel.media_kind = 'youtube'
+          AND channel.normalized_title_key = imm_anime.normalized_title_key)
+      AND (
+        normalized_title_key LIKE 'youtube channel %'
+        OR CASE WHEN json_valid(metadata_json)
+           THEN json_extract(metadata_json, '$.source') = 'youtube-channel'
+           ELSE 0 END
+      )
+  `);
+}
+
 export function ensureSchema(db: DatabaseSync): void {
   db.exec(`
     CREATE TABLE IF NOT EXISTS imm_schema_version (
@@ -895,6 +991,7 @@ export function ensureSchema(db: DatabaseSync): void {
     .prepare('SELECT schema_version FROM imm_schema_version ORDER BY schema_version DESC LIMIT 1')
     .get() as { schema_version: number } | null;
   if (currentVersion?.schema_version === SCHEMA_VERSION) {
+    classifyYoutubeChannels(db);
     ensureLexicalDailyRollupTables(db);
     ensureLifetimeSummaryTables(db);
     ensureStatsExcludedWordsTable(db);
@@ -906,7 +1003,7 @@ export function ensureSchema(db: DatabaseSync): void {
   db.exec(`
     CREATE TABLE IF NOT EXISTS imm_anime(
       anime_id INTEGER PRIMARY KEY AUTOINCREMENT,
-      normalized_title_key TEXT NOT NULL UNIQUE,
+      normalized_title_key TEXT NOT NULL,
       canonical_title TEXT NOT NULL,
       anilist_id INTEGER UNIQUE,
       title_romaji TEXT,
@@ -914,11 +1011,20 @@ export function ensureSchema(db: DatabaseSync): void {
       title_native TEXT,
       episodes_total INTEGER,
       description TEXT,
+      media_kind TEXT NOT NULL DEFAULT 'anime',
+      tmdb_id INTEGER,
+      tmdb_type TEXT,
       metadata_json TEXT,
       CREATED_DATE TEXT,
       LAST_UPDATE_DATE TEXT
     );
   `);
+  // Schema 26: media_kind separates anime, live-action (TMDB link) and YouTube
+  // channel entries. Kinds are validated in code, not by a CHECK constraint,
+  // so adding one later does not need a table rebuild.
+  addColumnIfMissing(db, 'imm_anime', 'media_kind', "TEXT NOT NULL DEFAULT 'anime'");
+  addColumnIfMissing(db, 'imm_anime', 'tmdb_id', 'INTEGER');
+  addColumnIfMissing(db, 'imm_anime', 'tmdb_type', 'TEXT');
   db.exec(`
     CREATE TABLE IF NOT EXISTS imm_videos(
       video_id INTEGER PRIMARY KEY AUTOINCREMENT,
@@ -1462,6 +1568,8 @@ export function ensureSchema(db: DatabaseSync): void {
     );
   }
 
+  migrateAnimeTableConstraints(db);
+  classifyYoutubeChannels(db);
   migrateSessionEventTimestampsToText(db);
 
   ensureLexicalDailyRollupTables(db);
@@ -1476,6 +1584,10 @@ export function ensureSchema(db: DatabaseSync): void {
     CREATE INDEX IF NOT EXISTS idx_anime_anilist_id
     ON imm_anime(anilist_id)
   `);
+  db.exec(`
+    CREATE INDEX IF NOT EXISTS idx_anime_tmdb_id
+    ON imm_anime(tmdb_id, tmdb_type)
+  `);
   db.exec(`
     CREATE INDEX IF NOT EXISTS idx_videos_anime_id
     ON imm_videos(anime_id)
diff --git a/src/core/services/immersion-tracker/types.ts b/src/core/services/immersion-tracker/types.ts
index 18d3d59a..0c4e414a 100644
--- a/src/core/services/immersion-tracker/types.ts
+++ b/src/core/services/immersion-tracker/types.ts
@@ -1,4 +1,7 @@
-export const SCHEMA_VERSION = 23;
+import type { MediaKind, TmdbMediaType } from '../../../shared/media-kind';
+
+// 26: live-action entries (TMDB link) and YouTube channels share the media_kind column.
+export const SCHEMA_VERSION = 26;
 export const DEFAULT_QUEUE_CAP = 1_000;
 export const DEFAULT_BATCH_SIZE = 25;
 export const DEFAULT_FLUSH_INTERVAL_MS = 500;
@@ -518,9 +521,12 @@ export interface YoutubeVideoMetadata {
 }
 
 export interface AnimeLibraryRow {
+  mediaKind: MediaKind;
   animeId: number;
   canonicalTitle: string;
   anilistId: number | null;
+  tmdbId: number | null;
+  tmdbType: TmdbMediaType | null;
   totalSessions: number;
   totalActiveMs: number;
   totalCards: number;
@@ -531,9 +537,12 @@ export interface AnimeLibraryRow {
 }
 
 export interface AnimeDetailRow {
+  mediaKind: MediaKind;
   animeId: number;
   canonicalTitle: string;
   anilistId: number | null;
+  tmdbId: number | null;
+  tmdbType: TmdbMediaType | null;
   titleRomaji: string | null;
   titleEnglish: string | null;
   titleNative: string | null;
diff --git a/src/core/services/immersion-tracker/youtube-kind.test.ts b/src/core/services/immersion-tracker/youtube-kind.test.ts
new file mode 100644
index 00000000..3a286cb5
--- /dev/null
+++ b/src/core/services/immersion-tracker/youtube-kind.test.ts
@@ -0,0 +1,362 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { Database, type DatabaseSync } from './sqlite';
+import {
+  ensureSchema,
+  getOrCreateAnimeRecord,
+  getOrCreateVideoRecord,
+  linkYoutubeVideoToAnimeRecord,
+} from './storage';
+import { getAnimeDetail, getAnimeLibrary } from './query-library';
+import { updateAnimeAnilistInfo } from './query-maintenance';
+import {
+  repairLegacySeasonlessAnimeRows,
+  resolveAnimeAnilistConflict,
+} from './anime-season-repair';
+import {
+  getAnimeMergeRecommendations,
+  recordAnimeMergeRecommendation,
+} from './anime-merge-recommendations';
+import { createCoverArtFetcher } from '../anilist/cover-art-fetcher';
+import { SCHEMA_VERSION, SOURCE_TYPE_REMOTE, type YoutubeVideoMetadata } from './types';
+
+const metadata: YoutubeVideoMetadata = {
+  youtubeVideoId: 'video1',
+  videoUrl: 'https://www.youtube.com/watch?v=video1',
+  videoTitle: 'Video title',
+  videoThumbnailUrl: null,
+  channelId: 'UC123',
+  channelName: 'Channel name',
+  channelUrl: 'https://www.youtube.com/channel/UC123',
+  channelThumbnailUrl: null,
+  uploaderId: null,
+  uploaderUrl: null,
+  description: null,
+  metadataJson: null,
+};
+
+function createVideo(db: DatabaseSync, key: string): number {
+  return getOrCreateVideoRecord(db, key, {
+    canonicalTitle: 'Video title',
+    sourcePath: null,
+    sourceUrl: metadata.videoUrl,
+    sourceType: SOURCE_TYPE_REMOTE,
+  });
+}
+
+function createAnime(
+  db: DatabaseSync,
+  parsedTitle: string,
+  metadataJson: string | null = null,
+): number {
+  return getOrCreateAnimeRecord(db, {
+    parsedTitle,
+    canonicalTitle: parsedTitle,
+    metadataJson,
+    anilistId: null,
+    titleRomaji: null,
+    titleEnglish: null,
+    titleNative: null,
+  });
+}
+
+test('schema 23 channel migration preserves history and manual assignments and is idempotent', () => {
+  const db = new Database(':memory:');
+  try {
+    ensureSchema(db);
+    const ids = [
+      createAnime(db, 'youtube-channel:UC123'),
+      createAnime(db, 'youtube-channel-url:https://www.youtube.com/@creator'),
+      createAnime(db, 'youtube-channel-name:Creator'),
+      createAnime(db, 'Renamed channel', '{ "source": "youtube-channel" }'),
+    ];
+    const animeId = createAnime(db, 'Anime title', 'legacy non-JSON metadata');
+    const videoId = createVideo(db, 'manual');
+    db.prepare(
+      'UPDATE imm_videos SET anime_id = ?, anime_assignment_locked = 1 WHERE video_id = ?',
+    ).run(animeId, videoId);
+    db.prepare(
+      'INSERT INTO imm_lifetime_anime(anime_id, total_active_ms, total_cards) VALUES (?, 123456, 7)',
+    ).run(animeId);
+    const history = getAnimeLibrary(db);
+    // Reproduce the previous schema, including its lack of a media kind column.
+    db.exec(
+      'DROP INDEX idx_anime_namespace_title; ALTER TABLE imm_anime DROP COLUMN media_kind; DELETE FROM imm_schema_version; INSERT INTO imm_schema_version VALUES (23, 0)',
+    );
+    ensureSchema(db);
+    ensureSchema(db);
+    for (const id of ids) {
+      const row = db.prepare('SELECT media_kind FROM imm_anime WHERE anime_id = ?').get(id);
+      assert.ok(row && typeof row === 'object' && 'media_kind' in row);
+      assert.equal(row.media_kind, 'youtube');
+    }
+    assert.deepEqual(getAnimeLibrary(db), history);
+    assert.equal(linkYoutubeVideoToAnimeRecord(db, videoId, metadata), animeId);
+    const version = db
+      .prepare('SELECT MAX(schema_version) AS version FROM imm_schema_version')
+      .get();
+    assert.ok(version && typeof version === 'object' && 'version' in version);
+    assert.equal(version.version, SCHEMA_VERSION);
+  } finally {
+    db.close();
+  }
+});
+
+test('channel creation and repeated linking expose youtube in library and detail without losing totals', async () => {
+  const db = new Database(':memory:');
+  try {
+    ensureSchema(db);
+    const videoId = createVideo(db, 'first');
+    const channelId = linkYoutubeVideoToAnimeRecord(db, videoId, metadata);
+    assert.ok(channelId);
+    const secondVideoId = createVideo(db, 'second');
+    assert.equal(linkYoutubeVideoToAnimeRecord(db, secondVideoId, metadata), channelId);
+    db.prepare(
+      'INSERT INTO imm_lifetime_anime(anime_id, total_active_ms, total_cards) VALUES (?, 123456, 7)',
+    ).run(channelId);
+    assert.equal(getAnimeLibrary(db)[0]?.mediaKind, 'youtube');
+    const detail = getAnimeDetail(db, channelId);
+    assert.equal(detail?.mediaKind, 'youtube');
+    assert.equal(detail?.episodeCount, 2);
+    assert.equal(detail?.totalActiveMs, 123456);
+    assert.equal(detail?.totalCards, 7);
+
+    // Even parsed season numbers and a matching anime name must not trigger repairs.
+    db.prepare('UPDATE imm_videos SET parsed_season = video_id').run();
+    assert.equal(repairLegacySeasonlessAnimeRows(db).repaired, 0);
+    const animeId = createAnime(db, 'Channel name');
+    for (const matchConfidence of ['exact', 'weak', 'manual'] as const) {
+      assert.equal(
+        resolveAnimeAnilistConflict(db, channelId, 123, { matchConfidence })
+          .anilistAssignmentBlocked,
+        true,
+      );
+    }
+    updateAnimeAnilistInfo(db, videoId, {
+      anilistId: 123,
+      titleRomaji: 'Wrong title',
+      titleEnglish: null,
+      titleNative: null,
+      episodesTotal: 12,
+    });
+    recordAnimeMergeRecommendation(db, channelId, animeId, 123);
+    assert.deepEqual(getAnimeMergeRecommendations(db), []);
+    assert.equal(getAnimeDetail(db, channelId)?.anilistId, null);
+    const fetcher = createCoverArtFetcher(
+      {
+        acquire: async () => {
+          assert.fail('YouTube must not query AniList');
+        },
+        recordResponse: () => {},
+      },
+      console,
+    );
+    assert.equal(await fetcher.fetchIfMissing(db, videoId, 'Channel name'), false);
+  } finally {
+    db.close();
+  }
+});
+
+test('startup reclassifies channels created by an older build after the schema upgrade', () => {
+  const db = new Database(':memory:');
+  try {
+    ensureSchema(db);
+    // An old build omits media_kind when creating a channel in the upgraded DB.
+    const channelId = createAnime(db, 'youtube-channel:UCnew');
+    db.prepare('UPDATE imm_anime SET anilist_id = 321 WHERE anime_id = ?').run(channelId);
+    const animeId = createAnime(db, 'Regular anime');
+    const videoId = createVideo(db, 'older-build');
+    db.prepare(
+      'UPDATE imm_videos SET anime_id = ?, anime_assignment_locked = 1 WHERE video_id = ?',
+    ).run(channelId, videoId);
+    db.prepare(
+      'INSERT INTO imm_lifetime_anime(anime_id, total_active_ms, total_cards) VALUES (?, 120000, 5)',
+    ).run(channelId);
+    assert.equal(getAnimeLibrary(db)[0]?.mediaKind, 'anime');
+    ensureSchema(db);
+    const channel = getAnimeLibrary(db)[0];
+    assert.equal(channel?.animeId, channelId);
+    assert.equal(channel?.mediaKind, 'youtube');
+    assert.equal(
+      (
+        db.prepare('SELECT anilist_id FROM imm_anime WHERE anime_id = ?').get(channelId) as {
+          anilist_id: number | null;
+        }
+      ).anilist_id,
+      null,
+    );
+    assert.equal(channel?.totalActiveMs, 120000);
+    assert.equal(channel?.totalCards, 5);
+    assert.equal(linkYoutubeVideoToAnimeRecord(db, videoId, metadata), channelId);
+    const anime = db.prepare('SELECT media_kind FROM imm_anime WHERE anime_id = ?').get(animeId);
+    assert.ok(anime && typeof anime === 'object' && 'media_kind' in anime);
+    assert.equal(anime.media_kind, 'anime');
+  } finally {
+    db.close();
+  }
+});
+
+test('title identity and aliases never cross media kinds', () => {
+  const db = new Database(':memory:');
+  try {
+    ensureSchema(db);
+    const animeId = createAnime(db, 'Shared title');
+    const input = {
+      mediaKind: 'youtube' as const,
+      parsedTitle: 'Shared title',
+      canonicalTitle: 'Shared title',
+      anilistId: null,
+      titleRomaji: null,
+      titleEnglish: null,
+      titleNative: null,
+      metadataJson: null,
+    };
+    const channelId = getOrCreateAnimeRecord(db, input);
+    assert.notEqual(channelId, animeId);
+    db.prepare('UPDATE imm_anime SET anilist_id = 123 WHERE anime_id = ?').run(channelId);
+    assert.equal(getOrCreateAnimeRecord(db, input), channelId);
+    assert.equal(
+      (
+        db.prepare('SELECT anilist_id FROM imm_anime WHERE anime_id = ?').get(channelId) as {
+          anilist_id: number | null;
+        }
+      ).anilist_id,
+      null,
+    );
+    assert.equal(createAnime(db, 'Shared title'), animeId);
+    db.prepare(
+      'INSERT INTO imm_anime_title_aliases(normalized_title_key, anime_id) VALUES (?, ?)',
+    ).run('alias title', animeId);
+    assert.notEqual(getOrCreateAnimeRecord(db, { ...input, parsedTitle: 'Alias title' }), animeId);
+    assert.throws(() =>
+      db
+        .prepare(
+          "INSERT INTO imm_anime(normalized_title_key, canonical_title, media_kind) VALUES ('shared title', 'duplicate', 'youtube')",
+        )
+        .run(),
+    );
+  } finally {
+    db.close();
+  }
+});
+
+test('anime title lookups land on a same-named live-action entry but never on a channel', () => {
+  const db = new Database(':memory:');
+  try {
+    ensureSchema(db);
+    const dramaId = createAnime(db, 'Hanzawa Naoki');
+    db.prepare(
+      "UPDATE imm_anime SET media_kind = 'live_action', tmdb_id = 61222, tmdb_type = 'tv' WHERE anime_id = ?",
+    ).run(dramaId);
+    // A later season folder parses to the same title with the default anime
+    // kind and must join the TMDB-linked entry rather than duplicate it.
+    assert.equal(
+      getOrCreateAnimeRecord(db, {
+        parsedTitle: 'Hanzawa Naoki',
+        canonicalTitle: 'Hanzawa Naoki',
+        anilistId: 99,
+        titleRomaji: null,
+        titleEnglish: null,
+        titleNative: null,
+        metadataJson: null,
+      }),
+      dramaId,
+    );
+    const row = db
+      .prepare('SELECT media_kind, anilist_id, tmdb_id FROM imm_anime WHERE anime_id = ?')
+      .get(dramaId) as { media_kind: string; anilist_id: number | null; tmdb_id: number };
+    assert.equal(row.media_kind, 'live_action');
+    assert.equal(row.anilist_id, null);
+    assert.equal(row.tmdb_id, 61222);
+    assert.notEqual(
+      getOrCreateAnimeRecord(db, {
+        mediaKind: 'youtube',
+        parsedTitle: 'Hanzawa Naoki',
+        canonicalTitle: 'Hanzawa Naoki',
+        anilistId: null,
+        titleRomaji: null,
+        titleEnglish: null,
+        titleNative: null,
+        metadataJson: null,
+      }),
+      dramaId,
+    );
+  } finally {
+    db.close();
+  }
+});
+
+test('schema 24 title constraint migration preserves referenced data', () => {
+  const db = new Database(':memory:');
+  try {
+    // Reproduce the original table-level uniqueness constraint.
+    db.exec(`CREATE TABLE imm_anime(
+      anime_id INTEGER PRIMARY KEY AUTOINCREMENT,
+      normalized_title_key TEXT NOT NULL UNIQUE,
+      canonical_title TEXT NOT NULL,
+      anilist_id INTEGER UNIQUE,
+      title_romaji TEXT, title_english TEXT, title_native TEXT,
+      episodes_total INTEGER, description TEXT, metadata_json TEXT,
+      CREATED_DATE TEXT, LAST_UPDATE_DATE TEXT,
+      media_kind TEXT NOT NULL DEFAULT 'anime' CHECK(media_kind IN ('anime', 'youtube'))
+    )`);
+    ensureSchema(db);
+    const animeId = createAnime(db, 'Shared title');
+    const videoId = createVideo(db, 'migration-video');
+    db.prepare(
+      'UPDATE imm_videos SET anime_id = ?, anime_assignment_locked = 1 WHERE video_id = ?',
+    ).run(animeId, videoId);
+    db.prepare(
+      'INSERT INTO imm_lifetime_anime(anime_id, total_active_ms, total_cards) VALUES (?, 123, 4)',
+    ).run(animeId);
+    // Restore the old constraint while leaving child rows populated.
+    db.exec(`PRAGMA foreign_keys = OFF;
+      CREATE TABLE old_anime AS SELECT * FROM imm_anime;
+      DROP TABLE imm_anime;
+      CREATE TABLE imm_anime(
+        anime_id INTEGER PRIMARY KEY AUTOINCREMENT, normalized_title_key TEXT NOT NULL UNIQUE,
+        canonical_title TEXT NOT NULL, anilist_id INTEGER UNIQUE,
+        title_romaji TEXT, title_english TEXT, title_native TEXT, episodes_total INTEGER,
+        description TEXT, metadata_json TEXT, CREATED_DATE TEXT, LAST_UPDATE_DATE TEXT,
+        media_kind TEXT NOT NULL DEFAULT 'anime' CHECK(media_kind IN ('anime', 'youtube')));
+      INSERT INTO imm_anime SELECT anime_id, normalized_title_key, canonical_title, anilist_id,
+        title_romaji, title_english, title_native, episodes_total, description, metadata_json,
+        CREATED_DATE, LAST_UPDATE_DATE, media_kind FROM old_anime;
+      DROP TABLE old_anime;
+      DELETE FROM imm_schema_version;
+      INSERT INTO imm_schema_version VALUES (24, 0);
+      PRAGMA foreign_keys = ON;`);
+    ensureSchema(db);
+    ensureSchema(db);
+    assert.deepEqual(db.prepare('PRAGMA foreign_key_check').all(), []);
+    // The v0.19.6 CHECK only allowed anime and youtube; live-action must fit now.
+    db.prepare(
+      "INSERT INTO imm_anime(normalized_title_key, canonical_title, media_kind, tmdb_id, tmdb_type) VALUES ('drama', 'Drama', 'live_action', 1, 'tv')",
+    ).run();
+    assert.equal(
+      (db.prepare('PRAGMA foreign_keys').get() as { foreign_keys: number }).foreign_keys,
+      1,
+    );
+    assert.equal(
+      (
+        db.prepare('SELECT anime_id FROM imm_videos WHERE video_id = ?').get(videoId) as {
+          anime_id: number;
+        }
+      ).anime_id,
+      animeId,
+    );
+    assert.equal(
+      (
+        db
+          .prepare('SELECT total_active_ms FROM imm_lifetime_anime WHERE anime_id = ?')
+          .get(animeId) as { total_active_ms: number }
+      ).total_active_ms,
+      123,
+    );
+    db.prepare(
+      "INSERT INTO imm_anime(normalized_title_key, canonical_title, media_kind) VALUES ('shared title', 'Channel', 'youtube')",
+    ).run();
+  } finally {
+    db.close();
+  }
+});
diff --git a/src/core/services/index.ts b/src/core/services/index.ts
index ecaeb03a..503493ba 100644
--- a/src/core/services/index.ts
+++ b/src/core/services/index.ts
@@ -50,6 +50,11 @@ export {
 } from './tokenizer/yomitan-parser-runtime';
 export { syncYomitanDefaultAnkiServer } from './tokenizer/yomitan-parser-runtime';
 export { createSubtitleProcessingController } from './subtitle-processing-controller';
+export {
+  resolveSanitizedSubtitleSeekCommand,
+  subtitleCueListSeekTime,
+  subtitleCueSeekTime,
+} from './subtitle-cue-navigation';
 export { createFrequencyDictionaryLookup } from './frequency-dictionary';
 export { createJlptVocabularyLookup } from './jlpt-vocab';
 export {
@@ -126,12 +131,6 @@ export {
   resolvePlaybackPlan as resolveJellyfinPlaybackPlanRuntime,
   ticksToSeconds as jellyfinTicksToSecondsRuntime,
 } from './jellyfin';
-export { loadJellyfinSubtitleDelay, saveJellyfinSubtitleDelay } from './jellyfin-subtitle-delay';
-export {
-  estimateSubtitleTimingOffset,
-  type SubtitleTimingOffsetOptions,
-  type SubtitleTimingOffsetResult,
-} from './subtitle-timing-offset';
 export { buildJellyfinTimelinePayload, JellyfinRemoteSessionService } from './jellyfin-remote';
 export {
   broadcastRuntimeOptionsChangedRuntime,
diff --git a/src/core/services/ipc.test.ts b/src/core/services/ipc.test.ts
index 21cb0d8d..91f16769 100644
--- a/src/core/services/ipc.test.ts
+++ b/src/core/services/ipc.test.ts
@@ -89,6 +89,7 @@ function createControllerConfigFixture() {
 
 function createSubtitleSidebarSnapshotFixture(): SubtitleSidebarSnapshot {
   return {
+    sourceKey: 'test-subtitles',
     cues: [],
     currentSubtitle: { text: '', startTime: null, endTime: null },
     config: {
@@ -648,6 +649,114 @@ test('registerIpcHandlers exposes playback window activation request', async ()
   assert.deepEqual(calls, ['activate']);
 });
 
+test('registerIpcHandlers accepts the keep-without-media timing decision', async () => {
+  const { registrar, handlers } = createFakeIpcRegistrar();
+  const requests: unknown[] = [];
+  registerIpcHandlers(
+    createRegisterIpcDeps({
+      resolveMediaTimingReview: async (request) => {
+        requests.push(request);
+        return { ok: true };
+      },
+    }),
+    registrar,
+  );
+
+  const handler = handlers.handle.get(IPC_CHANNELS.request.mediaTimingReviewResolve);
+  assert.ok(handler);
+  assert.deepEqual(
+    await handler!({}, { reviewId: 'review-1', decision: { action: 'skip-media' } }),
+    { ok: true },
+  );
+  assert.deepEqual(requests, [{ reviewId: 'review-1', decision: { action: 'skip-media' } }]);
+});
+
+test('frame IPC validates timestamps and directions', async () => {
+  const { registrar, handlers } = createFakeIpcRegistrar();
+  const requests: unknown[] = [];
+  registerIpcHandlers(
+    createRegisterIpcDeps({
+      getMediaTimingReviewFrame: async (request) => {
+        requests.push(request);
+        return { ok: true };
+      },
+    }),
+    registrar,
+  );
+  const frame = handlers.handle.get(IPC_CHANNELS.request.mediaTimingReviewFrame)!;
+  const valid = { reviewId: 'r', timestamp: 13, direction: 1 };
+  assert.deepEqual(await frame({}, valid), { ok: true });
+  for (const invalid of [
+    null,
+    {},
+    { ...valid, timestamp: NaN },
+    { ...valid, timestamp: '13' },
+    { ...valid, direction: 2 },
+  ]) {
+    assert.equal(((await frame({}, invalid)) as { ok: boolean }).ok, false);
+  }
+  assert.deepEqual(requests, [valid]);
+});
+
+test('registerIpcHandlers validates and forwards timing review text and screenshot selection', async () => {
+  const { registrar, handlers } = createFakeIpcRegistrar();
+  const requests: unknown[] = [];
+  registerIpcHandlers(
+    createRegisterIpcDeps({
+      resolveMediaTimingReview: async (request) => {
+        requests.push(request);
+        return { ok: true };
+      },
+    }),
+    registrar,
+  );
+
+  const handler = handlers.handle.get(IPC_CHANNELS.request.mediaTimingReviewResolve);
+  assert.ok(handler);
+  assert.deepEqual(
+    await handler!(
+      {},
+      {
+        reviewId: 'review-1',
+        decision: {
+          action: 'confirm',
+          startTime: 10,
+          endTime: 12,
+          text: '前の行 対象の行',
+          screenshotTime: 13,
+        },
+      },
+    ),
+    { ok: true },
+  );
+  assert.deepEqual(requests, [
+    {
+      reviewId: 'review-1',
+      decision: {
+        action: 'confirm',
+        startTime: 10,
+        endTime: 12,
+        text: '前の行 対象の行',
+        screenshotTime: 13,
+      },
+    },
+  ]);
+
+  for (const invalid of [{ text: '   ' }, { screenshotTime: Infinity }]) {
+    assert.deepEqual(
+      await handler!(
+        {},
+        {
+          reviewId: 'review-1',
+          decision: { action: 'confirm', startTime: 10, endTime: 12, ...invalid },
+        },
+      ),
+      { ok: false, message: 'Timing review is unavailable.' },
+    );
+  }
+  assert.equal(requests.length, 1);
+});
+
 test('registerIpcHandlers forwards yomitan lookup tracking commands to immersion tracker', () => {
   const { registrar, handlers } = createFakeIpcRegistrar();
   const calls: string[] = [];
@@ -959,7 +1068,13 @@ test('registerIpcHandlers accepts per-controller profile config updates', async
     },
   };
   await saveHandler({}, update);
-  assert.deepEqual(controllerSaves, [update]);
+  assert.deepEqual(controllerSaves, [
+    {
+      ...update,
+      // Validation uses a null prototype to safely store arbitrary profile IDs.
+      profiles: { __proto__: null, ...update.profiles },
+    },
+  ]);
 
   await assert.rejects(async () => {
     await saveHandler(
@@ -1239,3 +1354,18 @@ test('registerIpcHandlers exposes character dictionary selection handlers', asyn
   assert.deepEqual(calls, [21355]);
   assert.deepEqual(searches, ['Re:ZERO']);
 });
+
+test('mpv discovery has its own request and does not change session bindings', async () => {
+  const { registrar, handlers } = createFakeIpcRegistrar();
+  const snapshot = { keys: ['r'], blockedKeys: [] };
+  registerIpcHandlers(
+    createRegisterIpcDeps({ getMpvInputBindings: async () => snapshot }),
+    registrar,
+  );
+  const discovery = handlers.handle.get(IPC_CHANNELS.request.getMpvInputBindings);
+  const session = handlers.handle.get(IPC_CHANNELS.request.getSessionBindings);
+  assert.ok(discovery);
+  assert.ok(session);
+  assert.deepEqual(await discovery({}), snapshot);
+  assert.deepEqual(await session({}), []);
+});
diff --git a/src/core/services/ipc.ts b/src/core/services/ipc.ts
index 2475d215..3bf12a2e 100644
--- a/src/core/services/ipc.ts
+++ b/src/core/services/ipc.ts
@@ -1,4 +1,5 @@
 import electron from 'electron';
+import type { MpvInputBindingsSnapshot } from '../../types/session-bindings';
 import type { BrowserWindow as ElectronBrowserWindow, IpcMainEvent } from 'electron';
 import type {
   ChangelogSnapshot,
@@ -19,6 +20,15 @@ import type {
   YoutubePickerResolveRequest,
   YoutubePickerResolveResult,
 } from '../../types';
+import type {
+  MediaTimingReviewActionResult,
+  MediaTimingReviewPreviewRequest,
+  MediaTimingReviewResolveRequest,
+  MediaTimingReviewFrameRequest,
+  MediaTimingReviewFrameResult,
+  MediaTimingReviewWaveformRequest,
+  MediaTimingReviewWaveformResult,
+} from '../../types/anki';
 import { IPC_CHANNELS, type OverlayHostedModal } from '../../shared/ipc/contracts';
 import {
   parseMpvCommand,
@@ -82,7 +92,8 @@ export interface IpcServiceDeps {
   setMecabEnabled: (enabled: boolean) => void;
   handleMpvCommand: (command: Array<string | number>) => void;
   getKeybindings: () => unknown;
-  getSessionBindings?: () => CompiledSessionBinding[];
+  getMpvInputBindings?: () => Promise<MpvInputBindingsSnapshot>;
+  getSessionBindings?: () => CompiledSessionBinding[] | Promise<CompiledSessionBinding[]>;
   getConfiguredShortcuts: () => unknown;
   dispatchSessionAction?: (request: SessionActionDispatchRequest) => void | Promise<void>;
   getStatsToggleKey: () => string;
@@ -99,6 +110,19 @@ export interface IpcServiceDeps {
   onYoutubePickerResolve: (
     request: YoutubePickerResolveRequest,
   ) => Promise<YoutubePickerResolveResult>;
+  previewMediaTimingReview?: (
+    request: MediaTimingReviewPreviewRequest,
+  ) => Promise<MediaTimingReviewActionResult>;
+  getMediaTimingReviewFrame?: (
+    request: MediaTimingReviewFrameRequest,
+  ) => Promise<MediaTimingReviewFrameResult>;
+  getMediaTimingReviewWaveform?: (
+    request: MediaTimingReviewWaveformRequest,
+  ) => Promise<MediaTimingReviewWaveformResult>;
+  stopMediaTimingReviewPreview?: (reviewId: string) => Promise<MediaTimingReviewActionResult>;
+  resolveMediaTimingReview?: (
+    request: MediaTimingReviewResolveRequest,
+  ) => MediaTimingReviewActionResult | Promise<MediaTimingReviewActionResult>;
   getAnkiConnectStatus: () => boolean;
   getRuntimeOptions: () => unknown;
   setRuntimeOption: (id: RuntimeOptionId, value: RuntimeOptionValue) => unknown;
@@ -222,6 +246,98 @@ function parseOverlayNotificationActionPayload(
   return { notificationId, actionId, ...(typeof noteId === 'number' ? { noteId } : {}) };
 }
 
+function parseMediaTimingReviewPreviewRequest(
+  payload: unknown,
+): MediaTimingReviewPreviewRequest | null {
+  if (!payload || typeof payload !== 'object') return null;
+  const record = payload as Record<string, unknown>;
+  if (
+    typeof record.reviewId !== 'string' ||
+    !record.reviewId ||
+    typeof record.startTime !== 'number' ||
+    !Number.isFinite(record.startTime) ||
+    typeof record.endTime !== 'number' ||
+    !Number.isFinite(record.endTime)
+  ) {
+    return null;
+  }
+  return {
+    reviewId: record.reviewId,
+    startTime: record.startTime,
+    endTime: record.endTime,
+  };
+}
+
+function parseMediaTimingReviewWaveformRequest(
+  payload: unknown,
+): MediaTimingReviewWaveformRequest | null {
+  return parseMediaTimingReviewPreviewRequest(payload);
+}
+
+function parseMediaTimingReviewFrameRequest(
+  payload: unknown,
+): MediaTimingReviewFrameRequest | null {
+  if (!payload || typeof payload !== 'object') return null;
+  const record = payload as Record<string, unknown>;
+  if (
+    typeof record.reviewId !== 'string' ||
+    !record.reviewId ||
+    typeof record.timestamp !== 'number' ||
+    !Number.isFinite(record.timestamp) ||
+    (record.direction !== undefined && record.direction !== -1 && record.direction !== 1)
+  )
+    return null;
+  return {
+    reviewId: record.reviewId,
+    timestamp: record.timestamp,
+    ...(record.direction !== undefined ? { direction: record.direction as -1 | 1 } : {}),
+  };
+}
+
+function parseMediaTimingReviewResolveRequest(
+  payload: unknown,
+): MediaTimingReviewResolveRequest | null {
+  if (!payload || typeof payload !== 'object') return null;
+  const record = payload as Record<string, unknown>;
+  if (typeof record.reviewId !== 'string' || !record.reviewId) return null;
+  const decision = record.decision;
+  if (!decision || typeof decision !== 'object') return null;
+  const decisionRecord = decision as Record<string, unknown>;
+  if (
+    decisionRecord.action === 'use-original' ||
+    decisionRecord.action === 'skip-media' ||
+    decisionRecord.action === 'discard'
+  ) {
+    return { reviewId: record.reviewId, decision: { action: decisionRecord.action } };
+  }
+  if (
+    decisionRecord.action === 'confirm' &&
+    typeof decisionRecord.startTime === 'number' &&
+    Number.isFinite(decisionRecord.startTime) &&
+    typeof decisionRecord.endTime === 'number' &&
+    Number.isFinite(decisionRecord.endTime) &&
+    (decisionRecord.screenshotTime === undefined ||
+      (typeof decisionRecord.screenshotTime === 'number' &&
+        Number.isFinite(decisionRecord.screenshotTime))) &&
+    (decisionRecord.text === undefined ||
+      (typeof decisionRecord.text === 'string' && decisionRecord.text.trim().length > 0))
+  ) {
+    return {
+      reviewId: record.reviewId,
+      decision: {
+        action: 'confirm',
+        startTime: decisionRecord.startTime,
+        endTime: decisionRecord.endTime,
+        ...(decisionRecord.screenshotTime === undefined
+          ? {}
+          : { screenshotTime: decisionRecord.screenshotTime as number }),
+        ...(decisionRecord.text === undefined ? {} : { text: decisionRecord.text }),
+      },
+    };
+  }
+  return null;
+}
+
 export interface IpcDepsRuntimeOptions {
   getMainWindow: () => WindowLike | null;
   getVisibleOverlayVisibility: () => boolean;
@@ -261,7 +377,8 @@ export interface IpcDepsRuntimeOptions {
   getMecabTokenizer: () => MecabTokenizerLike | null;
   handleMpvCommand: (command: Array<string | number>) => void;
   getKeybindings: () => unknown;
-  getSessionBindings?: () => CompiledSessionBinding[];
+  getMpvInputBindings?: () => Promise<MpvInputBindingsSnapshot>;
+  getSessionBindings?: () => CompiledSessionBinding[] | Promise<CompiledSessionBinding[]>;
   getConfiguredShortcuts: () => unknown;
   dispatchSessionAction?: (request: SessionActionDispatchRequest) => void | Promise<void>;
   getStatsToggleKey: () => string;
@@ -278,6 +395,11 @@ export interface IpcDepsRuntimeOptions {
   onYoutubePickerResolve: (
     request: YoutubePickerResolveRequest,
   ) => Promise<YoutubePickerResolveResult>;
+  previewMediaTimingReview?: IpcServiceDeps['previewMediaTimingReview'];
+  getMediaTimingReviewFrame?: IpcServiceDeps['getMediaTimingReviewFrame'];
+  getMediaTimingReviewWaveform?: IpcServiceDeps['getMediaTimingReviewWaveform'];
+  stopMediaTimingReviewPreview?: IpcServiceDeps['stopMediaTimingReviewPreview'];
+  resolveMediaTimingReview?: IpcServiceDeps['resolveMediaTimingReview'];
   getAnkiConnectStatus: () => boolean;
   getRuntimeOptions: () => unknown;
   setRuntimeOption: (id: RuntimeOptionId, value: RuntimeOptionValue) => unknown;
@@ -351,6 +473,7 @@ export function createIpcDepsRuntime(options: IpcDepsRuntimeOptions): IpcService
     },
     handleMpvCommand: options.handleMpvCommand,
     getKeybindings: options.getKeybindings,
+    getMpvInputBindings: options.getMpvInputBindings,
     getSessionBindings: options.getSessionBindings ?? (() => []),
     getConfiguredShortcuts: options.getConfiguredShortcuts,
     dispatchSessionAction: options.dispatchSessionAction ?? (async () => {}),
@@ -371,6 +494,11 @@ export function createIpcDepsRuntime(options: IpcDepsRuntimeOptions): IpcService
       options.activatePlaybackWindowForOverlayInteraction ?? (() => false),
     runSubsyncManual: options.runSubsyncManual,
     onYoutubePickerResolve: options.onYoutubePickerResolve,
+    previewMediaTimingReview: options.previewMediaTimingReview,
+    getMediaTimingReviewFrame: options.getMediaTimingReviewFrame,
+    getMediaTimingReviewWaveform: options.getMediaTimingReviewWaveform,
+    stopMediaTimingReviewPreview: options.stopMediaTimingReviewPreview,
+    resolveMediaTimingReview: options.resolveMediaTimingReview,
     getAnkiConnectStatus: options.getAnkiConnectStatus,
     getRuntimeOptions: options.getRuntimeOptions,
     setRuntimeOption: options.setRuntimeOption,
@@ -498,6 +626,56 @@ export function registerIpcHandlers(deps: IpcServiceDeps, ipc: IpcMainRegistrar
     },
   );
 
+  ipc.handle(
+    IPC_CHANNELS.request.mediaTimingReviewPreview,
+    async (_event: unknown, payload: unknown) => {
+      const request = parseMediaTimingReviewPreviewRequest(payload);
+      if (!request || !deps.previewMediaTimingReview) {
+        return { ok: false, message: 'Timing preview is unavailable.' };
+      }
+      return await deps.previewMediaTimingReview(request);
+    },
+  );
+  ipc.handle(
+    IPC_CHANNELS.request.mediaTimingReviewWaveform,
+    async (_event: unknown, payload: unknown) => {
+      const request = parseMediaTimingReviewWaveformRequest(payload);
+      if (!request || !deps.getMediaTimingReviewWaveform) {
+        return { ok: false, message: 'Timing waveform is unavailable.' };
+      }
+      return await deps.getMediaTimingReviewWaveform(request);
+    },
+  );
+  ipc.handle(
+    IPC_CHANNELS.request.mediaTimingReviewFrame,
+    async (_event: unknown, payload: unknown) => {
+      const request = parseMediaTimingReviewFrameRequest(payload);
+      if (!request || !deps.getMediaTimingReviewFrame) {
+        return { ok: false, message: 'Screenshot preview is unavailable.' };
+      }
+      return await deps.getMediaTimingReviewFrame(request);
+    },
+  );
+  ipc.handle(
+    IPC_CHANNELS.request.mediaTimingReviewStopPreview,
+    async (_event: unknown, reviewId: unknown) => {
+      if (typeof reviewId !== 'string' || !reviewId || !deps.stopMediaTimingReviewPreview) {
+        return { ok: false, message: 'Timing preview is unavailable.' };
+      }
+      return await deps.stopMediaTimingReviewPreview(reviewId);
+    },
+  );
+  ipc.handle(
+    IPC_CHANNELS.request.mediaTimingReviewResolve,
+    async (_event: unknown, payload: unknown) => {
+      const request = parseMediaTimingReviewResolveRequest(payload);
+      if (!request || !deps.resolveMediaTimingReview) {
+        return { ok: false, message: 'Timing review is unavailable.' };
+      }
+      return await deps.resolveMediaTimingReview(request);
+    },
+  );
+
   ipc.on(IPC_CHANNELS.command.openYomitanSettings, () => {
     deps.openYomitanSettings();
   });
@@ -638,6 +816,10 @@ export function registerIpcHandlers(deps: IpcServiceDeps, ipc: IpcMainRegistrar
     return deps.getKeybindings();
   });
 
+  ipc.handle(IPC_CHANNELS.request.getMpvInputBindings, () => {
+    return deps.getMpvInputBindings?.() ?? { keys: [], blockedKeys: [] };
+  });
+
   ipc.handle(IPC_CHANNELS.request.getSessionBindings, () => {
     return deps.getSessionBindings?.() ?? [];
   });
diff --git a/src/core/services/jellyfin-remote.test.ts b/src/core/services/jellyfin-remote.test.ts
index 22b2e6b6..e3433976 100644
--- a/src/core/services/jellyfin-remote.test.ts
+++ b/src/core/services/jellyfin-remote.test.ts
@@ -4,6 +4,17 @@ import { buildJellyfinTimelinePayload, JellyfinRemoteSessionService } from './je
 
 class FakeWebSocket {
   private listeners: Record<string, Array<(...args: unknown[]) => void>> = {};
+  sent: string[] = [];
+  terminated = false;
+
+  send(data: string): void {
+    this.sent.push(data);
+  }
+
+  terminate(): void {
+    this.terminated = true;
+    this.emit('close');
+  }
 
   on(event: string, listener: (...args: unknown[]) => void): this {
     if (!this.listeners[event]) {
@@ -58,7 +69,7 @@ test('start posts capabilities on socket connect', async () => {
     accessToken: 'token-1',
     deviceId: 'device-1',
     webSocketFactory: (url) => {
-      assert.equal(url, 'ws://jellyfin.local:8096/socket?api_key=token-1&deviceId=device-1');
+      assert.equal(url, 'ws://jellyfin.local:8096/socket?ApiKey=token-1&deviceId=device-1');
       const socket = new FakeWebSocket();
       sockets.push(socket);
       return socket as unknown as any;
@@ -99,7 +110,8 @@ test('socket headers include jellyfin authorization metadata', () => {
   assert.equal(seenHeaders.length, 1);
   assert.ok(seenHeaders[0]!['Authorization']!.includes('Client="SubMiner"'));
   assert.ok(seenHeaders[0]!['Authorization']!.includes('DeviceId="device-auth"'));
-  assert.ok(seenHeaders[0]!['X-Emby-Authorization']);
+  assert.equal('X-Emby-Authorization' in seenHeaders[0]!, false);
+  assert.equal('X-Emby-Token' in seenHeaders[0]!, false);
 });
 
 test('dispatches inbound Play, Playstate, and GeneralCommand messages', () => {
@@ -355,3 +367,149 @@ test('advertiseNow validates server registration using Sessions endpoint', async
   assert.equal(ok, true);
   assert.ok(calls.some((url) => url.endsWith('/Sessions')));
 });
+
+test('answers ForceKeepAlive with KeepAlive messages on the advertised cadence', () => {
+  const sockets: FakeWebSocket[] = [];
+  const timers: Array<{ handler: () => void; delay: number }> = [];
+
+  const service = new JellyfinRemoteSessionService({
+    serverUrl: 'http://jellyfin.local',
+    accessToken: 'token-ka',
+    deviceId: 'device-ka',
+    webSocketFactory: () => {
+      const socket = new FakeWebSocket();
+      sockets.push(socket);
+      return socket as unknown as any;
+    },
+    fetchImpl: (async () => new Response(null, { status: 200 })) as typeof fetch,
+    setTimer: ((handler: () => void, delay?: number) => {
+      timers.push({ handler, delay: Number(delay) });
+      return timers.length as unknown as ReturnType<typeof setTimeout>;
+    }) as typeof setTimeout,
+    clearTimer: (() => undefined) as typeof clearTimeout,
+  });
+
+  service.start();
+  sockets[0]!.emit('open');
+  assert.deepEqual(sockets[0]!.sent, ['{"MessageType":"KeepAlive"}']);
+  assert.equal(timers[0]!.delay, 30_000);
+
+  sockets[0]!.emit('message', JSON.stringify({ MessageType: 'ForceKeepAlive', Data: 20 }));
+  assert.equal(sockets[0]!.sent.length, 2);
+  assert.equal(timers.at(-1)!.delay, 10_000);
+
+  timers.at(-1)!.handler();
+  assert.equal(sockets[0]!.sent.length, 3);
+});
+
+test('reconnects when the server stops answering keep-alives', () => {
+  let now = 1_000_000;
+  const sockets: FakeWebSocket[] = [];
+  const timers: Array<() => void> = [];
+  const warnings: string[] = [];
+
+  const service = new JellyfinRemoteSessionService({
+    serverUrl: 'http://jellyfin.local',
+    accessToken: 'token-lost',
+    deviceId: 'device-lost',
+    webSocketFactory: () => {
+      const socket = new FakeWebSocket();
+      sockets.push(socket);
+      return socket as unknown as any;
+    },
+    fetchImpl: (async () => new Response(null, { status: 200 })) as typeof fetch,
+    getNow: () => now,
+    logWarn: (message) => {
+      warnings.push(message);
+    },
+    reconnectBaseDelayMs: 100,
+    setTimer: ((handler: () => void) => {
+      timers.push(handler);
+      return timers.length as unknown as ReturnType<typeof setTimeout>;
+    }) as typeof setTimeout,
+    clearTimer: (() => undefined) as typeof clearTimeout,
+  });
+
+  service.start();
+  sockets[0]!.emit('open');
+
+  // Two silent ticks are still within the 90s tolerance; the third marks the socket lost.
+  now += 30_000;
+  timers.shift()!();
+  now += 30_000;
+  timers.shift()!();
+  assert.equal(sockets[0]!.sent.length, 3);
+  assert.equal(sockets[0]!.terminated, false);
+
+  now += 30_000;
+  timers.shift()!();
+  assert.equal(sockets[0]!.terminated, true);
+  assert.equal(service.isConnected(), false);
+  assert.equal(warnings.length, 1);
+
+  timers.shift()!();
+  assert.equal(sockets.length, 2);
+});
+
+test('warns once per failing timeline endpoint until it recovers', async () => {
+  const warnings: string[] = [];
+  let status = 400;
+
+  const service = new JellyfinRemoteSessionService({
+    serverUrl: 'http://jellyfin.local',
+    accessToken: 'token-warn',
+    deviceId: 'device-warn',
+    webSocketFactory: () => new FakeWebSocket() as unknown as any,
+    fetchImpl: (async () => new Response(null, { status })) as typeof fetch,
+    logWarn: (message) => {
+      warnings.push(message);
+    },
+  });
+  const state = { itemId: 'item-1', positionTicks: 10, playMethod: 'DirectPlay' };
+
+  assert.equal(await service.reportStopped(state), false);
+  assert.equal(await service.reportStopped(state), false);
+  assert.equal(warnings.length, 1);
+  assert.match(warnings[0]!, /Sessions\/Playing\/Stopped/);
+
+  status = 200;
+  assert.equal(await service.reportStopped(state), true);
+  status = 500;
+  assert.equal(await service.reportStopped(state), false);
+  assert.equal(warnings.length, 2);
+});
+
+test('ignores messages from a superseded socket', () => {
+  const sockets: FakeWebSocket[] = [];
+  const playPayloads: unknown[] = [];
+
+  const service = new JellyfinRemoteSessionService({
+    serverUrl: 'http://jellyfin.local',
+    accessToken: 'token-stale',
+    deviceId: 'device-stale',
+    webSocketFactory: () => {
+      const socket = new FakeWebSocket();
+      sockets.push(socket);
+      return socket as unknown as any;
+    },
+    fetchImpl: (async () => new Response(null, { status: 200 })) as typeof fetch,
+    onPlay: (payload) => {
+      playPayloads.push(payload);
+    },
+    setTimer: (() => 1 as unknown as ReturnType<typeof setTimeout>) as unknown as typeof setTimeout,
+    clearTimer: (() => undefined) as typeof clearTimeout,
+  });
+
+  service.start();
+  service.stop();
+  service.start();
+  sockets[1]!.emit('open');
+  assert.equal(sockets.length, 2);
+
+  sockets[0]!.emit('message', JSON.stringify({ MessageType: 'ForceKeepAlive', Data: 10 }));
+  sockets[0]!.emit('message', JSON.stringify({ MessageType: 'Play', Data: { ItemIds: ['x'] } }));
+
+  assert.deepEqual(sockets[0]!.sent, []);
+  assert.deepEqual(playPayloads, []);
+  assert.deepEqual(sockets[1]!.sent, ['{"MessageType":"KeepAlive"}']);
+});
diff --git a/src/core/services/jellyfin-remote.ts b/src/core/services/jellyfin-remote.ts
index ef0c301b..649f5a48 100644
--- a/src/core/services/jellyfin-remote.ts
+++ b/src/core/services/jellyfin-remote.ts
@@ -45,9 +45,22 @@ interface JellyfinRemoteSocket {
   on(event: 'close', listener: () => void): this;
   on(event: 'error', listener: (error: Error) => void): this;
   on(event: 'message', listener: (data: unknown) => void): this;
+  send(data: string): void;
+  terminate?(): void;
   close(): void;
 }
 
+// Jellyfin advertises its keep-alive timeout in the ForceKeepAlive message (60s by default),
+// drops sockets that stay silent past it, and since 12.0 also detaches the session's remote
+// controller when that happens. The drop never reaches the client as a close frame, so the
+// client has to keep sending KeepAlive and treat missing replies as a dead connection.
+const DEFAULT_KEEP_ALIVE_TIMEOUT_MS = 60_000;
+const KEEP_ALIVE_LOST_FACTOR = 1.5;
+
+function unrefTimer(timer: ReturnType<typeof setTimeout>): void {
+  (timer as unknown as { unref?: () => void }).unref?.();
+}
+
 type JellyfinRemoteSocketHeaders = Record<string, string>;
 
 export interface JellyfinRemoteSessionServiceOptions {
@@ -77,6 +90,9 @@ export interface JellyfinRemoteSessionServiceOptions {
   deviceName?: string;
   onConnected?: () => void;
   onDisconnected?: () => void;
+  logWarn?: (message: string, details?: unknown) => void;
+  keepAliveTimeoutMs?: number;
+  getNow?: () => number;
 }
 
 function normalizeServerUrl(serverUrl: string): string {
@@ -196,6 +212,12 @@ export class JellyfinRemoteSessionService {
   private readonly authHeader: string;
   private readonly onConnected?: () => void;
   private readonly onDisconnected?: () => void;
+  private readonly logWarn?: (message: string, details?: unknown) => void;
+  private readonly now: () => number;
+  private keepAliveTimeoutMs: number;
+  private keepAliveTimer: ReturnType<typeof setTimeout> | null = null;
+  private lastInboundAtMs = 0;
+  private readonly failedRequestPaths = new Set<string>();
 
   private readonly reconnectBaseDelayMs: number;
   private readonly reconnectMaxDelayMs: number;
@@ -233,6 +255,12 @@ export class JellyfinRemoteSessionService {
     });
     this.onConnected = options.onConnected;
     this.onDisconnected = options.onDisconnected;
+    this.logWarn = options.logWarn;
+    this.now = options.getNow ?? Date.now;
+    this.keepAliveTimeoutMs = Math.max(
+      1000,
+      options.keepAliveTimeoutMs ?? DEFAULT_KEEP_ALIVE_TIMEOUT_MS,
+    );
     this.reconnectBaseDelayMs = Math.max(100, options.reconnectBaseDelayMs ?? 500);
     this.reconnectMaxDelayMs = Math.max(
       this.reconnectBaseDelayMs,
@@ -250,6 +278,7 @@ export class JellyfinRemoteSessionService {
   public stop(): void {
     this.running = false;
     this.connected = false;
+    this.stopKeepAlive();
     if (this.reconnectTimer) {
       this.clearTimer(this.reconnectTimer);
       this.reconnectTimer = null;
@@ -298,12 +327,16 @@ export class JellyfinRemoteSessionService {
       if (this.socket !== socket || !this.running) return;
       this.connected = true;
       this.reconnectAttempt = 0;
+      this.lastInboundAtMs = this.now();
+      this.startKeepAlive(socket, this.keepAliveTimeoutMs);
       this.onConnected?.();
       void this.postCapabilities();
     });
 
     socket.on('message', (rawData) => {
-      this.handleInboundMessage(rawData);
+      if (this.socket !== socket || !this.running) return;
+      this.lastInboundAtMs = this.now();
+      this.handleInboundMessage(socket, rawData);
     });
 
     const handleDisconnect = () => {
@@ -311,6 +344,7 @@ export class JellyfinRemoteSessionService {
       disconnected = true;
       if (this.socket === socket) {
         this.socket = null;
+        this.stopKeepAlive();
       }
       this.connected = false;
       this.onDisconnected?.();
@@ -323,6 +357,51 @@ export class JellyfinRemoteSessionService {
     socket.on('error', handleDisconnect);
   }
 
+  private startKeepAlive(socket: JellyfinRemoteSocket, timeoutMs: number): void {
+    this.stopKeepAlive();
+    this.keepAliveTimeoutMs = timeoutMs;
+    this.sendKeepAlive(socket);
+    this.scheduleKeepAliveTick(socket);
+  }
+
+  private scheduleKeepAliveTick(socket: JellyfinRemoteSocket): void {
+    const intervalMs = Math.max(1000, Math.floor(this.keepAliveTimeoutMs / 2));
+    const timer = this.setTimer(() => {
+      this.keepAliveTimer = null;
+      if (this.socket !== socket || !this.running) return;
+      const silentForMs = this.now() - this.lastInboundAtMs;
+      if (silentForMs >= this.keepAliveTimeoutMs * KEEP_ALIVE_LOST_FACTOR) {
+        this.logWarn?.('Jellyfin remote websocket stopped answering keep-alives; reconnecting.');
+        // Dropping the socket raises 'close', which schedules the reconnect.
+        if (socket.terminate) {
+          socket.terminate();
+        } else {
+          socket.close();
+        }
+        return;
+      }
+      this.sendKeepAlive(socket);
+      this.scheduleKeepAliveTick(socket);
+    }, intervalMs);
+    unrefTimer(timer);
+    this.keepAliveTimer = timer;
+  }
+
+  private stopKeepAlive(): void {
+    if (this.keepAliveTimer) {
+      this.clearTimer(this.keepAliveTimer);
+      this.keepAliveTimer = null;
+    }
+  }
+
+  private sendKeepAlive(socket: JellyfinRemoteSocket): void {
+    try {
+      socket.send(JSON.stringify({ MessageType: 'KeepAlive' }));
+    } catch (error) {
+      this.logWarn?.('Failed to send Jellyfin remote keep-alive.', error);
+    }
+  }
+
   private scheduleReconnect(): void {
     const delay = Math.min(
       this.reconnectMaxDelayMs,
@@ -342,7 +421,7 @@ export class JellyfinRemoteSessionService {
     const baseUrl = new URL(`${this.serverUrl}/`);
     const socketUrl = new URL('/socket', baseUrl);
     socketUrl.protocol = baseUrl.protocol === 'https:' ? 'wss:' : 'ws:';
-    socketUrl.searchParams.set('api_key', this.accessToken);
+    socketUrl.searchParams.set('ApiKey', this.accessToken);
     socketUrl.searchParams.set('deviceId', this.deviceId);
     return socketUrl.toString();
   }
@@ -350,8 +429,6 @@ export class JellyfinRemoteSessionService {
   private createSocket(url: string): JellyfinRemoteSocket {
     const headers: JellyfinRemoteSocketHeaders = {
       Authorization: this.authHeader,
-      'X-Emby-Authorization': this.authHeader,
-      'X-Emby-Token': this.accessToken,
     };
     if (this.socketHeadersFactory) {
       return this.socketHeadersFactory(url, headers);
@@ -375,8 +452,6 @@ export class JellyfinRemoteSessionService {
         method: 'GET',
         headers: {
           Authorization: this.authHeader,
-          'X-Emby-Authorization': this.authHeader,
-          'X-Emby-Token': this.accessToken,
         },
       });
       if (!response.ok) return false;
@@ -398,21 +473,41 @@ export class JellyfinRemoteSessionService {
         headers: {
           'Content-Type': 'application/json',
           Authorization: this.authHeader,
-          'X-Emby-Authorization': this.authHeader,
-          'X-Emby-Token': this.accessToken,
         },
         body: JSON.stringify(payload),
       });
+      this.noteRequestOutcome(path, response.ok ? null : `HTTP ${response.status}`);
       return response.ok;
-    } catch {
+    } catch (error) {
+      this.noteRequestOutcome(path, error);
       return false;
     }
   }
 
-  private handleInboundMessage(rawData: unknown): void {
+  // Warn once per path while it keeps failing so a rejected stop report is visible in the
+  // log without a warning per progress tick.
+  private noteRequestOutcome(path: string, failure: unknown): void {
+    if (failure === null) {
+      this.failedRequestPaths.delete(path);
+      return;
+    }
+    if (this.failedRequestPaths.has(path)) return;
+    this.failedRequestPaths.add(path);
+    this.logWarn?.(`Jellyfin remote request failed: POST ${path}`, failure);
+  }
+
+  private handleInboundMessage(socket: JellyfinRemoteSocket, rawData: unknown): void {
     const message = parseInboundMessage(rawData);
     if (!message) return;
     const messageType = message.MessageType;
+    if (messageType === 'ForceKeepAlive') {
+      const seconds = Number(message.Data);
+      const timeoutMs =
+        Number.isFinite(seconds) && seconds > 0 ? seconds * 1000 : this.keepAliveTimeoutMs;
+      this.startKeepAlive(socket, timeoutMs);
+      return;
+    }
+    if (messageType === 'KeepAlive') return;
     const payload = parseMessageData(message.Data);
     if (messageType === 'Play') {
       this.onPlay?.(payload);
diff --git a/src/core/services/jellyfin-subtitle-delay.test.ts b/src/core/services/jellyfin-subtitle-delay.test.ts
deleted file mode 100644
index 6f844d49..00000000
--- a/src/core/services/jellyfin-subtitle-delay.test.ts
+++ /dev/null
@@ -1,54 +0,0 @@
-import assert from 'node:assert/strict';
-import * as fs from 'node:fs';
-import * as os from 'node:os';
-import * as path from 'node:path';
-import test from 'node:test';
-import { loadJellyfinSubtitleDelay, saveJellyfinSubtitleDelay } from './jellyfin-subtitle-delay';
-
-function statePath(name: string): string {
-  return path.join(fs.mkdtempSync(path.join(os.tmpdir(), 'subminer-jellyfin-delay-')), name);
-}
-
-test('jellyfin subtitle delay store saves and loads delay by item and stream', () => {
-  const filePath = statePath('delays.json');
-
-  assert.equal(
-    saveJellyfinSubtitleDelay({
-      filePath,
-      itemId: 'episode-1',
-      streamIndex: 3,
-      delaySeconds: 1.25,
-    }),
-    true,
-  );
-
-  assert.equal(loadJellyfinSubtitleDelay({ filePath, itemId: 'episode-1', streamIndex: 3 }), 1.25);
-  assert.equal(loadJellyfinSubtitleDelay({ filePath, itemId: 'episode-1', streamIndex: 4 }), null);
-});
-
-test('jellyfin subtitle delay store preserves other stream delays when updating one stream', () => {
-  const filePath = statePath('delays.json');
-
-  saveJellyfinSubtitleDelay({ filePath, itemId: 'episode-1', streamIndex: 3, delaySeconds: 1.25 });
-  saveJellyfinSubtitleDelay({ filePath, itemId: 'episode-1', streamIndex: 4, delaySeconds: -0.5 });
-  saveJellyfinSubtitleDelay({ filePath, itemId: 'episode-1', streamIndex: 3, delaySeconds: 2 });
-
-  assert.equal(loadJellyfinSubtitleDelay({ filePath, itemId: 'episode-1', streamIndex: 3 }), 2);
-  assert.equal(loadJellyfinSubtitleDelay({ filePath, itemId: 'episode-1', streamIndex: 4 }), -0.5);
-});
-
-test('jellyfin subtitle delay store ignores invalid files and values', () => {
-  const filePath = statePath('delays.json');
-  fs.writeFileSync(filePath, '{');
-
-  assert.equal(loadJellyfinSubtitleDelay({ filePath, itemId: 'episode-1', streamIndex: 3 }), null);
-  assert.equal(
-    saveJellyfinSubtitleDelay({
-      filePath,
-      itemId: 'episode-1',
-      streamIndex: 3,
-      delaySeconds: Number.NaN,
-    }),
-    false,
-  );
-});
diff --git a/src/core/services/jellyfin-subtitle-delay.ts b/src/core/services/jellyfin-subtitle-delay.ts
deleted file mode 100644
index 18bf8b3b..00000000
--- a/src/core/services/jellyfin-subtitle-delay.ts
+++ /dev/null
@@ -1,66 +0,0 @@
-import * as fs from 'fs';
-import * as path from 'path';
-
-type JellyfinSubtitleDelayStore = {
-  version?: unknown;
-  delays?: unknown;
-};
-
-type JellyfinSubtitleDelayParams = {
-  filePath: string;
-  itemId: string;
-  streamIndex: number;
-};
-
-type SaveJellyfinSubtitleDelayParams = JellyfinSubtitleDelayParams & {
-  delaySeconds: number;
-};
-
-function storeKey(itemId: string, streamIndex: number): string {
-  return JSON.stringify([itemId, streamIndex]);
-}
-
-function readDelayMap(filePath: string): Record<string, number> {
-  try {
-    if (!fs.existsSync(filePath)) return {};
-    const parsed = JSON.parse(fs.readFileSync(filePath, 'utf-8')) as JellyfinSubtitleDelayStore;
-    if (
-      !parsed ||
-      typeof parsed !== 'object' ||
-      !parsed.delays ||
-      typeof parsed.delays !== 'object'
-    ) {
-      return {};
-    }
-    const delays: Record<string, number> = {};
-    for (const [key, value] of Object.entries(parsed.delays as Record<string, unknown>)) {
-      if (typeof value === 'number' && Number.isFinite(value)) {
-        delays[key] = value;
-      }
-    }
-    return delays;
-  } catch {
-    return {};
-  }
-}
-
-export function loadJellyfinSubtitleDelay(params: JellyfinSubtitleDelayParams): number | null {
-  const delay = readDelayMap(params.filePath)[storeKey(params.itemId, params.streamIndex)];
-  return typeof delay === 'number' && Number.isFinite(delay) ? delay : null;
-}
-
-export function saveJellyfinSubtitleDelay(params: SaveJellyfinSubtitleDelayParams): boolean {
-  if (!Number.isFinite(params.delaySeconds)) return false;
-  try {
-    const delays = readDelayMap(params.filePath);
-    delays[storeKey(params.itemId, params.streamIndex)] = params.delaySeconds;
-    const dir = path.dirname(params.filePath);
-    if (!fs.existsSync(dir)) {
-      fs.mkdirSync(dir, { recursive: true });
-    }
-    fs.writeFileSync(params.filePath, JSON.stringify({ version: 1, delays }, null, 2));
-    return true;
-  } catch {
-    return false;
-  }
-}
diff --git a/src/core/services/jellyfin.test.ts b/src/core/services/jellyfin.test.ts
index 19e71a4d..301f109d 100644
--- a/src/core/services/jellyfin.test.ts
+++ b/src/core/services/jellyfin.test.ts
@@ -279,7 +279,7 @@ test('resolvePlaybackPlan prefers transcode when directPlayPreferred is disabled
     assert.equal(plan.mode, 'transcode');
     const url = new URL(plan.url);
     assert.match(url.pathname, /\/Videos\/movie-2\/master\.m3u8$/);
-    assert.equal(url.searchParams.get('api_key'), 'token');
+    assert.equal(url.searchParams.get('ApiKey'), 'token');
     assert.equal(url.searchParams.get('AudioStreamIndex'), '4');
     assert.equal(url.searchParams.get('StartTimeTicks'), '10000000');
   } finally {
@@ -365,7 +365,7 @@ test('listSubtitleTracks returns all subtitle streams with delivery urls', async
                 IsForced: true,
                 IsExternal: true,
                 DeliveryMethod: 'External',
-                DeliveryUrl: '/Videos/movie-1/ms-1/Subtitles/3/Stream.srt',
+                DeliveryUrl: '/Videos/movie-1/ms-1/Subtitles/3/Stream.srt?api_key=server-token',
                 IsExternalUrl: false,
               },
               {
@@ -377,6 +377,14 @@ test('listSubtitleTracks returns all subtitle streams with delivery urls', async
                 DeliveryUrl: 'https://cdn.example.com/subs.srt',
                 IsExternalUrl: true,
               },
+              {
+                Type: 'Subtitle',
+                Index: 5,
+                Codec: 'PGSSUB',
+                Language: 'eng',
+                DisplayTitle: 'English PGS',
+                DeliveryMethod: 'Embed',
+              },
             ],
           },
         ],
@@ -395,20 +403,21 @@ test('listSubtitleTracks returns all subtitle streams with delivery urls', async
       clientInfo,
       'movie-1',
     );
-    assert.equal(tracks.length, 3);
+    assert.equal(tracks.length, 4);
     assert.deepEqual(
       tracks.map((track) => track.index),
-      [2, 3, 4],
+      [2, 3, 4, 5],
     );
     assert.equal(
       tracks[0]!.deliveryUrl,
-      'http://jellyfin.local/Videos/movie-1/ms-1/Subtitles/2/Stream.srt?api_key=token',
+      'http://jellyfin.local/Videos/movie-1/ms-1/Subtitles/2/Stream.srt?ApiKey=token',
     );
     assert.equal(
       tracks[1]!.deliveryUrl,
-      'http://jellyfin.local/Videos/movie-1/ms-1/Subtitles/3/Stream.srt?api_key=token',
+      'http://jellyfin.local/Videos/movie-1/ms-1/Subtitles/3/Stream.srt?ApiKey=token',
     );
     assert.equal(tracks[2]!.deliveryUrl, 'https://cdn.example.com/subs.srt');
+    assert.equal(tracks[3]!.deliveryUrl, null, 'bitmap subtitles cannot be fetched as text');
   } finally {
     globalThis.fetch = originalFetch;
   }
@@ -505,7 +514,7 @@ test('resolvePlaybackPlan reuses server transcoding url and appends missing para
     const url = new URL(plan.url);
     assert.match(url.pathname, /\/Videos\/movie-4\/master\.m3u8$/);
     assert.equal(url.searchParams.get('VideoCodec'), 'hevc');
-    assert.equal(url.searchParams.get('api_key'), 'token');
+    assert.equal(url.searchParams.get('ApiKey'), 'token');
     assert.equal(url.searchParams.get('AudioStreamIndex'), '3');
     assert.equal(url.searchParams.get('SubtitleStreamIndex'), '8');
     assert.equal(url.searchParams.get('StartTimeTicks'), '50000000');
@@ -626,7 +635,7 @@ test('listSubtitleTracks falls back from PlaybackInfo to item media sources', as
     assert.equal(tracks[0]!.index, 11);
     assert.equal(
       tracks[0]!.deliveryUrl,
-      'http://jellyfin.local/Videos/movie-fallback/ms-fallback/Subtitles/11/Stream.srt?api_key=token',
+      'http://jellyfin.local/Videos/movie-fallback/ms-fallback/Subtitles/11/Stream.srt?ApiKey=token',
     );
   } finally {
     globalThis.fetch = originalFetch;
@@ -789,3 +798,67 @@ test('resolvePlaybackPlan surfaces no-source and no-stream fallback errors', asy
     globalThis.fetch = originalFetch;
   }
 });
+
+test('API requests authenticate with the MediaBrowser header only (no legacy X-Emby-Token)', async () => {
+  const originalFetch = globalThis.fetch;
+  const seenHeaders: Headers[] = [];
+  globalThis.fetch = (async (_input, init) => {
+    seenHeaders.push(new Headers(init?.headers));
+    return new Response(JSON.stringify({ Items: [] }), { status: 200 });
+  }) as typeof fetch;
+
+  try {
+    await listLibraries(
+      { serverUrl: 'http://jellyfin.local', accessToken: 'token', userId: 'u1', username: 'kyle' },
+      clientInfo,
+    );
+    assert.equal(seenHeaders.length, 1);
+    const headers = seenHeaders[0]!;
+    const authorization = headers.get('authorization') ?? '';
+    assert.match(authorization, /^MediaBrowser /);
+    assert.match(authorization, /Token="token"/);
+    assert.match(authorization, /DeviceId="subminer-test"/);
+    assert.equal(headers.has('x-emby-token'), false);
+    assert.equal(headers.has('x-emby-authorization'), false);
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
+test('resolvePlaybackPlan replaces a legacy api_key on the server transcoding url with ApiKey', async () => {
+  const originalFetch = globalThis.fetch;
+  globalThis.fetch = (async () =>
+    new Response(
+      JSON.stringify({
+        Id: 'movie-legacy',
+        Name: 'Movie Legacy',
+        MediaSources: [
+          {
+            Id: 'ms-legacy',
+            Container: 'mkv',
+            SupportsDirectStream: false,
+            SupportsTranscoding: true,
+            TranscodingUrl: '/Videos/movie-legacy/master.m3u8?VideoCodec=hevc&api_key=server-token',
+          },
+        ],
+      }),
+      { status: 200 },
+    )) as typeof fetch;
+
+  try {
+    const plan = await resolvePlaybackPlan(
+      { serverUrl: 'http://jellyfin.local', accessToken: 'token', userId: 'u1', username: 'kyle' },
+      clientInfo,
+      { enabled: true, directPlayPreferred: true },
+      { itemId: 'movie-legacy' },
+    );
+
+    assert.equal(plan.mode, 'transcode');
+    const url = new URL(plan.url);
+    assert.equal(url.searchParams.get('ApiKey'), 'token');
+    assert.equal(url.searchParams.has('api_key'), false);
+    assert.equal(url.searchParams.get('VideoCodec'), 'hevc');
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
diff --git a/src/core/services/jellyfin.ts b/src/core/services/jellyfin.ts
index a09577e6..2d421287 100644
--- a/src/core/services/jellyfin.ts
+++ b/src/core/services/jellyfin.ts
@@ -136,6 +136,27 @@ function getErrorMessage(error: unknown): string {
   return String(error || 'unknown error');
 }
 
+// Jellyfin reads query keys case-insensitively and older servers embed the token as
+// `api_key` in the URLs they hand back, so drop every spelling before setting the one
+// form Jellyfin 12 still accepts with legacy authorization disabled.
+function setApiKeyParam(url: URL, accessToken: string): void {
+  for (const key of [...url.searchParams.keys()]) {
+    if (/^api_?key$/i.test(key)) url.searchParams.delete(key);
+  }
+  url.searchParams.set('ApiKey', accessToken);
+}
+
+const IMAGE_SUBTITLE_CODECS = new Set([
+  'pgssub',
+  'pgs',
+  'hdmv_pgs_subtitle',
+  'dvdsub',
+  'dvd_subtitle',
+  'dvbsub',
+  'dvb_subtitle',
+  'xsub',
+]);
+
 function resolveDeliveryUrl(
   session: JellyfinAuthSession,
   stream: JellyfinMediaStream,
@@ -146,15 +167,15 @@ function resolveDeliveryUrl(
   if (deliveryUrl) {
     if (stream.IsExternalUrl === true) return deliveryUrl;
     const resolved = new URL(deliveryUrl, `${session.serverUrl}/`);
-    if (!resolved.searchParams.has('api_key')) {
-      resolved.searchParams.set('api_key', session.accessToken);
-    }
+    setApiKeyParam(resolved, session.accessToken);
     return resolved.toString();
   }
 
   const streamIndex = asIntegerOrNull(stream.Index);
   if (streamIndex === null || !itemId || !mediaSourceId) return null;
   const codec = ensureString(stream.Codec).toLowerCase();
+  // Jellyfin cannot convert bitmap subtitles to text, so requesting them always fails.
+  if (IMAGE_SUBTITLE_CODECS.has(codec)) return null;
   const ext =
     codec === 'subrip'
       ? 'srt'
@@ -171,9 +192,7 @@ function resolveDeliveryUrl(
     `/Videos/${encodeURIComponent(itemId)}/${encodeURIComponent(mediaSourceId)}/Subtitles/${streamIndex}/Stream.${ext}`,
     `${session.serverUrl}/`,
   );
-  if (!fallback.searchParams.has('api_key')) {
-    fallback.searchParams.set('api_key', session.accessToken);
-  }
+  setApiKeyParam(fallback, session.accessToken);
   return fallback.toString();
 }
 
@@ -197,7 +216,6 @@ async function jellyfinRequestJson<T>(
   const headers = new Headers(init.headers ?? {});
   headers.set('Content-Type', 'application/json');
   headers.set('Authorization', createAuthorizationHeader(client, session.accessToken));
-  headers.set('X-Emby-Token', session.accessToken);
 
   const response = await fetch(`${session.serverUrl}${path}`, {
     ...init,
@@ -221,7 +239,7 @@ function createDirectPlayUrl(
 ): string {
   const query = new URLSearchParams({
     static: 'true',
-    api_key: session.accessToken,
+    ApiKey: session.accessToken,
     MediaSourceId: ensureString(mediaSource.Id),
   });
   if (mediaSource.LiveStreamId) {
@@ -245,9 +263,7 @@ function createTranscodeUrl(
 ): string {
   if (mediaSource.TranscodingUrl) {
     const url = new URL(`${session.serverUrl}${mediaSource.TranscodingUrl}`);
-    if (!url.searchParams.has('api_key')) {
-      url.searchParams.set('api_key', session.accessToken);
-    }
+    setApiKeyParam(url, session.accessToken);
     if (!url.searchParams.has('AudioStreamIndex') && plan.audioStreamIndex !== null) {
       url.searchParams.set('AudioStreamIndex', String(plan.audioStreamIndex));
     }
@@ -261,7 +277,7 @@ function createTranscodeUrl(
   }
 
   const query = new URLSearchParams({
-    api_key: session.accessToken,
+    ApiKey: session.accessToken,
     MediaSourceId: ensureString(mediaSource.Id),
     VideoCodec: ensureString(config.transcodeVideoCodec, 'h264'),
     TranscodingContainer: 'ts',
diff --git a/src/core/services/media-timing-frame.test.ts b/src/core/services/media-timing-frame.test.ts
new file mode 100644
index 00000000..8818ec10
--- /dev/null
+++ b/src/core/services/media-timing-frame.test.ts
@@ -0,0 +1,70 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { createMediaTimingFrameExtractor, selectMediaTimingFrame } from './media-timing-frame';
+
+test('frame stepping follows decoded timestamps with variable frame durations', () => {
+  const times = [10, 10.041667, 10.125, 10.166667];
+  assert.equal(selectMediaTimingFrame(times, 10.05), 10.125);
+  assert.equal(selectMediaTimingFrame(times, 10.125 - 0.000001, 1), 10.166667);
+  assert.equal(selectMediaTimingFrame(times, 10.125 - 0.000001, -1), 10.041667);
+  assert.equal(selectMediaTimingFrame(times, 10, -1), undefined);
+  assert.equal(selectMediaTimingFrame(times, 10.166667, 1), undefined);
+  assert.equal(selectMediaTimingFrame([], 10), undefined);
+});
+
+function fixture(startTime = 0) {
+  const calls: Array<{ file: string; args: string[] }> = [];
+  const extractor = createMediaTimingFrameExtractor(async (file, args) => {
+    calls.push({ file, args });
+    if (file === 'ffmpeg') return Buffer.from('image');
+    if (args.includes('format=start_time'))
+      return Buffer.from(JSON.stringify({ format: { start_time: String(startTime) } }));
+    return Buffer.from(
+      JSON.stringify({
+        frames: [10, 10.04, 10.12, 10.16].map((time) => ({
+          best_effort_timestamp_time: String(time + startTime),
+        })),
+      }),
+    );
+  });
+  return { calls, extractor };
+}
+
+test('frame extraction normalizes nonzero source start times and reuses the frame index', async () => {
+  const { calls, extractor } = fixture(5);
+  const first = await extractor.generate({ media: '/movie.mkv', timestamp: 10.05 });
+  assert.ok(Math.abs(first.timestamp - 10.119999) < 0.000001);
+  assert.equal(first.dataUrl, 'data:image/jpeg;base64,aW1hZ2U=');
+  await extractor.generate({ media: '/movie.mkv', timestamp: first.timestamp, direction: 1 });
+  assert.equal(calls.filter((call) => call.file === 'ffprobe').length, 2);
+  assert.ok(calls[1]!.args.includes('13.05%17.05'));
+  extractor.clear();
+  await extractor.generate({ media: '/movie.mkv', timestamp: 10.05 });
+  assert.equal(calls.filter((call) => call.file === 'ffprobe').length, 4);
+});
+
+test('cached windows keep source timestamps for ffmpeg and use absolute ffprobe intervals', async () => {
+  const { calls, extractor } = fixture();
+  await extractor.generate({
+    media: { path: '/window.mkv', absoluteTimestamps: true },
+    timestamp: 10.05,
+  });
+  assert.ok(calls[1]!.args.includes('8.05%12.05'));
+  assert.equal(calls[1]!.args.includes('-seek_timestamp'), false);
+  assert.ok(calls[2]!.args.includes('-seek_timestamp'));
+});
+
+test('remote frame reads carry source headers and do not silently reuse a different input', async () => {
+  const { calls, extractor } = fixture();
+  const media = {
+    path: 'https://example.test/video',
+    inputOptions: { headers: { 'X-Emby-Token': 'test-token' } },
+  };
+  await extractor.generate({ media, timestamp: 10.05 });
+  assert.ok(calls.every((call) => call.args.includes('X-Emby-Token: test-token\r\n')));
+  await extractor.generate({
+    media: { ...media, path: 'https://example.test/other' },
+    timestamp: 10.05,
+  });
+  assert.equal(calls.filter((call) => call.file === 'ffprobe').length, 4);
+});
diff --git a/src/core/services/media-timing-frame.ts b/src/core/services/media-timing-frame.ts
new file mode 100644
index 00000000..9c9e0a11
--- /dev/null
+++ b/src/core/services/media-timing-frame.ts
@@ -0,0 +1,159 @@
+import { execFile } from 'node:child_process';
+import { normalizeMediaInput, type MediaInput } from '../../media-input';
+
+export interface MediaTimingFrameOptions {
+  media: MediaInput;
+  timestamp: number;
+  direction?: -1 | 1;
+}
+
+const FRAME_EPSILON = 0.00001;
+const PROBE_RADIUS_SECONDS = 2;
+
+function run(file: string, args: string[]): Promise<Buffer> {
+  return new Promise((resolve, reject) => {
+    execFile(
+      file,
+      args,
+      { encoding: 'buffer', timeout: 30_000, maxBuffer: 8 * 1024 * 1024, windowsHide: true },
+      (error, stdout) => {
+        // Child-process errors contain the input URL, which may contain authentication tokens.
+        if (error)
+          reject(
+            new Error('Screenshot preview is unavailable. Check FFmpeg and the video source.'),
+          );
+        else resolve(stdout);
+      },
+    );
+  });
+}
+
+/** Uses decoded timestamps, rather than an assumed FPS, including for variable-rate video. */
+export function selectMediaTimingFrame(
+  times: readonly number[],
+  timestamp: number,
+  direction?: -1 | 1,
+): number | undefined {
+  if (direction === -1)
+    return [...times].reverse().find((time) => time < timestamp - FRAME_EPSILON);
+  if (direction === 1) return times.find((time) => time > timestamp + FRAME_EPSILON);
+  return times.find((time) => time >= timestamp - FRAME_EPSILON) ?? times.at(-1);
+}
+
+export function createMediaTimingFrameExtractor(execute: typeof run = run) {
+  let cached: { key: string; start: number; end: number; times: number[] } | null = null;
+  let source: { key: string; offset: number } | null = null;
+  let generation = 0;
+
+  async function generate(
+    options: MediaTimingFrameOptions,
+  ): Promise<{ dataUrl: string; timestamp: number }> {
+    const input = normalizeMediaInput(options.media);
+    const key = JSON.stringify(options.media);
+    const currentGeneration = generation;
+    const absolute = typeof options.media !== 'string' && options.media.absoluteTimestamps;
+    // -seek_timestamp is an ffmpeg option; ffprobe intervals already use stream timestamps.
+    const probeInputArgs = normalizeMediaInput({
+      path: input.path,
+      ...(typeof options.media !== 'string' ? { inputOptions: options.media.inputOptions } : {}),
+    }).inputArgs;
+    let offset = source?.key === key ? source.offset : undefined;
+    if (offset === undefined) {
+      const metadata = JSON.parse(
+        (
+          await execute('ffprobe', [
+            '-v',
+            'error',
+            ...probeInputArgs,
+            '-show_entries',
+            'format=start_time',
+            '-of',
+            'json',
+            input.path,
+          ])
+        ).toString(),
+      ) as { format?: { start_time?: string } };
+      const start = Number(metadata.format?.start_time ?? 0);
+      offset = absolute || !Number.isFinite(start) ? 0 : start;
+      if (generation === currentGeneration) source = { key, offset };
+    }
+    let times: number[];
+    if (
+      cached?.key === key &&
+      options.timestamp > cached.start + 0.5 &&
+      options.timestamp < cached.end - 0.5
+    ) {
+      times = cached.times;
+    } else {
+      const start = Math.max(0, options.timestamp - PROBE_RADIUS_SECONDS);
+      const end = options.timestamp + PROBE_RADIUS_SECONDS;
+      const result = JSON.parse(
+        (
+          await execute('ffprobe', [
+            '-v',
+            'error',
+            ...probeInputArgs,
+            '-read_intervals',
+            `${start + offset}%${end + offset}`,
+            '-select_streams',
+            'v:0',
+            '-show_entries',
+            'frame=best_effort_timestamp_time',
+            '-of',
+            'json',
+            input.path,
+          ])
+        ).toString(),
+      ) as { frames?: { best_effort_timestamp_time?: string }[] };
+      times = [
+        ...new Set(
+          (result.frames ?? [])
+            .map((frame) => Number(frame.best_effort_timestamp_time) - offset)
+            .filter((time) => Number.isFinite(time) && time >= 0 && time >= start && time <= end),
+        ),
+      ].sort((a, b) => a - b);
+      if (generation === currentGeneration) cached = { key, start, end, times };
+    }
+    const timestamp = selectMediaTimingFrame(times, options.timestamp, options.direction);
+    if (timestamp === undefined) throw new Error('No adjacent video frame is available here.');
+    // Round down by one microsecond so decimal timestamp rounding cannot skip the chosen frame.
+    const seekTime = Math.max(0, timestamp - 0.000001);
+    const image = await execute('ffmpeg', [
+      '-hide_banner',
+      '-nostdin',
+      '-loglevel',
+      'error',
+      '-ss',
+      String(seekTime),
+      ...input.inputArgs,
+      '-i',
+      input.path,
+      '-map',
+      '0:v:0',
+      '-frames:v',
+      '1',
+      '-an',
+      '-sn',
+      '-vf',
+      'scale=w=640:h=360:force_original_aspect_ratio=decrease',
+      '-c:v',
+      'mjpeg',
+      '-q:v',
+      '3',
+      '-f',
+      'image2pipe',
+      'pipe:1',
+    ]);
+    if (!image.length) throw new Error('No video frame is available here.');
+    return { dataUrl: `data:image/jpeg;base64,${image.toString('base64')}`, timestamp: seekTime };
+  }
+
+  return {
+    generate,
+    clear: () => {
+      generation += 1;
+      cached = null;
+      source = null;
+    },
+  };
+}
diff --git a/src/core/services/media-timing-preview.test.ts b/src/core/services/media-timing-preview.test.ts
new file mode 100644
index 00000000..c13cb61d
--- /dev/null
+++ b/src/core/services/media-timing-preview.test.ts
@@ -0,0 +1,291 @@
+import assert from 'node:assert/strict';
+import { EventEmitter } from 'node:events';
+import net from 'node:net';
+import { describe, test } from 'node:test';
+import { buildMediaTimingPreviewArgs, MediaTimingPreviewSession } from './media-timing-preview';
+
+describe('buildMediaTimingPreviewArgs', () => {
+  test('creates a hidden audio-only reusable mpv session', () => {
+    const args = buildMediaTimingPreviewArgs('/tmp/review.sock', {
+      mediaPath: '/video/show.mkv',
+      audioTrackId: 3,
+      volume: 55,
+    });
+
+    assert.ok(args.includes('--no-video'));
+    assert.ok(args.includes('--force-window=no'));
+    assert.ok(args.includes('--idle=yes'));
+    assert.ok(args.includes('--pause=yes'));
+    assert.ok(args.includes('--input-ipc-server=/tmp/review.sock'));
+    assert.ok(args.includes('--aid=3'));
+    assert.ok(args.includes('--volume=55'));
+    assert.equal(args.at(-2), '--');
+    assert.equal(args.at(-1), '/video/show.mkv');
+  });
+
+  test('keeps source timestamps for cached remote windows', () => {
+    const args = buildMediaTimingPreviewArgs('/tmp/review.sock', {
+      mediaPath: '/tmp/window.mkv',
+      absoluteTimestamps: true,
+    });
+
+    assert.ok(args.includes('--rebase-start-time=no'));
+    assert.equal(
+      buildMediaTimingPreviewArgs('/tmp/review.sock', { mediaPath: '/video/show.mkv' }).includes(
+        '--rebase-start-time=no',
+      ),
+      false,
+    );
+  });
+
+  test('separates an option-like media path without adding optional audio arguments', () => {
+    const args = buildMediaTimingPreviewArgs('/tmp/review.sock', {
+      mediaPath: '--fullscreen',
+    });
+
+    assert.equal(args.at(-2), '--');
+    assert.equal(args.at(-1), '--fullscreen');
+    assert.equal(
+      args.some((arg) => arg.startsWith('--aid=')),
+      false,
+    );
+    assert.equal(
+      args.some((arg) => arg.startsWith('--volume=')),
+      false,
+    );
+  });
+});
+
+test('preview session handles socket errors after connecting', async () => {
+  const socket = new net.Socket();
+  const child = new EventEmitter() as EventEmitter & { kill: () => boolean };
+  child.kill = () => true;
+  const session = new MediaTimingPreviewSession({
+    platform: 'linux',
+    spawnProcess: () => child as never,
+    connectSocket: () => {
+      queueMicrotask(() => socket.emit('connect'));
+      return socket;
+    },
+    removeSocketFile: () => undefined,
+    createSocketPath: () => '/tmp/review.sock',
+  });
+
+  await session.start({ mediaPath: '/video/show.mkv' });
+  assert.doesNotThrow(() => socket.emit('error', new Error('pipe closed')));
+  await assert.rejects(session.play(1, 2), /not ready/);
+  session.dispose();
+});
+
+test('preview session keeps failed connection errors handled through destruction', async () => {
+  const socket = new EventEmitter() as EventEmitter & {
+    destroy: () => void;
+  };
+  socket.destroy = () => {
+    socket.emit('error', new Error('socket failed again while closing'));
+  };
+  const child = new EventEmitter() as EventEmitter & { kill: () => boolean };
+  child.kill = () => true;
+  const times = [0, 0, 0, 6_000];
+  const session = new MediaTimingPreviewSession({
+    platform: 'linux',
+    spawnProcess: () => child as never,
+    connectSocket: () => {
+      queueMicrotask(() => socket.emit('error', new Error('connection failed')));
+      return socket as never;
+    },
+    now: () => times.shift() ?? 6_000,
+    removeSocketFile: () => undefined,
+    createSocketPath: () => '/tmp/review.sock',
+  });
+
+  await assert.rejects(session.start({ mediaPath: '/video/show.mkv' }), /Timed out starting/);
+});
+
+test('preview session rejects a connection that finishes after disposal', async () => {
+  const socket = new net.Socket();
+  const child = new EventEmitter() as EventEmitter & { kill: () => boolean };
+  child.kill = () => true;
+  const session = new MediaTimingPreviewSession({
+    platform: 'linux',
+    spawnProcess: () => child as never,
+    connectSocket: () => socket,
+    removeSocketFile: () => undefined,
+    createSocketPath: () => '/tmp/review.sock',
+  });
+
+  const pendingStart = session.start({ mediaPath: '-playlist' });
+  session.dispose();
+  socket.emit('connect');
+
+  await assert.rejects(pendingStart, /closed/);
+  assert.equal(socket.destroyed, true);
+});
+
+test('preview session shares one startup across concurrent start calls', async () => {
+  const socket = new net.Socket();
+  const child = new EventEmitter() as EventEmitter & { kill: () => boolean };
+  child.kill = () => true;
+  let spawnCount = 0;
+  const session = new MediaTimingPreviewSession({
+    platform: 'linux',
+    spawnProcess: () => {
+      spawnCount += 1;
+      return child as never;
+    },
+    connectSocket: () => socket,
+    removeSocketFile: () => undefined,
+    createSocketPath: () => '/tmp/review.sock',
+  });
+
+  const firstStart = session.start({ mediaPath: '/video/show.mkv' });
+  const secondStart = session.start({ mediaPath: '/video/show.mkv' });
+  socket.emit('connect');
+
+  await Promise.all([firstStart, secondStart]);
+  assert.equal(spawnCount, 1);
+  session.dispose();
+});
+
+test('preview session can start again after a startup failure', async () => {
+  const socket = new net.Socket();
+  const child = new EventEmitter() as EventEmitter & { kill: () => boolean };
+  child.kill = () => true;
+  let spawnCount = 0;
+  const session = new MediaTimingPreviewSession({
+    platform: 'linux',
+    spawnProcess: () => {
+      spawnCount += 1;
+      if (spawnCount === 1) throw new Error('spawn failed');
+      return child as never;
+    },
+    connectSocket: () => {
+      queueMicrotask(() => socket.emit('connect'));
+      return socket;
+    },
+    removeSocketFile: () => undefined,
+    createSocketPath: () => '/tmp/review.sock',
+  });
+
+  await assert.rejects(session.start({ mediaPath: '/video/show.mkv' }), /spawn failed/);
+  await session.start({ mediaPath: '/video/show.mkv' });
+  assert.equal(spawnCount, 2);
+  session.dispose();
+});
+
+test('preview session bounds a connection attempt that never settles', async () => {
+  const child = new EventEmitter() as EventEmitter & { kill: () => boolean };
+  child.kill = () => true;
+  let nowMs = 0;
+  let connectAttempts = 0;
+  const session = new MediaTimingPreviewSession({
+    platform: 'linux',
+    spawnProcess: () => child as never,
+    connectSocket: () => {
+      connectAttempts += 1;
+      const socket = new net.Socket();
+      socket.destroy = (() => {
+        socket.emit('error', new Error('socket failed while timing out'));
+        return socket;
+      }) as typeof socket.destroy;
+      return socket;
+    },
+    now: () => {
+      const current = nowMs;
+      nowMs += 1_000;
+      return current;
+    },
+    schedule: (callback) => setTimeout(callback, 0),
+    cancelSchedule: (timeout) => clearTimeout(timeout),
+    removeSocketFile: () => undefined,
+    createSocketPath: () => '/tmp/review.sock',
+  });
+
+  await assert.rejects(session.start({ mediaPath: '/video/show.mkv' }), /Timed out starting/);
+  assert.equal(connectAttempts, 1);
+});
+
+function createFakeSocket() {
+  const socket = new EventEmitter() as EventEmitter & {
+    destroyed: boolean;
+    write: (data: string) => boolean;
+    end: () => void;
+    destroy: () => void;
+    off: EventEmitter['off'];
+  };
+  const writes: string[] = [];
+  socket.destroyed = false;
+  socket.write = (data) => {
+    writes.push(data);
+    return true;
+  };
+  socket.end = () => undefined;
+  socket.destroy = () => {
+    socket.destroyed = true;
+  };
+  return { socket, writes };
+}
+
+test('preview session plays once to the clip end and reports when mpv has drained it', async () => {
+  const { socket, writes } = createFakeSocket();
+  const child = new EventEmitter() as EventEmitter & { kill: () => boolean };
+  child.kill = () => true;
+  const session = new MediaTimingPreviewSession({
+    platform: 'linux',
+    spawnProcess: () => child as never,
+    connectSocket: () => {
+      queueMicrotask(() => socket.emit('connect'));
+      return socket as never;
+    },
+    removeSocketFile: () => undefined,
+    createSocketPath: () => '/tmp/review.sock',
+  });
+  let endedCount = 0;
+  session.onPlaybackEnded(() => {
+    endedCount += 1;
+  });
+  const property = (name: string, data: boolean): string =>
+    `${JSON.stringify({ event: 'property-change', name, data })}\n`;
+
+  await session.start({ mediaPath: '/video/show.mkv' });
+  assert.deepEqual(
+    writes.map((line) => JSON.parse(line).command),
+    [
+      ['observe_property', 1, 'eof-reached'],
+      ['observe_property', 2, 'pause'],
+    ],
+  );
+  // The observers' initial replies describe the idle paused player, not a finished preview.
+  socket.emit('data', property('eof-reached', false) + property('pause', true));
+  assert.equal(endedCount, 0);
+
+  writes.length = 0;
+  await session.play(12.25, 14.5);
+  assert.deepEqual(
+    writes.map((line) => JSON.parse(line).command),
+    [
+      ['set_property', 'pause', true],
+      ['seek', 12.25, 'absolute+exact'],
+      ['set_property', 'end', '14.500'],
+      ['set_property', 'pause', false],
+    ],
+  );
+
+  // Events may arrive split across chunks. The decoder passing `end` flips eof-reached while
+  // audio still drains; only the keep-open pause that follows marks the preview as finished.
+  socket.emit('data', property('eof-reached', false) + property('pause', false).slice(0, 20));
+  socket.emit('data', property('pause', false).slice(20) + property('eof-reached', true));
+  assert.equal(endedCount, 0);
+  socket.emit('data', property('pause', true));
+  assert.equal(endedCount, 1);
+  socket.emit('data', property('pause', true));
+  assert.equal(endedCount, 1);
+
+  // Stopping early pauses without an end signal, and a later real EOF is not a preview end.
+  await session.play(1, 2);
+  socket.emit('data', property('eof-reached', false) + property('pause', false));
+  await session.stop();
+  socket.emit('data', property('pause', true) + property('eof-reached', true));
+  assert.equal(endedCount, 1);
+  session.dispose();
+});
diff --git a/src/core/services/media-timing-preview.ts b/src/core/services/media-timing-preview.ts
new file mode 100644
index 00000000..60f60863
--- /dev/null
+++ b/src/core/services/media-timing-preview.ts
@@ -0,0 +1,394 @@
+import { spawn, type ChildProcess } from 'child_process';
+import fs from 'fs';
+import net, { type Socket } from 'net';
+import os from 'os';
+import path from 'path';
+import { randomUUID } from 'crypto';
+
+const CONNECT_TIMEOUT_MS = 5_000;
+const CONNECT_ATTEMPT_TIMEOUT_MS = 500;
+const CONNECT_RETRY_MS = 40;
+/**
+ * mpv flips eof-reached as soon as the decoder passes `end`, while its audio buffer is still
+ * draining; keep-open then pauses once the buffer has played out. A preview has ended when
+ * both have happened.
+ */
+const EOF_OBSERVER_ID = 1;
+const PAUSE_OBSERVER_ID = 2;
+
+export interface MediaTimingPreviewStartOptions {
+  mediaPath: string;
+  executablePath?: string;
+  audioTrackId?: number;
+  volume?: number;
+  /** The file keeps source timestamps (a cached remote window); seek with the original times. */
+  absoluteTimestamps?: boolean;
+}
+
+type PreviewProcess = Pick<ChildProcess, 'kill' | 'once'>;
+
+interface MediaTimingPreviewDeps {
+  platform: NodeJS.Platform;
+  spawnProcess: (command: string, args: string[]) => PreviewProcess;
+  connectSocket: (socketPath: string) => Socket;
+  now: () => number;
+  schedule: (callback: () => void, delayMs: number) => ReturnType<typeof setTimeout>;
+  cancelSchedule: (timeout: ReturnType<typeof setTimeout>) => void;
+  removeSocketFile: (socketPath: string) => void;
+  createSocketPath: () => string;
+}
+
+export function buildMediaTimingPreviewArgs(
+  socketPath: string,
+  options: MediaTimingPreviewStartOptions,
+): string[] {
+  const args = [
+    '--no-config',
+    '--no-video',
+    '--audio-display=no',
+    '--force-window=no',
+    '--idle=yes',
+    '--keep-open=yes',
+    '--pause=yes',
+    '--terminal=no',
+    '--msg-level=all=warn',
+    `--input-ipc-server=${socketPath}`,
+  ];
+  if (typeof options.audioTrackId === 'number' && Number.isInteger(options.audioTrackId)) {
+    args.push(`--aid=${options.audioTrackId}`);
+  }
+  if (typeof options.volume === 'number' && Number.isFinite(options.volume)) {
+    args.push(`--volume=${Math.max(0, options.volume)}`);
+  }
+  if (options.absoluteTimestamps) {
+    args.push('--rebase-start-time=no');
+  }
+  args.push('--', options.mediaPath);
+  return args;
+}
+
+function createDefaultSocketPath(): string {
+  const suffix = `${process.pid}-${randomUUID()}`;
+  return process.platform === 'win32'
+    ? `\\\\.\\pipe\\subminer-timing-preview-${suffix}`
+    : path.join(
+        // macOS limits Unix socket paths to 104 bytes, while its temp directory can be long.
+        process.platform === 'darwin' ? '/tmp' : os.tmpdir(),
+        `subminer-timing-preview-${suffix}.sock`,
+      );
+}
+
+function removePosixSocketFile(socketPath: string): void {
+  if (process.platform === 'win32') return;
+  try {
+    fs.unlinkSync(socketPath);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== 'ENOENT') {
+      throw error;
+    }
+  }
+}
+
+export class MediaTimingPreviewSession {
+  private readonly deps: MediaTimingPreviewDeps;
+  private socketPath: string | null = null;
+  private socket: Socket | null = null;
+  private process: PreviewProcess | null = null;
+  private startupError: Error | null = null;
+  private startPromise: Promise<void> | null = null;
+  private retryWait: {
+    timeout: ReturnType<typeof setTimeout>;
+    resolve: () => void;
+  } | null = null;
+  private disposed = false;
+  private readBuffer = '';
+  private playing = false;
+  private eofReached = false;
+  private paused = true;
+  private readonly endedListeners = new Set<() => void>();
+
+  constructor(deps: Partial<MediaTimingPreviewDeps> = {}) {
+    this.deps = {
+      platform: process.platform,
+      spawnProcess: (command, args) => spawn(command, args, { stdio: 'ignore' }),
+      connectSocket: (socketPath) => net.createConnection(socketPath),
+      now: Date.now,
+      schedule: (callback, delayMs) => setTimeout(callback, delayMs),
+      cancelSchedule: (timeout) => clearTimeout(timeout),
+      removeSocketFile: removePosixSocketFile,
+      createSocketPath: createDefaultSocketPath,
+      ...deps,
+    };
+  }
+
+  async start(options: MediaTimingPreviewStartOptions): Promise<void> {
+    if (this.disposed) throw new Error('Preview session is closed');
+    if (this.socket) return;
+    if (this.startPromise) return await this.startPromise;
+
+    const startPromise = this.startOnce(options);
+    this.startPromise = startPromise;
+    try {
+      await startPromise;
+    } catch (error) {
+      this.releaseResources();
+      throw error;
+    } finally {
+      if (this.startPromise === startPromise) this.startPromise = null;
+    }
+  }
+
+  private async startOnce(options: MediaTimingPreviewStartOptions): Promise<void> {
+    const mediaPath = options.mediaPath.trim();
+    if (!mediaPath) throw new Error('No media source is available for preview');
+
+    const socketPath = this.deps.createSocketPath();
+    this.socketPath = socketPath;
+    if (this.deps.platform !== 'win32') {
+      this.deps.removeSocketFile(socketPath);
+    }
+
+    const command = options.executablePath?.trim() || 'mpv';
+    this.startupError = null;
+    const child = this.deps.spawnProcess(
+      command,
+      buildMediaTimingPreviewArgs(socketPath, { ...options, mediaPath }),
+    );
+    this.process = child;
+    child.once('error', (error) => {
+      if (this.process !== child) return;
+      this.startupError = error;
+    });
+    child.once('exit', () => {
+      if (this.process !== child) return;
+      if (!this.socket && !this.disposed && !this.startupError) {
+        this.startupError = new Error('The hidden mpv preview player exited during startup');
+      }
+      this.socket?.destroy();
+      this.socket = null;
+      this.process = null;
+    });
+
+    await this.connectWithRetry(socketPath);
+  }
+
+  /**
+   * Plays [startTime, endTime) once. mpv stops itself at `end` and, thanks to keep-open,
+   * pauses after draining the audio device, so the listener hears the whole clip even on
+   * high-latency outputs. onPlaybackEnded fires when mpv reports the end was reached.
+   */
+  async play(startTime: number, endTime: number): Promise<void> {
+    if (!this.socket || this.socket.destroyed) {
+      throw new Error('Preview player is not ready');
+    }
+    if (!Number.isFinite(startTime) || !Number.isFinite(endTime) || endTime <= startTime) {
+      throw new Error('Preview timing is invalid');
+    }
+
+    this.playing = false;
+    this.send(['set_property', 'pause', true]);
+    this.send(['seek', startTime, 'absolute+exact']);
+    // The option parser wants a time string; a raw JSON number is not accepted for `end`.
+    this.send(['set_property', 'end', endTime.toFixed(3)]);
+    this.send(['set_property', 'pause', false]);
+    // Only the seek's eof-reached=false and the later keep-open pause count for this play.
+    this.eofReached = false;
+    this.paused = false;
+    this.playing = true;
+  }
+
+  async stop(): Promise<void> {
+    this.playing = false;
+    if (!this.socket || this.socket.destroyed) return;
+    this.send(['set_property', 'pause', true]);
+  }
+
+  onPlaybackEnded(listener: () => void): void {
+    this.endedListeners.add(listener);
+  }
+
+  private finishPlayback(): void {
+    if (!this.playing) return;
+    this.playing = false;
+    for (const listener of this.endedListeners) listener();
+  }
+
+  private handleSocketData(chunk: Buffer | string): void {
+    this.readBuffer += chunk.toString();
+    let newline = this.readBuffer.indexOf('\n');
+    while (newline !== -1) {
+      const line = this.readBuffer.slice(0, newline).trim();
+      this.readBuffer = this.readBuffer.slice(newline + 1);
+      newline = this.readBuffer.indexOf('\n');
+      if (!line) continue;
+      let message: unknown;
+      try {
+        message = JSON.parse(line);
+      } catch {
+        continue;
+      }
+      if (
+        typeof message === 'object' &&
+        message !== null &&
+        'event' in message &&
+        message.event === 'property-change' &&
+        'name' in message &&
+        'data' in message
+      ) {
+        this.handlePropertyChange(message.name, message.data);
+      }
+    }
+  }
+
+  private handlePropertyChange(name: unknown, data: unknown): void {
+    if (name === 'eof-reached') this.eofReached = data === true;
+    else if (name === 'pause') this.paused = data === true;
+    else return;
+    if (this.playing && this.eofReached && this.paused) this.finishPlayback();
+  }
+
+  dispose(): void {
+    if (this.disposed) return;
+    this.disposed = true;
+    this.releaseResources();
+  }
+
+  private releaseResources(): void {
+    this.cancelRetryWait();
+    try {
+      this.send(['quit']);
+    } catch {
+      // The process may already have exited.
+    }
+    this.socket?.end();
+    this.socket?.destroy();
+    this.socket = null;
+    const child = this.process;
+    this.process = null;
+    child?.kill();
+    if (this.socketPath && this.deps.platform !== 'win32') {
+      try {
+        this.deps.removeSocketFile(this.socketPath);
+      } catch {
+        // mpv may still be releasing the socket. The OS temp directory owns cleanup.
+      }
+    }
+    this.socketPath = null;
+  }
+
+  private send(command: Array<string | number | boolean>): void {
+    if (!this.socket || this.socket.destroyed) {
+      throw new Error('Preview player is not connected');
+    }
+    this.socket.write(`${JSON.stringify({ command })}\n`);
+  }
+
+  private async connectWithRetry(socketPath: string): Promise<void> {
+    const deadline = this.deps.now() + CONNECT_TIMEOUT_MS;
+    while (!this.disposed && this.deps.now() < deadline) {
+      if (this.startupError) {
+        throw this.startupError;
+      }
+      try {
+        const remainingMs = deadline - this.deps.now();
+        if (remainingMs <= 0) break;
+        const socket = await this.connectOnce(
+          socketPath,
+          Math.min(CONNECT_ATTEMPT_TIMEOUT_MS, remainingMs),
+        );
+        if (this.disposed) {
+          socket.destroy();
+          throw new Error('Preview session is closed');
+        }
+        this.socket = socket;
+        this.readBuffer = '';
+        socket.on('data', (chunk: Buffer | string) => {
+          if (this.socket === socket) this.handleSocketData(chunk);
+        });
+        socket.once('close', () => this.finishPlayback());
+        this.send(['observe_property', EOF_OBSERVER_ID, 'eof-reached']);
+        this.send(['observe_property', PAUSE_OBSERVER_ID, 'pause']);
+        return;
+      } catch {
+        if (this.disposed) {
+          throw new Error('Preview session is closed');
+        }
+        const remainingMs = deadline - this.deps.now();
+        if (remainingMs <= 0) break;
+        await this.waitForRetry(Math.min(CONNECT_RETRY_MS, remainingMs));
+      }
+    }
+    if (this.startupError) {
+      throw this.startupError;
+    }
+    if (this.disposed) {
+      throw new Error('Preview session is closed');
+    }
+    throw new Error('Timed out starting the hidden mpv preview player');
+  }
+
+  private waitForRetry(delayMs: number): Promise<void> {
+    return new Promise<void>((resolve) => {
+      const timeout = this.deps.schedule(() => {
+        if (this.retryWait?.timeout === timeout) this.retryWait = null;
+        resolve();
+      }, delayMs);
+      this.retryWait = { timeout, resolve };
+    });
+  }
+
+  private cancelRetryWait(): void {
+    const pending = this.retryWait;
+    this.retryWait = null;
+    if (!pending) return;
+    this.deps.cancelSchedule(pending.timeout);
+    pending.resolve();
+  }
+
+  private connectOnce(socketPath: string, timeoutMs: number): Promise<Socket> {
+    return new Promise<Socket>((resolve, reject) => {
+      let timeout: ReturnType<typeof setTimeout> | null = null;
+      let settled = false;
+      const clearAttemptTimeout = (): void => {
+        if (timeout !== null) this.deps.cancelSchedule(timeout);
+        timeout = null;
+      };
+      const socket = this.deps.connectSocket(socketPath);
+      const onConnect = (): void => {
+        if (settled) return;
+        settled = true;
+        clearAttemptTimeout();
+        socket.off('error', onError);
+        socket.on('error', () => {
+          socket.destroy();
+          if (this.socket === socket) this.socket = null;
+        });
+        socket.once('close', () => {
+          if (this.socket === socket) this.socket = null;
+        });
+        resolve(socket);
+      };
+      const onError = (error: Error): void => {
+        if (settled) return;
+        settled = true;
+        clearAttemptTimeout();
+        socket.off('connect', onConnect);
+        socket.on('error', () => {});
+        socket.destroy();
+        reject(error);
+      };
+      socket.once('connect', onConnect);
+      socket.once('error', onError);
+      timeout = this.deps.schedule(() => {
+        if (settled) return;
+        settled = true;
+        timeout = null;
+        socket.off('connect', onConnect);
+        socket.off('error', onError);
+        socket.on('error', () => {});
+        socket.destroy();
+        reject(new Error('Timed out connecting to the hidden mpv preview player'));
+      }, timeoutMs);
+    });
+  }
+}
diff --git a/src/core/services/media-timing-waveform.test.ts b/src/core/services/media-timing-waveform.test.ts
new file mode 100644
index 00000000..3b555eb9
--- /dev/null
+++ b/src/core/services/media-timing-waveform.test.ts
@@ -0,0 +1,125 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import {
+  buildSpeechWaveformArgs,
+  computeWaveformPeaks,
+  generateSpeechWaveform,
+} from './media-timing-waveform';
+
+function pcm(samples: number[]): Buffer {
+  const result = Buffer.alloc(samples.length * 2);
+  samples.forEach((sample, index) => result.writeInt16LE(sample, index * 2));
+  return result;
+}
+
+test('speech waveform maps the selected FFmpeg stream and visible range', () => {
+  const args = buildSpeechWaveformArgs(
+    {
+      mediaPath: '/video/show.mkv',
+      startTime: 8,
+      endTime: 15,
+      audioStreamIndex: 3,
+    },
+    'center',
+  );
+
+  assert.deepEqual(args.slice(args.indexOf('-ss'), args.indexOf('-t') + 2), [
+    '-ss',
+    '8',
+    '-i',
+    '/video/show.mkv',
+    '-t',
+    '7',
+  ]);
+  assert.deepEqual(args.slice(args.indexOf('-map'), args.indexOf('-map') + 2), ['-map', '0:3']);
+  assert.match(args[args.indexOf('-af') + 1] ?? '', /c0=FC/);
+});
+
+test('speech waveform seeks cached windows by source timestamps', () => {
+  const args = buildSpeechWaveformArgs(
+    {
+      mediaPath: { path: '/tmp/window.mkv', absoluteTimestamps: true, singleResolvedStream: true },
+      startTime: 8,
+      endTime: 15,
+    },
+    'downmix',
+  );
+
+  assert.deepEqual(args.slice(args.indexOf('-ss'), args.indexOf('-t') + 2), [
+    '-ss',
+    '8',
+    '-seek_timestamp',
+    '1',
+    '-i',
+    '/tmp/window.mkv',
+    '-t',
+    '7',
+  ]);
+  assert.equal(args.includes('-map'), false);
+});
+
+test('waveform levels rise with loudness and top out at the reference level', () => {
+  const peaks = computeWaveformPeaks(pcm([0, 1_000, -2_000, 4_000, -8_000, 16_000]), 3);
+
+  assert.equal(peaks.length, 3);
+  assert.equal(peaks[0], 0);
+  assert.ok((peaks[1] ?? 0) > 0);
+  assert.ok((peaks[1] ?? 0) < (peaks[2] ?? 0));
+  assert.equal(peaks[2], 1);
+});
+
+test('waveform flattens steady background noise and keeps speech bursts tall', () => {
+  // 20 slices of steady noise at a fixed level with an 18 dB louder "speech" burst in the middle.
+  const noise = 1_000;
+  const samples: number[] = [];
+  for (let slice = 0; slice < 20; slice += 1) {
+    const level = slice >= 8 && slice < 12 ? noise * 8 : noise;
+    for (let sample = 0; sample < 50; sample += 1) {
+      samples.push(sample % 2 === 0 ? level : -level);
+    }
+  }
+
+  const peaks = computeWaveformPeaks(pcm(samples), 20);
+
+  for (const [index, peak] of peaks.entries()) {
+    if (index >= 8 && index < 12) assert.equal(peak, 1);
+    else assert.equal(peak, 0);
+  }
+});
+
+test('waveform stays flat when the whole range is a single steady level', () => {
+  const peaks = computeWaveformPeaks(
+    pcm(Array.from({ length: 400 }, (_, i) => (i % 2 ? 900 : -900))),
+    40,
+  );
+
+  assert.ok(peaks.every((peak) => peak === 0));
+});
+
+test('speech waveform uses a mono downmix when the source has no center activity', async () => {
+  const calls: string[][] = [];
+  const peaks = await generateSpeechWaveform(
+    { mediaPath: '/video/show.mkv', startTime: 0, endTime: 2 },
+    async (args) => {
+      calls.push(args);
+      return calls.length === 1 ? pcm([0, 0, 0, 0]) : pcm([0, 4_000, -8_000, 16_000]);
+    },
+  );
+
+  assert.equal(calls.length, 2);
+  assert.match(calls[1]?.[calls[1].indexOf('-af') + 1] ?? '', /channel_layouts=mono/);
+  assert.equal(Math.max(...peaks), 1);
+});
+
+test('speech waveform keeps an active center channel without doing a second decode', async () => {
+  let calls = 0;
+  await generateSpeechWaveform(
+    { mediaPath: '/video/show.mkv', startTime: 0, endTime: 2 },
+    async () => {
+      calls += 1;
+      return pcm([0, 4_000, -8_000, 16_000]);
+    },
+  );
+
+  assert.equal(calls, 1);
+});
diff --git a/src/core/services/media-timing-waveform.ts b/src/core/services/media-timing-waveform.ts
new file mode 100644
index 00000000..59aa30ad
--- /dev/null
+++ b/src/core/services/media-timing-waveform.ts
@@ -0,0 +1,185 @@
+import { spawn } from 'node:child_process';
+import { normalizeMediaInput, type MediaInput } from '../../media-input';
+
+const WAVEFORM_SAMPLE_RATE = 8_000;
+const WAVEFORM_POINT_COUNT = 480;
+const WAVEFORM_TIMEOUT_MS = 15_000;
+const MAX_WAVEFORM_BYTES = 16 * 1024 * 1024;
+// Keep the band where speech intelligibility lives; bass, drums, and hum sit below it.
+const SPEECH_FILTER = 'highpass=f=250,lowpass=f=3500';
+const NOISE_FLOOR_PERCENTILE = 0.2;
+const REFERENCE_PERCENTILE = 0.95;
+const NOISE_GATE_DB = 3;
+const MIN_DISPLAY_RANGE_DB = 12;
+const SILENCE_DB = -100;
+const CENTER_CHANNEL_FILTER = `pan=mono|c0=FC,${SPEECH_FILTER}`;
+const DOWNMIX_FILTER = `aformat=channel_layouts=mono,${SPEECH_FILTER}`;
+
+export interface SpeechWaveformOptions {
+  mediaPath: MediaInput;
+  startTime: number;
+  endTime: number;
+  audioStreamIndex?: number;
+}
+
+type RunFfmpeg = (args: string[]) => Promise<Buffer>;
+
+export function buildSpeechWaveformArgs(
+  options: SpeechWaveformOptions,
+  mode: 'center' | 'downmix',
+): string[] {
+  const duration = options.endTime - options.startTime;
+  const input = normalizeMediaInput(options.mediaPath);
+  const args = [
+    '-hide_banner',
+    '-nostdin',
+    '-loglevel',
+    'error',
+    '-ss',
+    String(options.startTime),
+    ...input.inputArgs,
+    '-i',
+    input.path,
+    '-t',
+    String(duration),
+  ];
+  if (
+    options.audioStreamIndex !== undefined &&
+    Number.isInteger(options.audioStreamIndex) &&
+    options.audioStreamIndex >= 0
+  ) {
+    args.push('-map', `0:${options.audioStreamIndex}`);
+  }
+  args.push(
+    '-vn',
+    '-sn',
+    '-dn',
+    '-af',
+    mode === 'center' ? CENTER_CHANNEL_FILTER : DOWNMIX_FILTER,
+    '-ac',
+    '1',
+    '-ar',
+    String(WAVEFORM_SAMPLE_RATE),
+    '-f',
+    's16le',
+    'pipe:1',
+  );
+  return args;
+}
+
+function runFfmpeg(args: string[]): Promise<Buffer> {
+  return new Promise((resolve, reject) => {
+    const child = spawn('ffmpeg', args, { stdio: ['ignore', 'pipe', 'pipe'] });
+    const chunks: Buffer[] = [];
+    let byteLength = 0;
+    let stderr = '';
+    let settled = false;
+    const timeout = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      child.kill('SIGKILL');
+      reject(new Error(`FFmpeg waveform analysis timed out after ${WAVEFORM_TIMEOUT_MS}ms`));
+    }, WAVEFORM_TIMEOUT_MS);
+
+    const settle = (callback: () => void): void => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timeout);
+      callback();
+    };
+
+    child.stdout.on('data', (chunk: Buffer) => {
+      if (settled) return;
+      byteLength += chunk.byteLength;
+      if (byteLength > MAX_WAVEFORM_BYTES) {
+        settle(() => {
+          child.kill('SIGKILL');
+          reject(new Error('The visible waveform range is too large to analyze.'));
+        });
+        return;
+      }
+      chunks.push(chunk);
+    });
+    child.stderr.setEncoding('utf8');
+    child.stderr.on('data', (chunk) => {
+      if (stderr.length < 4_000) stderr += String(chunk);
+    });
+    child.once('error', (error) => settle(() => reject(error)));
+    child.once('close', (code) => {
+      settle(() => {
+        if (code === 0) {
+          resolve(Buffer.concat(chunks, byteLength));
+          return;
+        }
+        reject(new Error(stderr.trim() || `FFmpeg exited with status ${code ?? 'unknown'}`));
+      });
+    });
+  });
+}
+
+function percentile(sortedValues: number[], fraction: number): number {
+  const index = Math.min(sortedValues.length - 1, Math.floor(sortedValues.length * fraction));
+  return sortedValues[index] ?? SILENCE_DB;
+}
+
+/**
+ * Turns mono PCM into 0..1 display heights. Each point is the RMS level of its slice in
+ * dB, measured against the clip's own noise floor (a low percentile of the slices), so
+ * constant background noise draws flat and sustained speech stands out. Peak sampling
+ * would instead follow music transients and lift the floor to nearly speech height.
+ */
+export function computeWaveformPeaks(pcm: Buffer, pointCount = WAVEFORM_POINT_COUNT): number[] {
+  const sampleCount = Math.floor(pcm.byteLength / 2);
+  if (sampleCount === 0 || pointCount <= 0) return [];
+  const resolvedPointCount = Math.min(pointCount, sampleCount);
+  const levelsDb = Array.from({ length: resolvedPointCount }, () => SILENCE_DB);
+
+  for (let point = 0; point < resolvedPointCount; point += 1) {
+    const sampleStart = Math.floor((point * sampleCount) / resolvedPointCount);
+    const sampleEnd = Math.max(
+      sampleStart + 1,
+      Math.floor(((point + 1) * sampleCount) / resolvedPointCount),
+    );
+    let energy = 0;
+    for (let sample = sampleStart; sample < sampleEnd; sample += 1) {
+      const value = pcm.readInt16LE(sample * 2) / 32_768;
+      energy += value * value;
+    }
+    const rms = Math.sqrt(energy / (sampleEnd - sampleStart));
+    levelsDb[point] = rms > 0 ? Math.max(SILENCE_DB, 20 * Math.log10(rms)) : SILENCE_DB;
+  }
+
+  const sortedLevels = [...levelsDb].sort((left, right) => left - right);
+  const floorDb = percentile(sortedLevels, NOISE_FLOOR_PERCENTILE) + NOISE_GATE_DB;
+  const referenceDb = Math.max(
+    percentile(sortedLevels, REFERENCE_PERCENTILE),
+    floorDb + MIN_DISPLAY_RANGE_DB,
+  );
+  return levelsDb.map(
+    (levelDb) =>
+      Math.round(Math.min(1, Math.max(0, (levelDb - floorDb) / (referenceDb - floorDb))) * 1_000) /
+      1_000,
+  );
+}
+
+function hasAudibleSamples(pcm: Buffer): boolean {
+  for (let offset = 0; offset + 1 < pcm.byteLength; offset += 2) {
+    if (Math.abs(pcm.readInt16LE(offset)) >= 164) return true;
+  }
+  return false;
+}
+
+export async function generateSpeechWaveform(
+  options: SpeechWaveformOptions,
+  execute: RunFfmpeg = runFfmpeg,
+): Promise<number[]> {
+  try {
+    const centerPcm = await execute(buildSpeechWaveformArgs(options, 'center'));
+    if (hasAudibleSamples(centerPcm)) return computeWaveformPeaks(centerPcm);
+  } catch {
+    // Sources without a named center channel can reject the center-only filter.
+  }
+
+  const downmixPcm = await execute(buildSpeechWaveformArgs(options, 'downmix'));
+  return computeWaveformPeaks(downmixPcm);
+}
diff --git a/src/core/services/mining.test.ts b/src/core/services/mining.test.ts
index a39bca09..5e6ad438 100644
--- a/src/core/services/mining.test.ts
+++ b/src/core/services/mining.test.ts
@@ -244,6 +244,35 @@ test('handleMultiCopyDigit copies available history and reports truncation', ()
   assert.equal(osd.at(-1), 'Only 2 lines available, copied 2');
 });
 
+test('handleMultiCopyDigit copies backward from the current subtitle after a backward seek', () => {
+  const copied: string[] = [];
+  const tracker = new SubtitleTimingTracker();
+
+  try {
+    tracker.recordSubtitle('A', 1, 2);
+    tracker.recordSubtitle('B', 3, 4);
+    tracker.recordSubtitle('C', 5, 6);
+    tracker.recordSubtitle('B', 3, 4);
+
+    const deps = {
+      subtitleTimingTracker: tracker,
+      writeClipboardText: (text: string) => copied.push(text),
+      showMpvOsd: () => {},
+    };
+
+    handleMultiCopyDigit(1, deps);
+    handleMultiCopyDigit(2, deps);
+
+    assert.deepEqual(copied, ['B', 'A\n\nB']);
+    assert.deepEqual(tracker.getRecentEntries(2), [
+      { displayText: 'A', startTime: 1, endTime: 2, secondaryText: undefined },
+      { displayText: 'B', startTime: 3, endTime: 4, secondaryText: undefined },
+    ]);
+  } finally {
+    tracker.destroy();
+  }
+});
+
 test('handleMineSentenceDigit reports async create failures', async () => {
   const osd: string[] = [];
   const logs: Array<{ message: string; err: unknown }> = [];
@@ -344,6 +373,22 @@ test('handleMineSentenceDigit keeps per-entry timings when subtitle text repeats
   }
 });
 
+test('subtitle timing history preserves adjacent repeated text with distinct timings', () => {
+  const tracker = new SubtitleTimingTracker();
+
+  try {
+    tracker.recordSubtitle('same', 1, 2);
+    tracker.recordSubtitle('same', 3, 4);
+
+    assert.deepEqual(tracker.getRecentEntries(2), [
+      { displayText: 'same', startTime: 1, endTime: 2, secondaryText: undefined },
+      { displayText: 'same', startTime: 3, endTime: 4, secondaryText: undefined },
+    ]);
+  } finally {
+    tracker.destroy();
+  }
+});
+
 test('handleMineSentenceDigit joins per-entry secondary subtitles when available', async () => {
   const created: Array<{ sentence: string; secondarySub?: string }> = [];
   const tracker = new SubtitleTimingTracker();
diff --git a/src/core/services/mpv-properties.ts b/src/core/services/mpv-properties.ts
index ae7f2b78..6891872e 100644
--- a/src/core/services/mpv-properties.ts
+++ b/src/core/services/mpv-properties.ts
@@ -1,5 +1,6 @@
 import {
   MPV_REQUEST_ID_AID,
+  MPV_REQUEST_ID_MEDIA_TITLE,
   MPV_REQUEST_ID_OSD_DIMENSIONS,
   MPV_REQUEST_ID_OSD_HEIGHT,
   MPV_REQUEST_ID_PATH,
@@ -85,6 +86,7 @@ const MPV_INITIAL_PROPERTY_REQUESTS: Array<MpvProtocolCommand> = [
   },
   {
     command: ['get_property', 'media-title'],
+    request_id: MPV_REQUEST_ID_MEDIA_TITLE,
   },
   {
     command: ['get_property', 'pause'],
diff --git a/src/core/services/mpv-protocol.test.ts b/src/core/services/mpv-protocol.test.ts
index b92d23ac..a1f0a791 100644
--- a/src/core/services/mpv-protocol.test.ts
+++ b/src/core/services/mpv-protocol.test.ts
@@ -83,6 +83,7 @@ function createDeps(overrides: Partial<MpvProtocolHandleMessageDeps> = {}): {
         state.secondarySubText = text;
       },
       resolvePendingRequest: () => false,
+      shouldEnforceSecondarySubVisibilityHidden: () => true,
       setSecondarySubVisibility: () => {},
       syncCurrentAudioStreamIndex: () => {},
       setCurrentAudioTrackId: () => {},
@@ -198,6 +199,21 @@ test('dispatchMpvProtocolMessage rejects decimal subtitle track IDs', async () =
   assert.deepEqual(state.events, [{ sid: null }, { sid: null }, { sid: null }, { sid: null }]);
 });
 
+test('dispatchMpvProtocolMessage hides native secondary subtitles after a track change', async () => {
+  const visibilityChanges: boolean[] = [];
+  const { deps, state } = createDeps({
+    setSecondarySubVisibility: (visible) => visibilityChanges.push(visible),
+  });
+
+  await dispatchMpvProtocolMessage(
+    { event: 'property-change', name: 'secondary-sid', data: '4' },
+    deps,
+  );
+
+  assert.deepEqual(visibilityChanges, [false]);
+  assert.deepEqual(state.events, [{ sid: 4 }]);
+});
+
 test('dispatchMpvProtocolMessage enforces sub-visibility hidden when overlay suppression is enabled', async () => {
   const { deps, state } = createDeps({
     isVisibleOverlayVisible: () => true,
@@ -239,6 +255,24 @@ test('dispatchMpvProtocolMessage skips sub-visibility suppression when overlay i
   assert.equal(state.commands.length, 0);
 });
 
+test('dispatchMpvProtocolMessage corrects native secondary subtitle visibility', async () => {
+  const visibilityChanges: boolean[] = [];
+  const { deps } = createDeps({
+    setSecondarySubVisibility: (visible) => visibilityChanges.push(visible),
+  });
+
+  await dispatchMpvProtocolMessage(
+    { event: 'property-change', name: 'secondary-sub-visibility', data: 'yes' },
+    deps,
+  );
+  await dispatchMpvProtocolMessage(
+    { event: 'property-change', name: 'secondary-sub-visibility', data: 'no' },
+    deps,
+  );
+
+  assert.deepEqual(visibilityChanges, [false]);
+});
+
 test('dispatchMpvProtocolMessage sets secondary subtitle track based on track list response', async () => {
   const { deps, state } = createDeps();
 
diff --git a/src/core/services/mpv-protocol.ts b/src/core/services/mpv-protocol.ts
index c892a577..da3b1c9a 100644
--- a/src/core/services/mpv-protocol.ts
+++ b/src/core/services/mpv-protocol.ts
@@ -1,4 +1,5 @@
 import { MpvSubtitleRenderMetrics } from '../../types';
+import { sanitizeMediaTitle } from '../../shared/media-identity';
 
 export type MpvMessage = {
   event?: string;
@@ -34,6 +35,7 @@ export const MPV_REQUEST_ID_SUB_USE_MARGINS = 122;
 export const MPV_REQUEST_ID_PAUSE = 123;
 export const MPV_REQUEST_ID_TRACK_LIST_SECONDARY = 200;
 export const MPV_REQUEST_ID_TRACK_LIST_AUDIO = 201;
+export const MPV_REQUEST_ID_MEDIA_TITLE = 202;
 
 export type MpvMessageParser = (message: MpvMessage) => void;
 export type MpvParseErrorHandler = (line: string, error: unknown) => void;
@@ -72,6 +74,7 @@ export interface MpvProtocolHandleMessageDeps {
   emitSubtitleMetricsChange: (payload: Partial<MpvSubtitleRenderMetrics>) => void;
   setCurrentSecondarySubText: (text: string) => void;
   resolvePendingRequest: (requestId: number, message: MpvMessage) => boolean;
+  shouldEnforceSecondarySubVisibilityHidden: () => boolean;
   setSecondarySubVisibility: (visible: boolean) => void;
   syncCurrentAudioStreamIndex: () => void;
   setCurrentAudioTrackId: (value: number | null) => void;
@@ -285,6 +288,9 @@ export async function dispatchMpvProtocolMessage(
             : null;
       deps.emitSubtitleTrackChange({ sid: sid !== null && Number.isInteger(sid) ? sid : null });
     } else if (msg.name === 'secondary-sid') {
+      if (deps.shouldEnforceSecondarySubVisibilityHidden()) {
+        deps.setSecondarySubVisibility(false);
+      }
       const sid =
         typeof msg.data === 'number'
           ? msg.data
@@ -330,12 +336,18 @@ export async function dispatchMpvProtocolMessage(
     } else if (msg.name === 'fullscreen') {
       deps.emitFullscreenChange({ fullscreen: asBoolean(msg.data, false) });
     } else if (msg.name === 'media-title') {
-      deps.emitMediaTitleChange({
-        title: typeof msg.data === 'string' ? msg.data.trim() : null,
-      });
+      applyMediaTitle(deps, msg.data);
     } else if (msg.name === 'path') {
       const path = (msg.data as string) || '';
       deps.setCurrentVideoPath(path);
+      // A forced title set before loadfile arrives ahead of the path change that clears the
+      // cached title and never fires again, so read it back once the new path is known.
+      if (path) {
+        deps.sendCommand({
+          command: ['get_property', 'media-title'],
+          request_id: MPV_REQUEST_ID_MEDIA_TITLE,
+        });
+      }
       deps.emitMediaPathChange({ path });
       deps.autoLoadSecondarySubTrack(path);
       deps.syncCurrentAudioStreamIndex();
@@ -375,6 +387,11 @@ export async function dispatchMpvProtocolMessage(
       if (deps.isVisibleOverlayVisible() && asBoolean(msg.data, false)) {
         deps.sendCommand({ command: ['set_property', 'sub-visibility', false] });
       }
+    } else if (msg.name === 'secondary-sub-visibility') {
+      const visible = parseVisibilityProperty(msg.data);
+      if (deps.shouldEnforceSecondarySubVisibilityHidden() && visible === true) {
+        deps.setSecondarySubVisibility(false);
+      }
     } else if (msg.name === 'sub-use-margins') {
       deps.emitSubtitleMetricsChange({
         subUseMargins: asBoolean(msg.data, deps.getSubtitleMetrics().subUseMargins),
@@ -455,6 +472,8 @@ export async function dispatchMpvProtocolMessage(
       deps.emitSubtitleAssChange({ text: (msg.data as string) || '' });
     } else if (msg.request_id === MPV_REQUEST_ID_PATH) {
       deps.emitMediaPathChange({ path: (msg.data as string) || '' });
+    } else if (msg.request_id === MPV_REQUEST_ID_MEDIA_TITLE) {
+      applyMediaTitle(deps, msg.data);
     } else if (msg.request_id === MPV_REQUEST_ID_AID) {
       deps.setCurrentAudioTrackId(typeof msg.data === 'number' ? (msg.data as number) : null);
       deps.syncCurrentAudioStreamIndex();
@@ -545,6 +564,17 @@ export function asFiniteNumber(value: unknown, fallback: number): number {
   return Number.isFinite(nextValue) ? nextValue : fallback;
 }
 
+// URL-derived titles (mpv falls back to the basename of a query-bearing stream URL) must not
+// replace known metadata, so they are dropped instead of cached.
+function applyMediaTitle(
+  deps: Pick<MpvProtocolHandleMessageDeps, 'emitMediaTitleChange'>,
+  data: unknown,
+): void {
+  const title = typeof data === 'string' ? sanitizeMediaTitle(data) : null;
+  if (typeof data === 'string' && data.trim() && !title) return;
+  deps.emitMediaTitleChange({ title });
+}
+
 export function parseVisibilityProperty(value: unknown): boolean | null {
   if (typeof value === 'boolean') return value;
   if (typeof value !== 'string') return null;
diff --git a/src/core/services/mpv.test.ts b/src/core/services/mpv.test.ts
index 4afb556f..5b14f061 100644
--- a/src/core/services/mpv.test.ts
+++ b/src/core/services/mpv.test.ts
@@ -9,6 +9,7 @@ import {
 } from './mpv';
 import {
   MPV_REQUEST_ID_TRACK_LIST_AUDIO,
+  MPV_REQUEST_ID_MEDIA_TITLE,
   MPV_REQUEST_ID_TRACK_LIST_SECONDARY,
 } from './mpv-protocol';
 
@@ -120,9 +121,30 @@ test('MpvIpcClient emits fullscreen property changes', async () => {
   assert.deepEqual(events, [{ fullscreen: true }]);
 });
 
-test('MpvIpcClient clears cached media title when media path changes', async () => {
+test('MpvIpcClient ignores URL-derived titles without replacing known metadata', async () => {
   const client = new MpvIpcClient('/tmp/mpv.sock', makeDeps());
+  const titles: Array<string | null> = [];
+  client.on('media-title-change', ({ title }) => titles.push(title));
+  for (const data of [
+    'My Anime S01E02',
+    'https://example.com/stream?api_key=test-secret',
+    'stream?api_key=test-secret',
+  ]) {
+    await invokeHandleMessage(client, { event: 'property-change', name: 'media-title', data });
+  }
+  assert.equal(client.currentMediaTitle, 'My Anime S01E02');
+  assert.deepEqual(titles, ['My Anime S01E02']);
+});
 
+test('MpvIpcClient clears cached media title when media path changes and reads it back', async () => {
+  const client = new MpvIpcClient('/tmp/mpv.sock', makeDeps());
+  const commands: Array<{ command?: unknown[]; request_id?: number }> = [];
+  (client as any).send = (command: { command?: unknown[]; request_id?: number }) => {
+    commands.push(command);
+    return true;
+  };
+
+  // A forced title (Jellyfin sets force-media-title before loadfile) arrives before the path.
   await invokeHandleMessage(client, {
     event: 'property-change',
     name: 'media-title',
@@ -133,11 +155,33 @@ test('MpvIpcClient clears cached media title when media path changes', async ()
   await invokeHandleMessage(client, {
     event: 'property-change',
     name: 'path',
-    data: '/tmp/new-episode.mkv',
+    data: 'http://pve-main:8096/Videos/item/stream?static=true&ApiKey=secret',
   });
 
-  assert.equal(client.currentVideoPath, '/tmp/new-episode.mkv');
+  assert.equal(
+    client.currentVideoPath,
+    'http://pve-main:8096/Videos/item/stream?static=true&ApiKey=secret',
+  );
   assert.equal(client.currentMediaTitle, null);
+  const titleRequest = commands.find(
+    (command) => command.command?.[0] === 'get_property' && command.command?.[1] === 'media-title',
+  );
+  assert.equal(titleRequest?.request_id, MPV_REQUEST_ID_MEDIA_TITLE);
+
+  await invokeHandleMessage(client, {
+    request_id: MPV_REQUEST_ID_MEDIA_TITLE,
+    error: 'success',
+    data: '[Jellyfin/direct] Episode 1',
+  });
+  assert.equal(client.currentMediaTitle, '[Jellyfin/direct] Episode 1');
+
+  // A URL-derived read-back must not poison the cache.
+  await invokeHandleMessage(client, {
+    request_id: MPV_REQUEST_ID_MEDIA_TITLE,
+    error: 'success',
+    data: 'stream?static=true&ApiKey=secret',
+  });
+  assert.equal(client.currentMediaTitle, '[Jellyfin/direct] Episode 1');
 });
 
 test('MpvIpcClient skips secondary subtitle autoload when media path is managed', async () => {
@@ -652,7 +696,7 @@ test('MpvIpcClient captures and disables secondary subtitle visibility on reques
   ]);
 });
 
-test('MpvIpcClient restorePreviousSecondarySubVisibility restores and clears tracked value', async () => {
+test('MpvIpcClient restores secondary subtitle visibility and relinquishes suppression', async () => {
   const commands: unknown[] = [];
   const client = new MpvIpcClient('/tmp/mpv.sock', makeDeps());
   const previous: boolean[] = [];
@@ -671,6 +715,12 @@ test('MpvIpcClient restorePreviousSecondarySubVisibility restores and clears tra
   });
   client.restorePreviousSecondarySubVisibility();
 
+  await invokeHandleMessage(client, {
+    event: 'property-change',
+    name: 'secondary-sub-visibility',
+    data: 'yes',
+  });
+
   assert.equal(previous[0], true);
   assert.equal(previous.length, 1);
   assert.deepEqual(commands, [
@@ -682,8 +732,53 @@ test('MpvIpcClient restorePreviousSecondarySubVisibility restores and clears tra
     },
   ]);
 
+  await invokeHandleMessage(client, {
+    event: 'property-change',
+    name: 'secondary-sub-visibility',
+    data: 'yes',
+  });
+  assert.equal(commands.length, 2);
+
   client.restorePreviousSecondarySubVisibility();
   assert.equal(commands.length, 2);
+
+  const callbacks = (client as any).transport.callbacks;
+  callbacks.onConnect();
+  commands.length = 0;
+
+  await invokeHandleMessage(client, {
+    event: 'property-change',
+    name: 'secondary-sub-visibility',
+    data: 'yes',
+  });
+  assert.deepEqual(commands, [{ command: ['set_property', 'secondary-sub-visibility', 'no'] }]);
+});
+
+test('MpvIpcClient keeps secondary subtitle suppression when restoration send fails', async () => {
+  const commands: unknown[] = [];
+  const client = new MpvIpcClient('/tmp/mpv.sock', makeDeps());
+
+  (client as any).send = (payload: unknown) => {
+    commands.push(payload);
+    return false;
+  };
+
+  await invokeHandleMessage(client, {
+    request_id: MPV_REQUEST_ID_SECONDARY_SUB_VISIBILITY,
+    data: 'yes',
+  });
+  client.restorePreviousSecondarySubVisibility();
+  await invokeHandleMessage(client, {
+    event: 'property-change',
+    name: 'secondary-sid',
+    data: 4,
+  });
+
+  assert.deepEqual(commands, [
+    { command: ['set_property', 'secondary-sub-visibility', 'no'] },
+    { command: ['set_property', 'secondary-sub-visibility', 'yes'] },
+    { command: ['set_property', 'secondary-sub-visibility', 'no'] },
+  ]);
 });
 
 test('MpvIpcClient updates current audio stream index from track list', async () => {
diff --git a/src/core/services/mpv.ts b/src/core/services/mpv.ts
index 271e9735..3345733d 100644
--- a/src/core/services/mpv.ts
+++ b/src/core/services/mpv.ts
@@ -184,6 +184,7 @@ export class MpvIpcClient implements MpvClient {
     osdDimensions: null,
   };
   private previousSecondarySubVisibility: boolean | null = null;
+  private enforceSecondarySubVisibilityHidden = true;
   private playbackPaused: boolean | null = null;
   private pauseAtTime: number | null = null;
   private pendingPauseAtSubEnd = false;
@@ -199,6 +200,7 @@ export class MpvIpcClient implements MpvClient {
       socketFactory: deps.socketFactory,
       connectTimeoutMs: deps.connectTimeoutMs,
       onConnect: () => {
+        this.enforceSecondarySubVisibilityHidden = true;
         this.connected = true;
         this.connecting = false;
         this.socket = this.transport.getSocket();
@@ -476,6 +478,7 @@ export class MpvIpcClient implements MpvClient {
       },
       resolvePendingRequest: (requestId: number, message: MpvMessage) =>
         this.tryResolvePendingRequest(requestId, message),
+      shouldEnforceSecondarySubVisibilityHidden: () => this.enforceSecondarySubVisibilityHidden,
       setSecondarySubVisibility: (visible: boolean) => this.setSecondarySubVisibility(visible),
       syncCurrentAudioStreamIndex: () => {
         this.syncCurrentAudioStreamIndex();
@@ -647,9 +650,11 @@ export class MpvIpcClient implements MpvClient {
   restorePreviousSecondarySubVisibility(): void {
     const previous = this.previousSecondarySubVisibility;
     if (previous === null) return;
-    this.send({
+    const restored = this.send({
       command: ['set_property', 'secondary-sub-visibility', previous ? 'yes' : 'no'],
     });
+    if (!restored) return;
+    this.enforceSecondarySubVisibilityHidden = false;
     this.previousSecondarySubVisibility = null;
   }
 
diff --git a/src/core/services/overlay-runtime-init.ts b/src/core/services/overlay-runtime-init.ts
index 6f452336..1042c6fc 100644
--- a/src/core/services/overlay-runtime-init.ts
+++ b/src/core/services/overlay-runtime-init.ts
@@ -21,6 +21,7 @@ type CreateAnkiIntegrationArgs = {
   mpvClient: { send?: (payload: { command: string[] }) => void };
   showDesktopNotification: (title: string, options: { body?: string; icon?: string }) => void;
   showOverlayNotification?: (payload: OverlayNotificationPayload) => void;
+  dismissOverlayNotification?: (id: string) => void;
   createFieldGroupingCallback: () => (
     data: KikuFieldGroupingRequestData,
   ) => Promise<KikuFieldGroupingChoice>;
@@ -74,6 +75,7 @@ function createDefaultAnkiIntegration(args: CreateAnkiIntegrationArgs): AnkiInte
     args.getCachedMediaPath,
     args.shouldRequireRemoteMediaCache,
     args.getYoutubeMediaSourceUrl,
+    args.dismissOverlayNotification,
   );
 }
 
@@ -137,6 +139,7 @@ export function initializeOverlayRuntime(
     setAnkiIntegration: (integration: unknown | null) => void;
     showDesktopNotification: (title: string, options: { body?: string; icon?: string }) => void;
     showOverlayNotification?: (payload: OverlayNotificationPayload) => void;
+    dismissOverlayNotification?: (id: string) => void;
     createFieldGroupingCallback: () => (
       data: KikuFieldGroupingRequestData,
     ) => Promise<KikuFieldGroupingChoice>;
@@ -177,6 +180,7 @@ export function initializeOverlayAnkiIntegration(options: {
   setAnkiIntegration: (integration: unknown | null) => void;
   showDesktopNotification: (title: string, options: { body?: string; icon?: string }) => void;
   showOverlayNotification?: (payload: OverlayNotificationPayload) => void;
+  dismissOverlayNotification?: (id: string) => void;
   createFieldGroupingCallback: () => (
     data: KikuFieldGroupingRequestData,
   ) => Promise<KikuFieldGroupingChoice>;
@@ -219,6 +223,7 @@ export function initializeOverlayAnkiIntegration(options: {
     mpvClient,
     showDesktopNotification: options.showDesktopNotification,
     showOverlayNotification: options.showOverlayNotification,
+    dismissOverlayNotification: options.dismissOverlayNotification,
     createFieldGroupingCallback: options.createFieldGroupingCallback,
     knownWordCacheStatePath: options.getKnownWordCacheStatePath(),
     ...(options.getCachedMediaPath ? { getCachedMediaPath: options.getCachedMediaPath } : {}),
diff --git a/src/core/services/overlay-shortcut-handler.test.ts b/src/core/services/overlay-shortcut-handler.test.ts
index f6fff56e..724b21a4 100644
--- a/src/core/services/overlay-shortcut-handler.test.ts
+++ b/src/core/services/overlay-shortcut-handler.test.ts
@@ -29,6 +29,8 @@ function makeShortcuts(overrides: Partial<ConfiguredShortcuts> = {}): Configured
     openRuntimeOptions: null,
     openJimaku: null,
     openTsukihime: null,
+    openSubtitleSelection: null,
+    openSubtitleGeneration: null,
     openSessionHelp: null,
     openControllerSelect: null,
     openControllerDebug: null,
diff --git a/src/core/services/overlay-shortcut.test.ts b/src/core/services/overlay-shortcut.test.ts
index 8daa1867..c616fe85 100644
--- a/src/core/services/overlay-shortcut.test.ts
+++ b/src/core/services/overlay-shortcut.test.ts
@@ -24,6 +24,8 @@ function createShortcuts(overrides: Partial<ConfiguredShortcuts> = {}): Configur
     openRuntimeOptions: null,
     openJimaku: null,
     openTsukihime: null,
+    openSubtitleSelection: null,
+    openSubtitleGeneration: null,
     openSessionHelp: null,
     openControllerSelect: null,
     openControllerDebug: null,
diff --git a/src/core/services/overlay-window-input.ts b/src/core/services/overlay-window-input.ts
index e39ecee4..5f783701 100644
--- a/src/core/services/overlay-window-input.ts
+++ b/src/core/services/overlay-window-input.ts
@@ -37,6 +37,15 @@ export function handleOverlayWindowBeforeInputEvent(options: {
   if (options.kind === 'modal') return false;
   if (!options.windowVisible) return false;
 
+  // The renderer decides whether Copy targets selected sidebar text or the live cue.
+  if (
+    (options.input.control || options.input.meta) &&
+    !options.input.alt &&
+    !options.input.shift &&
+    (options.input.code === 'KeyC' || options.input.key.toLowerCase() === 'c')
+  )
+    return false;
+
   if (isKeyboardModeToggleInput(options.input)) {
     options.preventDefault();
     options.sendKeyboardModeToggleRequested();
diff --git a/src/core/services/overlay-window.test.ts b/src/core/services/overlay-window.test.ts
index 2458f017..2d38c042 100644
--- a/src/core/services/overlay-window.test.ts
+++ b/src/core/services/overlay-window.test.ts
@@ -85,6 +85,35 @@ test('handleOverlayWindowBeforeInputEvent leaves modal Tab handling alone', () =
   assert.deepEqual(calls, []);
 });
 
+test('native Copy reaches the renderer before the current-subtitle fallback', () => {
+  for (const modifier of [{ control: true }, { meta: true }]) {
+    const handled = handleOverlayWindowBeforeInputEvent({
+      kind: 'visible',
+      windowVisible: true,
+      input: {
+        type: 'keyDown',
+        key: 'c',
+        code: 'KeyC',
+        isAutoRepeat: false,
+        isComposing: false,
+        shift: false,
+        control: false,
+        alt: false,
+        meta: false,
+        location: 0,
+        modifiers: [],
+        ...modifier,
+      },
+      preventDefault: () => assert.fail('Copy must reach Chromium'),
+      sendKeyboardModeToggleRequested: () => assert.fail('Unexpected mode toggle'),
+      sendLookupWindowToggleRequested: () => assert.fail('Unexpected lookup toggle'),
+      tryHandleOverlayShortcutLocalFallback: () => assert.fail('Renderer owns Copy'),
+      forwardTabToMpv: () => assert.fail('Unexpected mpv input'),
+    });
+    assert.equal(handled, false);
+  }
+});
+
 test('handleOverlayWindowBlurred skips visible overlay restacking after manual hide', () => {
   const calls: string[] = [];
 
diff --git a/src/core/services/remote-media-window-cache.test.ts b/src/core/services/remote-media-window-cache.test.ts
new file mode 100644
index 00000000..836ca149
--- /dev/null
+++ b/src/core/services/remote-media-window-cache.test.ts
@@ -0,0 +1,253 @@
+import assert from 'node:assert/strict';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import test from 'node:test';
+import {
+  buildRemoteMediaWindowArgs,
+  RemoteMediaWindowCache,
+  REMOTE_MEDIA_WINDOW_MAX_SECONDS,
+  type RemoteMediaWindowCacheOptions,
+} from './remote-media-window-cache';
+
+const SOURCE = {
+  path: 'https://jellyfin.example/Videos/abc/stream?static=true',
+  audioStreamIndex: 2,
+};
+
+type ExecFileStub = NonNullable<RemoteMediaWindowCacheOptions['execFile']>;
+
+function createStub(options: { fail?: boolean; empty?: boolean; defer?: boolean } = {}) {
+  const calls: string[][] = [];
+  const pendingCallbacks: Array<() => void> = [];
+  const execFile: ExecFileStub = (_file, args, _options, callback) => {
+    calls.push([...args]);
+    const finish = (): void => {
+      const outputPath = args.at(-1);
+      assert.ok(outputPath);
+      if (options.fail) {
+        callback(Object.assign(new Error('boom'), { code: 1 }));
+        return;
+      }
+      if (!options.empty) {
+        fs.writeFileSync(outputPath, 'mkv', 'utf8');
+      }
+      callback(null);
+    };
+    if (options.defer) {
+      pendingCallbacks.push(finish);
+    } else {
+      queueMicrotask(finish);
+    }
+  };
+  return {
+    calls,
+    execFile,
+    flush: () => {
+      for (const finish of pendingCallbacks.splice(0)) finish();
+    },
+  };
+}
+
+async function withCache(
+  stubOptions: Parameters<typeof createStub>[0],
+  cacheOptions: Omit<RemoteMediaWindowCacheOptions, 'execFile' | 'tempDir'>,
+  run: (cache: RemoteMediaWindowCache, stub: ReturnType<typeof createStub>) => Promise<void>,
+): Promise<void> {
+  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'subminer-media-window-test-'));
+  const stub = createStub(stubOptions);
+  const cache = new RemoteMediaWindowCache({
+    tempDir,
+    execFile: stub.execFile,
+    idleTtlMs: 0,
+    logDebug: () => undefined,
+    ...cacheOptions,
+  });
+  try {
+    await run(cache, stub);
+  } finally {
+    cache.cleanup();
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  }
+}
+
+function argValue(args: string[], flag: string): string | undefined {
+  const index = args.indexOf(flag);
+  return index === -1 ? undefined : args[index + 1];
+}
+
+test('buildRemoteMediaWindowArgs stream-copies the window with source timestamps intact', () => {
+  const args = buildRemoteMediaWindowArgs(
+    { ...SOURCE, inputOptions: { reconnect: true, headers: { Referer: 'https://a.example/' } } },
+    { startTime: 22.75, endTime: 33 },
+    '/tmp/window.mkv',
+  );
+
+  const inputIndex = args.indexOf('-i');
+  assert.equal(args[inputIndex + 1], SOURCE.path);
+  assert.ok(args.indexOf('-reconnect') < inputIndex);
+  assert.ok(args.indexOf('-headers') < inputIndex);
+  assert.equal(argValue(args, '-ss'), '22.75');
+  assert.equal(argValue(args, '-t'), '10.25');
+  assert.ok(args.indexOf('-t') < inputIndex);
+  assert.deepEqual(args.slice(args.indexOf('-map'), args.indexOf('-map') + 4), [
+    '-map',
+    '0:v:0?',
+    '-map',
+    '0:2',
+  ]);
+  assert.equal(argValue(args, '-c'), 'copy');
+  assert.ok(args.includes('-copyts'));
+  assert.ok(args.includes('-start_at_zero'));
+  assert.equal(argValue(args, '-f'), 'matroska');
+  assert.equal(args.at(-1), '/tmp/window.mkv');
+});
+
+test('buildRemoteMediaWindowArgs keeps every audio stream when none is selected', () => {
+  const args = buildRemoteMediaWindowArgs(
+    { path: SOURCE.path, audioStreamIndex: null },
+    { startTime: 0, endTime: 5 },
+    '/tmp/window.mkv',
+  );
+
+  assert.equal(args[args.lastIndexOf('-map') + 1], '0:a');
+});
+
+test('acquire downloads once and reuses the window for covered ranges', async () => {
+  await withCache({}, {}, async (cache, stub) => {
+    const window = await cache.acquire(SOURCE, { startTime: 10, endTime: 14 });
+
+    assert.equal(stub.calls.length, 1);
+    assert.equal(argValue(stub.calls[0]!, '-ss'), '9.75');
+    assert.equal(argValue(stub.calls[0]!, '-t'), '5.25');
+    assert.equal(window.startTime, 9.75);
+    assert.equal(window.endTime, 15);
+    assert.equal(window.audioStreamIndex, 2);
+    assert.ok(fs.existsSync(window.path));
+    assert.deepEqual(window.media, {
+      path: window.path,
+      source: 'remote-window',
+      singleResolvedStream: true,
+      absoluteTimestamps: true,
+    });
+
+    assert.equal(await cache.acquire(SOURCE, { startTime: 11, endTime: 15 }), window);
+    assert.equal(await cache.lookup(SOURCE, { startTime: 12, endTime: 12 }), window);
+    assert.equal(
+      await cache.lookup(
+        { path: SOURCE.path, audioStreamIndex: null },
+        { startTime: 12, endTime: 13 },
+      ),
+      window,
+    );
+    assert.equal(stub.calls.length, 1);
+  });
+});
+
+test('lookup never downloads and misses on other ranges, sources, or audio streams', async () => {
+  await withCache({}, {}, async (cache, stub) => {
+    assert.equal(await cache.lookup(SOURCE, { startTime: 10, endTime: 14 }), null);
+    assert.equal(stub.calls.length, 0);
+
+    await cache.acquire(SOURCE, { startTime: 10, endTime: 14 });
+    assert.equal(await cache.lookup(SOURCE, { startTime: 14, endTime: 16 }), null);
+    assert.equal(
+      await cache.lookup(
+        { path: 'https://other.example/stream', audioStreamIndex: 2 },
+        {
+          startTime: 11,
+          endTime: 12,
+        },
+      ),
+      null,
+    );
+    assert.equal(
+      await cache.lookup(
+        { path: SOURCE.path, audioStreamIndex: 3 },
+        { startTime: 11, endTime: 12 },
+      ),
+      null,
+    );
+    assert.equal(stub.calls.length, 1);
+  });
+});
+
+test('acquire widens to the union of the old window and replaces the old file', async () => {
+  await withCache({}, {}, async (cache, stub) => {
+    const first = await cache.acquire(SOURCE, { startTime: 10, endTime: 14 });
+    const second = await cache.acquire(SOURCE, { startTime: 8, endTime: 12 });
+
+    assert.equal(stub.calls.length, 2);
+    assert.equal(argValue(stub.calls[1]!, '-ss'), '7.75');
+    assert.equal(second.startTime, 7.75);
+    assert.equal(second.endTime, 15);
+    assert.notEqual(second.path, first.path);
+    assert.equal(fs.existsSync(first.path), false);
+    assert.ok(fs.existsSync(second.path));
+    assert.equal(cache.currentWindow, second);
+  });
+});
+
+test('acquire shares an in-flight download between concurrent callers', async () => {
+  await withCache({ defer: true }, {}, async (cache, stub) => {
+    const first = cache.acquire(SOURCE, { startTime: 10, endTime: 14 });
+    await Promise.resolve();
+    const second = cache.acquire(SOURCE, { startTime: 11, endTime: 13 });
+    const lookup = cache.lookup(SOURCE, { startTime: 12, endTime: 12 });
+    await Promise.resolve();
+    assert.equal(stub.calls.length, 1);
+
+    stub.flush();
+    const [a, b, c] = await Promise.all([first, second, lookup]);
+    assert.equal(a, b);
+    assert.equal(a, c);
+    assert.equal(stub.calls.length, 1);
+  });
+});
+
+test('acquire rejects on ffmpeg failure, leaves no file, and can retry', async () => {
+  await withCache({ fail: true }, {}, async (cache, stub) => {
+    await assert.rejects(
+      cache.acquire(SOURCE, { startTime: 10, endTime: 14 }),
+      /FFmpeg media window failed: boom/,
+    );
+    assert.equal(cache.currentWindow, null);
+    assert.equal(await cache.lookup(SOURCE, { startTime: 10, endTime: 14 }), null);
+
+    await assert.rejects(cache.acquire(SOURCE, { startTime: 10, endTime: 14 }));
+    assert.equal(stub.calls.length, 2);
+  });
+  await withCache({ empty: true }, {}, async (cache) => {
+    await assert.rejects(
+      cache.acquire(SOURCE, { startTime: 10, endTime: 14 }),
+      /exited without creating a media window/,
+    );
+  });
+});
+
+test('acquire refuses invalid and oversized ranges without spawning ffmpeg', async () => {
+  await withCache({}, {}, async (cache, stub) => {
+    await assert.rejects(cache.acquire(SOURCE, { startTime: 10, endTime: 10 }), /invalid/);
+    await assert.rejects(cache.acquire(SOURCE, { startTime: -1, endTime: 10 }), /invalid/);
+    await assert.rejects(
+      cache.acquire(SOURCE, { startTime: 0, endTime: REMOTE_MEDIA_WINDOW_MAX_SECONDS + 1 }),
+      /too long/,
+    );
+    assert.equal(stub.calls.length, 0);
+  });
+});
+
+test('the window is deleted after the idle timeout and on cleanup', async () => {
+  await withCache({}, { idleTtlMs: 20 }, async (cache) => {
+    const window = await cache.acquire(SOURCE, { startTime: 10, endTime: 14 });
+    await new Promise((resolve) => setTimeout(resolve, 60));
+
+    assert.equal(cache.currentWindow, null);
+    assert.equal(fs.existsSync(window.path), false);
+
+    const again = await cache.acquire(SOURCE, { startTime: 10, endTime: 14 });
+    cache.cleanup();
+    assert.equal(fs.existsSync(again.path), false);
+    assert.equal(fs.existsSync(path.dirname(again.path)), false);
+  });
+});
diff --git a/src/core/services/remote-media-window-cache.ts b/src/core/services/remote-media-window-cache.ts
new file mode 100644
index 00000000..ca486a66
--- /dev/null
+++ b/src/core/services/remote-media-window-cache.ts
@@ -0,0 +1,377 @@
+import { execFile as nodeExecFile, type ExecFileException } from 'child_process';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { createLogger } from '../../logger';
+import { normalizeMediaInput, type MediaInput, type MediaInputOptions } from '../../media-input';
+
+const log = createLogger('media-window');
+
+export const REMOTE_MEDIA_WINDOW_TIMEOUT_MS = 120_000;
+export const REMOTE_MEDIA_WINDOW_MAX_SECONDS = 180;
+const HEAD_SLACK_SECONDS = 0.25;
+const TAIL_SLACK_SECONDS = 1;
+const DEFAULT_IDLE_TTL_MS = 10 * 60_000;
+const COVERAGE_EPSILON_SECONDS = 0.01;
+
+export interface RemoteMediaWindowSource {
+  path: string;
+  inputOptions?: MediaInputOptions;
+  /** FFmpeg stream index to keep; `null`/undefined keeps every audio stream. */
+  audioStreamIndex?: number | null;
+}
+
+export interface RemoteMediaWindowRange {
+  startTime: number;
+  endTime: number;
+}
+
+export interface RemoteMediaWindow {
+  path: string;
+  startTime: number;
+  endTime: number;
+  sourcePath: string;
+  audioStreamIndex: number | null;
+  /** Input descriptor for FFmpeg reads; timestamps stay absolute so callers keep source times. */
+  media: MediaInput;
+}
+
+type WindowExecFile = (
+  file: string,
+  args: readonly string[],
+  options: { timeout: number },
+  callback: (error: ExecFileException | null) => void,
+) => void;
+
+export interface RemoteMediaWindowCacheOptions {
+  tempDir?: string;
+  execFile?: WindowExecFile;
+  idleTtlMs?: number;
+  logDebug?: (message: string) => void;
+}
+
+interface PendingFetch extends RemoteMediaWindowRange {
+  sourcePath: string;
+  audioStreamIndex: number | null;
+  promise: Promise<RemoteMediaWindow>;
+}
+
+export function isRemoteMediaWindowSourcePath(value: string): boolean {
+  return /^https?:\/\//i.test(value.trim());
+}
+
+function describeSourceForDebugLog(sourcePath: string): string {
+  try {
+    return `remote:${new URL(sourcePath).hostname.toLowerCase() || 'unknown'}`;
+  } catch {
+    return 'remote:unknown';
+  }
+}
+
+function isUsableRange(range: RemoteMediaWindowRange, allowEmpty: boolean): boolean {
+  return (
+    Number.isFinite(range.startTime) &&
+    Number.isFinite(range.endTime) &&
+    range.startTime >= 0 &&
+    (allowEmpty ? range.endTime >= range.startTime : range.endTime > range.startTime)
+  );
+}
+
+function audioStreamMatches(
+  windowIndex: number | null,
+  requested: number | null | undefined,
+): boolean {
+  return requested == null || windowIndex === requested;
+}
+
+function covers(
+  candidate: RemoteMediaWindowRange & { sourcePath: string; audioStreamIndex: number | null },
+  source: RemoteMediaWindowSource,
+  range: RemoteMediaWindowRange,
+): boolean {
+  return (
+    candidate.sourcePath === source.path &&
+    audioStreamMatches(candidate.audioStreamIndex, source.audioStreamIndex) &&
+    candidate.startTime <= range.startTime + COVERAGE_EPSILON_SECONDS &&
+    candidate.endTime >= range.endTime - COVERAGE_EPSILON_SECONDS
+  );
+}
+
+/**
+ * Stream-copies `[startTime, endTime]` of a remote source into a local Matroska file.
+ * `-copyts -start_at_zero` keeps the source timestamps, so later reads seek with the
+ * original times via `-seek_timestamp 1` (see `MediaInput.absoluteTimestamps`).
+ */
+export function buildRemoteMediaWindowArgs(
+  source: RemoteMediaWindowSource,
+  range: RemoteMediaWindowRange,
+  outputPath: string,
+): string[] {
+  const input = normalizeMediaInput({ path: source.path, inputOptions: source.inputOptions });
+  const audioMap =
+    typeof source.audioStreamIndex === 'number' && Number.isInteger(source.audioStreamIndex)
+      ? `0:${source.audioStreamIndex}`
+      : '0:a';
+  return [
+    '-hide_banner',
+    '-nostdin',
+    '-loglevel',
+    'error',
+    '-ss',
+    String(range.startTime),
+    '-t',
+    String(range.endTime - range.startTime),
+    ...input.inputArgs,
+    '-i',
+    input.path,
+    '-map',
+    '0:v:0?',
+    '-map',
+    audioMap,
+    '-c',
+    'copy',
+    '-sn',
+    '-dn',
+    '-copyts',
+    '-start_at_zero',
+    '-f',
+    'matroska',
+    '-y',
+    outputPath,
+  ];
+}
+
+/**
+ * Holds one downloaded window of the current remote stream so the timing review,
+ * audio extraction, and screenshot all read the same local bytes instead of each
+ * re-fetching the clip over HTTP. A new window replaces the old one; the file is
+ * deleted after `idleTtlMs` without use, on `clear()`, or on `cleanup()`.
+ */
+export class RemoteMediaWindowCache {
+  private readonly tempDir: string;
+  private readonly execFile: WindowExecFile;
+  private readonly idleTtlMs: number;
+  private readonly logDebug: (message: string) => void;
+  private current: RemoteMediaWindow | null = null;
+  private pending: PendingFetch | null = null;
+  private idleTimer: ReturnType<typeof setTimeout> | null = null;
+  private sequence = 0;
+
+  constructor(options: RemoteMediaWindowCacheOptions = {}) {
+    this.tempDir = options.tempDir ?? path.join(os.tmpdir(), 'subminer-media-windows');
+    this.execFile = options.execFile ?? nodeExecFile;
+    this.idleTtlMs = options.idleTtlMs ?? DEFAULT_IDLE_TTL_MS;
+    this.logDebug = options.logDebug ?? ((message) => log.debug(message));
+  }
+
+  get currentWindow(): RemoteMediaWindow | null {
+    return this.current;
+  }
+
+  /** Returns a ready or in-flight window covering the range; never starts a download. */
+  async lookup(
+    source: RemoteMediaWindowSource,
+    range: RemoteMediaWindowRange,
+  ): Promise<RemoteMediaWindow | null> {
+    if (!isUsableRange(range, true)) return null;
+    if (this.current && covers(this.current, source, range)) {
+      this.touch();
+      return this.current;
+    }
+    const pending = this.pending;
+    if (pending && covers(pending, source, range)) {
+      try {
+        const window = await pending.promise;
+        this.touch();
+        return window;
+      } catch {
+        return null;
+      }
+    }
+    return null;
+  }
+
+  /** Returns a window covering the range, downloading (and widening) one when needed. */
+  async acquire(
+    source: RemoteMediaWindowSource,
+    range: RemoteMediaWindowRange,
+  ): Promise<RemoteMediaWindow> {
+    if (!isUsableRange(range, false)) {
+      throw new Error('Media window range is invalid.');
+    }
+    if (range.endTime - range.startTime > REMOTE_MEDIA_WINDOW_MAX_SECONDS) {
+      throw new Error('Media window range is too long to download.');
+    }
+
+    for (;;) {
+      const hit = await this.lookup(source, range);
+      if (hit) return hit;
+      const pending = this.pending;
+      if (!pending) break;
+      // Another caller is already downloading; wait for it, then re-check coverage.
+      await pending.promise.catch(() => null);
+    }
+
+    return this.fetch(source, this.planFetchRange(source, range));
+  }
+
+  clear(): void {
+    this.cancelIdleTimer();
+    const current = this.current;
+    this.current = null;
+    if (current) this.removeFile(current.path);
+  }
+
+  cleanup(): void {
+    this.clear();
+    try {
+      fs.rmSync(this.tempDir, { recursive: true, force: true });
+    } catch (error) {
+      log.error('Failed to cleanup media window directory:', error);
+    }
+  }
+
+  private planFetchRange(
+    source: RemoteMediaWindowSource,
+    range: RemoteMediaWindowRange,
+  ): RemoteMediaWindowRange {
+    let startTime = Math.max(0, range.startTime - HEAD_SLACK_SECONDS);
+    let endTime = range.endTime + TAIL_SLACK_SECONDS;
+    const current = this.current;
+    if (
+      current &&
+      current.sourcePath === source.path &&
+      audioStreamMatches(current.audioStreamIndex, source.audioStreamIndex)
+    ) {
+      // Keep what was already downloaded when the review timeline grows in one direction.
+      const unionStart = Math.min(startTime, current.startTime);
+      const unionEnd = Math.max(endTime, current.endTime);
+      if (unionEnd - unionStart <= REMOTE_MEDIA_WINDOW_MAX_SECONDS) {
+        startTime = unionStart;
+        endTime = unionEnd;
+      }
+    }
+    return { startTime, endTime };
+  }
+
+  private fetch(
+    source: RemoteMediaWindowSource,
+    range: RemoteMediaWindowRange,
+  ): Promise<RemoteMediaWindow> {
+    fs.mkdirSync(this.tempDir, { recursive: true });
+    this.sequence += 1;
+    const outputPath = path.join(this.tempDir, `window_${Date.now()}_${this.sequence}.mkv`);
+    const audioStreamIndex =
+      typeof source.audioStreamIndex === 'number' ? source.audioStreamIndex : null;
+    const description = describeSourceForDebugLog(source.path);
+    const startedAt = Date.now();
+    this.logDebug(
+      `[media-window] fetch start ${description} start=${range.startTime} end=${range.endTime} audioStream=${audioStreamIndex ?? 'all'}`,
+    );
+
+    const promise = new Promise<RemoteMediaWindow>((resolve, reject) => {
+      this.execFile(
+        'ffmpeg',
+        buildRemoteMediaWindowArgs(source, range, outputPath),
+        { timeout: REMOTE_MEDIA_WINDOW_TIMEOUT_MS },
+        (error) => {
+          const elapsedMs = Math.max(0, Date.now() - startedAt);
+          const size = error ? 0 : this.fileSize(outputPath);
+          if (error || size === 0) {
+            this.removeFile(outputPath);
+            const reason = error
+              ? error.code === 'ENOENT'
+                ? 'FFmpeg not found. Install FFmpeg to enable media generation.'
+                : `FFmpeg media window failed: ${error.message}`
+              : 'FFmpeg exited without creating a media window.';
+            this.logDebug(`[media-window] fetch failed ${description} elapsedMs=${elapsedMs}`);
+            reject(new Error(reason));
+            return;
+          }
+          const window: RemoteMediaWindow = {
+            path: outputPath,
+            startTime: range.startTime,
+            endTime: range.endTime,
+            sourcePath: source.path,
+            audioStreamIndex,
+            media: {
+              path: outputPath,
+              source: 'remote-window',
+              singleResolvedStream: true,
+              absoluteTimestamps: true,
+            },
+          };
+          this.logDebug(
+            `[media-window] fetch complete ${description} elapsedMs=${elapsedMs} bytes=${size}`,
+          );
+          this.replaceCurrent(window);
+          resolve(window);
+        },
+      );
+    });
+
+    const pending: PendingFetch = {
+      sourcePath: source.path,
+      audioStreamIndex,
+      startTime: range.startTime,
+      endTime: range.endTime,
+      promise,
+    };
+    this.pending = pending;
+    promise
+      .catch(() => undefined)
+      .then(() => {
+        if (this.pending === pending) this.pending = null;
+      });
+    return promise;
+  }
+
+  private replaceCurrent(window: RemoteMediaWindow): void {
+    const previous = this.current;
+    this.current = window;
+    if (previous && previous.path !== window.path) this.removeFile(previous.path);
+    this.touch();
+  }
+
+  private touch(): void {
+    this.cancelIdleTimer();
+    if (this.idleTtlMs <= 0 || !this.current) return;
+    const timer = setTimeout(() => {
+      if (this.idleTimer === timer) this.idleTimer = null;
+      this.clear();
+    }, this.idleTtlMs);
+    timer.unref?.();
+    this.idleTimer = timer;
+  }
+
+  private cancelIdleTimer(): void {
+    if (this.idleTimer) clearTimeout(this.idleTimer);
+    this.idleTimer = null;
+  }
+
+  private fileSize(filePath: string): number {
+    try {
+      return fs.statSync(filePath).size;
+    } catch {
+      return 0;
+    }
+  }
+
+  private removeFile(filePath: string): void {
+    try {
+      fs.unlinkSync(filePath);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') {
+        log.debug(`Failed to remove media window ${filePath}:`, (error as Error).message);
+      }
+    }
+  }
+}
+
+let sharedCache: RemoteMediaWindowCache | null = null;
+
+/** Process-wide cache so the review modal and card media generation share one download. */
+export function getSharedRemoteMediaWindowCache(): RemoteMediaWindowCache {
+  sharedCache ??= new RemoteMediaWindowCache();
+  return sharedCache;
+}
diff --git a/src/core/services/secondary-subtitle-line-identity.ts b/src/core/services/secondary-subtitle-line-identity.ts
new file mode 100644
index 00000000..16442abf
--- /dev/null
+++ b/src/core/services/secondary-subtitle-line-identity.ts
@@ -0,0 +1,15 @@
+const MIN_FLATTENED_DUPLICATE_LENGTH = 16;
+const TERMINAL_SENTENCE_PUNCTUATION = /[.!?。！？…⋯]+$/gu;
+
+/**
+ * Identifies long lines that become duplicates when positioned ASS events are
+ * flattened into the secondary subtitle bar. Short dialogue stays distinct.
+ */
+export function flattenedSecondarySubtitleLineIdentity(text: string): string | null {
+  const identity = text
+    .normalize('NFKC')
+    .replace(/\s+/gu, '')
+    .replace(TERMINAL_SENTENCE_PUNCTUATION, '');
+
+  return identity.length >= MIN_FLATTENED_DUPLICATE_LENGTH ? identity : null;
+}
diff --git a/src/core/services/session-actions.test.ts b/src/core/services/session-actions.test.ts
index 863dbff0..b6216d01 100644
--- a/src/core/services/session-actions.test.ts
+++ b/src/core/services/session-actions.test.ts
@@ -6,7 +6,9 @@ import { dispatchSessionAction, type SessionActionExecutorDeps } from './session
 function createDeps(overrides: Partial<SessionActionExecutorDeps> = {}) {
   const calls: string[] = [];
   const deps: SessionActionExecutorDeps = {
-    toggleStatsOverlay: () => calls.push('stats'),
+    toggleStatsOverlay: () => {
+      calls.push('stats');
+    },
     toggleVisibleOverlay: () => calls.push('visible'),
     copyCurrentSubtitle: () => calls.push('copy'),
     copySubtitleCount: (count) => calls.push(`copy:${count}`),
@@ -41,6 +43,8 @@ function createDeps(overrides: Partial<SessionActionExecutorDeps> = {}) {
     openControllerDebug: () => calls.push('controller-debug'),
     openJimaku: () => calls.push('jimaku'),
     openTsukihime: () => calls.push('tsukihime'),
+    openSubtitleSelection: () => calls.push('subtitle-selection'),
+    openSubtitleGeneration: () => calls.push('subtitle-generation'),
     openYoutubeTrackPicker: () => {
       calls.push('youtube');
     },
@@ -85,3 +89,9 @@ test('dispatchSessionAction opens the character dictionary manager', async () =>
 
   assert.deepEqual(calls, ['character-dictionary-manager']);
 });
+
+test('dispatchSessionAction opens subtitle generation without opening the sidebar', async () => {
+  const { calls, deps } = createDeps();
+  await dispatchSessionAction({ actionId: 'openSubtitleGeneration' }, deps);
+  assert.deepEqual(calls, ['subtitle-generation']);
+});
diff --git a/src/core/services/session-actions.ts b/src/core/services/session-actions.ts
index 9e22775b..5c257be5 100644
--- a/src/core/services/session-actions.ts
+++ b/src/core/services/session-actions.ts
@@ -3,7 +3,7 @@ import type { SessionActionId } from '../../types/session-bindings';
 import type { SessionActionDispatchRequest } from '../../types/runtime';
 
 export interface SessionActionExecutorDeps {
-  toggleStatsOverlay: () => void;
+  toggleStatsOverlay: () => Promise<void> | void;
   toggleVisibleOverlay: () => void;
   copyCurrentSubtitle: () => void;
   copySubtitleCount: (count: number) => void;
@@ -25,6 +25,8 @@ export interface SessionActionExecutorDeps {
   openControllerDebug: () => void;
   openJimaku: () => void;
   openTsukihime: () => void;
+  openSubtitleSelection: () => void;
+  openSubtitleGeneration: () => void;
   openYoutubeTrackPicker: () => void | Promise<void>;
   openPlaylistBrowser: () => boolean | void | Promise<boolean | void>;
   replayCurrentSubtitle: () => void;
@@ -49,7 +51,7 @@ export async function dispatchSessionAction(
 ): Promise<void> {
   switch (request.actionId) {
     case 'toggleStatsOverlay':
-      deps.toggleStatsOverlay();
+      await deps.toggleStatsOverlay();
       return;
     case 'toggleVisibleOverlay':
       deps.toggleVisibleOverlay();
@@ -119,6 +121,12 @@ export async function dispatchSessionAction(
     case 'openTsukihime':
       deps.openTsukihime();
       return;
+    case 'openSubtitleSelection':
+      deps.openSubtitleSelection();
+      return;
+    case 'openSubtitleGeneration':
+      deps.openSubtitleGeneration();
+      return;
     case 'openYoutubePicker':
       await deps.openYoutubeTrackPicker();
       return;
diff --git a/src/core/services/session-bindings.test.ts b/src/core/services/session-bindings.test.ts
index b22d0a6f..079f2dc3 100644
--- a/src/core/services/session-bindings.test.ts
+++ b/src/core/services/session-bindings.test.ts
@@ -5,6 +5,7 @@ import type { ConfiguredShortcuts } from '../utils/shortcut-config';
 import { DEFAULT_CONFIG, DEFAULT_KEYBINDINGS, SPECIAL_COMMANDS } from '../../config/definitions';
 import { resolveConfiguredShortcuts } from '../utils/shortcut-config';
 import { buildPluginSessionBindingsArtifact, compileSessionBindings } from './session-bindings';
+import { parseSessionActionDispatchRequest } from '../../shared/ipc/validators';
 
 function createShortcuts(overrides: Partial<ConfiguredShortcuts> = {}): ConfiguredShortcuts {
   return {
@@ -23,6 +24,8 @@ function createShortcuts(overrides: Partial<ConfiguredShortcuts> = {}): Configur
     openRuntimeOptions: null,
     openJimaku: null,
     openTsukihime: null,
+    openSubtitleSelection: null,
+    openSubtitleGeneration: null,
     openSessionHelp: null,
     openControllerSelect: null,
     openControllerDebug: null,
@@ -37,6 +40,50 @@ function createKeybinding(key: string, command: Keybinding['command']): Keybindi
   return { key, command };
 }
 
+test('subtitle generation shortcut compiles for overlay and mpv without conflicting with field grouping', () => {
+  for (const platform of ['linux', 'darwin', 'win32'] as const) {
+    const result = compileSessionBindings({
+      shortcuts: resolveConfiguredShortcuts(DEFAULT_CONFIG, DEFAULT_CONFIG),
+      keybindings: DEFAULT_KEYBINDINGS,
+      platform,
+    });
+    const binding = result.bindings.find(
+      (entry) =>
+        entry.actionType === 'session-action' && entry.actionId === 'openSubtitleGeneration',
+    );
+    assert.ok(binding);
+    assert.deepEqual(binding.key, { code: 'KeyG', modifiers: ['ctrl', 'shift'] });
+    assert.equal(
+      result.warnings.some(
+        (warning) =>
+          warning.path === 'shortcuts.openSubtitleGeneration' ||
+          warning.conflictingPaths?.includes('shortcuts.openSubtitleGeneration'),
+      ),
+      false,
+    );
+    assert.ok(
+      result.bindings.some(
+        (entry) =>
+          entry.actionType === 'session-action' && entry.actionId === 'triggerFieldGrouping',
+      ),
+    );
+    const artifact = buildPluginSessionBindingsArtifact({
+      bindings: [binding],
+      warnings: [],
+      numericSelectionTimeoutMs: 3000,
+    });
+    const pluginBinding = artifact.bindings[0];
+    assert.ok(pluginBinding?.actionType === 'session-action');
+    assert.deepEqual(pluginBinding.cliArgs, [
+      '--session-action',
+      '{"actionId":"openSubtitleGeneration"}',
+    ]);
+    assert.deepEqual(parseSessionActionDispatchRequest({ actionId: 'openSubtitleGeneration' }), {
+      actionId: 'openSubtitleGeneration',
+    });
+  }
+});
+
 test('compileSessionBindings merges shortcuts and keybindings into one canonical list', () => {
   const result = compileSessionBindings({
     shortcuts: createShortcuts({
@@ -661,3 +708,58 @@ test('buildPluginSessionBindingsArtifact preserves plugin selector CLI for no-co
   assert.equal(byActionId.get('copySubtitleMultiple')?.cliArgs, undefined);
   assert.equal(byActionId.get('mineSentenceMultiple')?.cliArgs, undefined);
 });
+
+test('single keys reserve sequence prefixes without reserving the second stroke', () => {
+  for (const key of ['g', 'Ctrl+g', 's']) {
+    const result = compileSessionBindings({
+      shortcuts: createShortcuts({ openSubtitleSelection: 'g-s' }),
+      keybindings: [createKeybinding(key, ['show-text', 'single'])],
+      platform: 'linux',
+    });
+    assert.ok(result.bindings.some((binding) => binding.originalKey === key));
+    assert.equal(
+      result.bindings.some((binding) => binding.originalKey === 'g-s'),
+      key !== 'g',
+    );
+    assert.equal(result.warnings.length, key === 'g' ? 1 : 0);
+    if (key === 'g') assert.match(result.warnings[0]!.message, /Single-key bindings take priority/);
+  }
+});
+
+test('configured shortcuts and built-in overlay keys also reserve sequence prefixes', () => {
+  for (const prefix of ['g', 'y', 'v']) {
+    const result = compileSessionBindings({
+      shortcuts: createShortcuts({ openSubtitleSelection: `${prefix}-s`, copySubtitle: 'g' }),
+      keybindings: [],
+      platform: 'linux',
+    });
+    assert.equal(
+      result.bindings.some((binding) => binding.originalKey === `${prefix}-s`),
+      false,
+    );
+    assert.ok(result.bindings.some((binding) => binding.originalKey === 'g'));
+    assert.equal(result.warnings.length, 1);
+  }
+});
+
+test('sequence reservations follow the sidebar code and literal Shift semantics', () => {
+  for (const [toggleKey, disabled] of [
+    ['KeyG', true],
+    ['g', false],
+    ['G', true],
+  ] as const) {
+    const result = compileSessionBindings({
+      shortcuts: createShortcuts({ openSubtitleSelection: 'Shift+g-s' }),
+      keybindings: [],
+      platform: 'linux',
+      rawConfig: {
+        ...DEFAULT_CONFIG,
+        subtitleSidebar: { ...DEFAULT_CONFIG.subtitleSidebar, toggleKey },
+      },
+    });
+    assert.equal(
+      result.bindings.some((binding) => binding.originalKey === 'Shift+g-s'),
+      !disabled,
+    );
+  }
+});
diff --git a/src/core/services/session-bindings.ts b/src/core/services/session-bindings.ts
index 7bbbc3b6..01329489 100644
--- a/src/core/services/session-bindings.ts
+++ b/src/core/services/session-bindings.ts
@@ -12,6 +12,10 @@ import type {
   SessionKeySpec,
 } from '../../types/session-bindings';
 import { SPECIAL_COMMANDS } from '../../config';
+import {
+  resolveSessionSequenceConflicts,
+  type SessionKeyReservation,
+} from '../../shared/session-key-sequences';
 
 type PlatformKeyModel = 'darwin' | 'win32' | 'linux';
 
@@ -56,6 +60,8 @@ const SESSION_SHORTCUT_ACTIONS: Array<{
   { key: 'openRuntimeOptions', actionId: 'openRuntimeOptions' },
   { key: 'openJimaku', actionId: 'openJimaku' },
   { key: 'openTsukihime', actionId: 'openTsukihime' },
+  { key: 'openSubtitleSelection', actionId: 'openSubtitleSelection' },
+  { key: 'openSubtitleGeneration', actionId: 'openSubtitleGeneration' },
   { key: 'openSessionHelp', actionId: 'openSessionHelp' },
   { key: 'openControllerSelect', actionId: 'openControllerSelect' },
   { key: 'openControllerDebug', actionId: 'openControllerDebug' },
@@ -80,6 +86,13 @@ function normalizeCodeToken(
 ): string | null {
   const normalized = token.trim();
   if (!normalized) return null;
+  // Two lowercase letters use mpv's sequential-key syntax, for example g-s.
+  if (/^[a-z]-[a-z]$/.test(normalized)) {
+    return normalized
+      .split('-')
+      .map((letter) => `Key${letter.toUpperCase()}`)
+      .join('-');
+  }
   if (options.allowMouseButtons === true) {
     const normalizedMouse = normalized.toUpperCase();
     if (MPV_MOUSE_BUTTON_CODES.has(normalizedMouse)) {
@@ -211,7 +224,7 @@ function parseAccelerator(
   };
 }
 
-function parseDomKeyString(
+export function parseSessionBindingKey(
   key: string,
   platform: PlatformKeyModel,
 ): { key: SessionKeySpec | null; message?: string } {
@@ -435,7 +448,7 @@ export function compileSessionBindings(input: CompileSessionBindingsInput): {
   }
 
   if (statsToggleKey) {
-    const parsed = parseDomKeyString(statsToggleKey, input.platform);
+    const parsed = parseSessionBindingKey(statsToggleKey, input.platform);
     if (!parsed.key) {
       warnings.push({
         kind: 'unsupported',
@@ -462,7 +475,7 @@ export function compileSessionBindings(input: CompileSessionBindingsInput): {
   }
 
   if (statsMarkWatchedKey) {
-    const parsed = parseDomKeyString(statsMarkWatchedKey, input.platform);
+    const parsed = parseSessionBindingKey(statsMarkWatchedKey, input.platform);
     if (!parsed.key) {
       warnings.push({
         kind: 'unsupported',
@@ -490,7 +503,7 @@ export function compileSessionBindings(input: CompileSessionBindingsInput): {
 
   input.keybindings.forEach((binding, index) => {
     if (!binding.command) return;
-    const parsed = parseDomKeyString(binding.key, input.platform);
+    const parsed = parseSessionBindingKey(binding.key, input.platform);
     if (!parsed.key) {
       warnings.push({
         kind: 'unsupported',
@@ -542,7 +555,37 @@ export function compileSessionBindings(input: CompileSessionBindingsInput): {
   }
 
   bindings.sort((left, right) => left.sourcePath.localeCompare(right.sourcePath));
-  return { bindings, warnings };
+  const reservations: SessionKeyReservation[] = [
+    { key: { code: 'KeyY', modifiers: [] }, path: 'built-in y sequences' },
+    { key: { code: 'KeyV', modifiers: [] }, path: 'primary subtitle visibility key' },
+    { key: { code: 'KeyY', modifiers: ['ctrl'] }, path: 'lookup window toggle' },
+    { key: { code: 'KeyY', modifiers: ['meta'] }, path: 'lookup window toggle' },
+    { key: { code: 'KeyY', modifiers: ['ctrl', 'shift'] }, path: 'keyboard-driven mode toggle' },
+    { key: { code: 'KeyY', modifiers: ['shift', 'meta'] }, path: 'keyboard-driven mode toggle' },
+    ...[...candidates.values()].flatMap((drafts) =>
+      drafts.map(({ binding }) => ({
+        key: binding.key,
+        path: binding.sourcePath,
+      })),
+    ),
+  ];
+  const sidebarKey = input.rawConfig?.subtitleSidebar?.toggleKey;
+  if (sidebarKey) {
+    const { key } = parseSessionBindingKey(sidebarKey, input.platform);
+    if (key) {
+      // The sidebar accepts DOM codes with either Shift state, or literal characters.
+      if (/^[A-Z]$/.test(sidebarKey)) key.modifiers = ['shift'];
+      reservations.push({ key, path: 'subtitleSidebar.toggleKey' });
+      if (/^Key[A-Z]$/.test(sidebarKey)) {
+        reservations.push({
+          key: { ...key, modifiers: ['shift'] },
+          path: 'subtitleSidebar.toggleKey',
+        });
+      }
+    }
+  }
+  const result = resolveSessionSequenceConflicts(bindings, reservations);
+  return { bindings: result.bindings, warnings: [...warnings, ...result.warnings] };
 }
 
 export function buildPluginSessionBindingsArtifact(input: {
diff --git a/src/core/services/stats-cover-routes.ts b/src/core/services/stats-cover-routes.ts
index 3e70f4f3..7d4f71aa 100644
--- a/src/core/services/stats-cover-routes.ts
+++ b/src/core/services/stats-cover-routes.ts
@@ -3,37 +3,13 @@ import type { Hono } from 'hono';
 import type { ImmersionTrackerService } from './immersion-tracker-service.js';
 import { statsJson, type StatsCoverImagesRequest } from '../../types/stats-http-contract.js';
 import type { StatsCoverImage } from '../../types/stats-wire.js';
+import { parsePositiveId, parsePositiveIdList } from './stats-server/route-support.js';
 
 type StatsCoverImagePayload = StatsCoverImage | null;
 type StatsCoverBatchBody = Partial<Record<keyof StatsCoverImagesRequest, unknown>>;
 
 const MAX_BACKGROUND_ANIME_COVER_FETCHES = 3;
 
-function parseIntQuery(raw: string | undefined, fallback: number, maxLimit?: number): number {
-  if (raw === undefined) return fallback;
-  const n = Number(raw);
-  if (!Number.isFinite(n) || n < 0) {
-    return fallback;
-  }
-  const parsed = Math.floor(n);
-  return maxLimit === undefined ? parsed : Math.min(parsed, maxLimit);
-}
-
-function parsePositiveIdList(raw: unknown, maxItems = 100): number[] {
-  if (!Array.isArray(raw)) return [];
-
-  const ids = new Set<number>();
-  for (const rawId of raw) {
-    const id = typeof rawId === 'number' ? rawId : typeof rawId === 'string' ? Number(rawId) : NaN;
-    if (Number.isFinite(id) && id > 0) {
-      ids.add(Math.floor(id));
-      if (ids.size >= maxItems) break;
-    }
-  }
-
-  return Array.from(ids).sort((a, b) => a - b);
-}
-
 function coverImagePayload(
   art: { coverBlob?: Uint8Array | null } | null | undefined,
 ): StatsCoverImagePayload {
@@ -129,8 +105,11 @@ export function registerStatsCoverRoutes(app: Hono, tracker: ImmersionTrackerSer
 
   app.post('/api/stats/covers', async (c) => {
     const body = (await c.req.json().catch(() => null)) as StatsCoverBatchBody | null;
-    const animeIds = parsePositiveIdList(body?.animeIds);
-    const videoIds = parsePositiveIdList(body?.videoIds);
+    const animeIds = body?.animeIds === undefined ? [] : parsePositiveIdList(body.animeIds, 100);
+    const videoIds = body?.videoIds === undefined ? [] : parsePositiveIdList(body.videoIds, 100);
+    if (!animeIds || !videoIds) return c.body(null, 400);
+    animeIds.sort((a, b) => a - b);
+    videoIds.sort((a, b) => a - b);
     const anime: Record<number, StatsCoverImagePayload> = {};
     const media: Record<number, StatsCoverImagePayload> = {};
 
@@ -155,8 +134,8 @@ export function registerStatsCoverRoutes(app: Hono, tracker: ImmersionTrackerSer
   });
 
   app.get('/api/stats/anime/:animeId/cover', async (c) => {
-    const animeId = parseIntQuery(c.req.param('animeId'), 0);
-    if (animeId <= 0) return c.body(null, 404);
+    const animeId = parsePositiveId(c.req.param('animeId'));
+    if (animeId === null) return c.body(null, 400);
     let art = await tracker.getAnimeCoverArt(animeId);
     if (!art?.coverBlob) {
       await tracker.ensureAnimeCoverArt(animeId);
@@ -167,8 +146,8 @@ export function registerStatsCoverRoutes(app: Hono, tracker: ImmersionTrackerSer
   });
 
   app.get('/api/stats/media/:videoId/cover', async (c) => {
-    const videoId = parseIntQuery(c.req.param('videoId'), 0);
-    if (videoId <= 0) return c.body(null, 404);
+    const videoId = parsePositiveId(c.req.param('videoId'));
+    if (videoId === null) return c.body(null, 400);
     let art = await tracker.getCoverArt(videoId);
     if (!art?.coverBlob) {
       await tracker.ensureCoverArt(videoId);
diff --git a/src/core/services/stats-server.ts b/src/core/services/stats-server.ts
index 6254a20b..66c60204 100644
--- a/src/core/services/stats-server.ts
+++ b/src/core/services/stats-server.ts
@@ -1,11 +1,14 @@
+import type { StatsMiningRouteOptions } from './stats-server/mining-support';
 import { Hono } from 'hono';
 import http, { type IncomingMessage, type ServerResponse } from 'node:http';
 import { Readable } from 'node:stream';
 import type { AnkiConnectConfig } from '../../types.js';
 import type { AnilistRateLimiter } from './anilist/rate-limiter.js';
+import type { TmdbClient } from './tmdb/tmdb-client.js';
 import type { ImmersionTrackerService } from './immersion-tracker-service.js';
 import type { RetimedSecondarySubtitleInput } from './secondary-subtitle-sidecar.js';
 import type { StatsServerMediaGenerator } from './stats-server/mining-support.js';
+import { enforceStatsRequestSafety } from './stats-server/request-safety.js';
 import {
   registerStatsAnalyticsRoutes,
   registerStatsIntegrationRoutes,
@@ -37,7 +40,10 @@ function toFetchRequest(req: IncomingMessage): Request {
     method,
     headers: toFetchHeaders(req.headers),
   };
-  if (method !== 'GET' && method !== 'HEAD') {
+  const hasBody =
+    req.headers['transfer-encoding'] !== undefined ||
+    Number(req.headers['content-length'] ?? 0) > 0;
+  if (method !== 'GET' && method !== 'HEAD' && hasBody) {
     init.body = Readable.toWeb(req) as BodyInit;
     init.duplex = 'half';
   }
@@ -50,8 +56,26 @@ async function writeFetchResponse(res: ServerResponse, response: Response): Prom
   res.end(Buffer.from(await response.arrayBuffer()));
 }
 
-function startNodeHttpServer(app: Hono, config: StatsServerConfig): { close: () => void } {
-  const server = http.createServer((req, res) => {
+export interface StatsServer {
+  close: () => Promise<void>;
+}
+
+const SHUTDOWN_GRACE_MS = 1_000;
+
+type BunServe = (options: {
+  fetch: (typeof Hono.prototype)['fetch'];
+  port: number;
+  hostname: string;
+}) => {
+  stop: () => Promise<void> | void;
+};
+
+export function startNodeHttpServer(
+  app: Hono,
+  config: StatsServerConfig,
+  createServer: (listener: http.RequestListener) => http.Server = http.createServer,
+): Promise<StatsServer> {
+  const server = createServer((req, res) => {
     void (async () => {
       try {
         await writeFetchResponse(res, await app.fetch(toFetchRequest(req)));
@@ -61,12 +85,33 @@ function startNodeHttpServer(app: Hono, config: StatsServerConfig): { close: ()
       }
     })();
   });
-  server.listen(config.port, '127.0.0.1');
-  return {
-    close: () => {
-      server.close();
-    },
-  };
+  return new Promise((resolve, reject) => {
+    const handleStartupError = (error: Error): void => {
+      server.removeListener('listening', handleListening);
+      reject(error);
+    };
+    const handleListening = (): void => {
+      server.removeListener('error', handleStartupError);
+      let closePromise: Promise<void> | null = null;
+      resolve({
+        close: () => {
+          closePromise ??= new Promise<void>((closeResolve, closeReject) => {
+            const forceClose = setTimeout(() => server.closeAllConnections(), SHUTDOWN_GRACE_MS);
+            server.close((error) => {
+              clearTimeout(forceClose);
+              if (error) closeReject(error);
+              else closeResolve();
+            });
+          });
+          return closePromise;
+        },
+      });
+    };
+
+    server.once('error', handleStartupError);
+    server.once('listening', handleListening);
+    server.listen(config.port, '127.0.0.1');
+  });
 }
 
 export interface StatsServerConfig {
@@ -86,7 +131,9 @@ export interface StatsServerConfig {
     input: RetimedSecondarySubtitleInput,
   ) => Promise<string> | string;
   anilistRateLimiter?: AnilistRateLimiter;
+  tmdbClient?: TmdbClient;
   addYomitanNote?: (word: string) => Promise<number | null>;
+  generateSentenceFurigana?: StatsMiningRouteOptions['generateSentenceFurigana'];
   resolveAnkiNoteId?: (noteId: number) => number;
   resolveSentenceSearchHeadwords?: (term: string) => Promise<string[]> | string[];
 }
@@ -108,7 +155,9 @@ export function createStatsApp(
       input: RetimedSecondarySubtitleInput,
     ) => Promise<string> | string;
     anilistRateLimiter?: AnilistRateLimiter;
+    tmdbClient?: TmdbClient;
     addYomitanNote?: (word: string) => Promise<number | null>;
+    generateSentenceFurigana?: StatsMiningRouteOptions['generateSentenceFurigana'];
     resolveAnkiNoteId?: (noteId: number) => number;
     resolveSentenceSearchHeadwords?: (term: string) => Promise<string[]> | string[];
     createMediaGenerator?: () => StatsServerMediaGenerator;
@@ -117,6 +166,7 @@ export function createStatsApp(
   },
 ) {
   const app = new Hono();
+  app.use('*', enforceStatsRequestSafety);
   registerStatsAnalyticsRoutes(app, tracker, options);
   registerStatsLibraryRoutes(app, tracker, options);
   registerStatsIntegrationRoutes(app, tracker, options);
@@ -125,7 +175,10 @@ export function createStatsApp(
   return app;
 }
 
-export function startStatsServer(config: StatsServerConfig): { close: () => void } {
+export async function startStatsServerWithRuntime(
+  config: StatsServerConfig,
+  runtime: { bunServe: BunServe | null },
+): Promise<StatsServer> {
   const app = createStatsApp(config.tracker, {
     staticDir: config.staticDir,
     knownWordCachePath: config.knownWordCachePath,
@@ -139,25 +192,33 @@ export function startStatsServer(config: StatsServerConfig): { close: () => void
     getStatsMiningAlassPath: config.getStatsMiningAlassPath,
     resolveRetimedSecondarySubtitleText: config.resolveRetimedSecondarySubtitleText,
     anilistRateLimiter: config.anilistRateLimiter,
+    tmdbClient: config.tmdbClient,
     addYomitanNote: config.addYomitanNote,
+    generateSentenceFurigana: config.generateSentenceFurigana,
     resolveAnkiNoteId: config.resolveAnkiNoteId,
     resolveSentenceSearchHeadwords: config.resolveSentenceSearchHeadwords,
   });
 
-  const bunRuntime = globalThis as typeof globalThis & {
-    Bun?: {
-      serve?: (options: { fetch: (typeof app)['fetch']; port: number; hostname: string }) => {
-        stop: () => void;
-      };
-    };
-  };
-  if (bunRuntime.Bun?.serve) {
-    const server = bunRuntime.Bun.serve({
+  if (runtime.bunServe) {
+    const server = runtime.bunServe({
       fetch: app.fetch,
       port: config.port,
       hostname: '127.0.0.1',
     });
-    return { close: () => server.stop() };
+    let closePromise: Promise<void> | null = null;
+    return Promise.resolve({
+      close: () => {
+        closePromise ??= Promise.resolve().then(() => server.stop());
+        return closePromise;
+      },
+    });
   }
   return startNodeHttpServer(app, config);
 }
+
+export function startStatsServer(config: StatsServerConfig): Promise<StatsServer> {
+  const bunRuntime = globalThis as typeof globalThis & {
+    Bun?: { serve?: BunServe };
+  };
+  return startStatsServerWithRuntime(config, { bunServe: bunRuntime.Bun?.serve ?? null });
+}
diff --git a/src/core/services/stats-server/analytics-routes.ts b/src/core/services/stats-server/analytics-routes.ts
index 6a9f3e6e..640915da 100644
--- a/src/core/services/stats-server/analytics-routes.ts
+++ b/src/core/services/stats-server/analytics-routes.ts
@@ -6,6 +6,7 @@ import {
   loadKnownWordsSet,
   parseEventTypesQuery,
   parseIntQuery,
+  parsePositiveId,
   parseTrendFillEmpty,
   parseTrendGroupBy,
   parseTrendRange,
@@ -83,8 +84,8 @@ export function registerStatsAnalyticsRoutes(
   });
 
   app.get('/api/stats/sessions/:id/timeline', async (c) => {
-    const id = parseIntQuery(c.req.param('id'), 0);
-    if (id <= 0) return c.json(statsJson('sessionTimeline', []), 400);
+    const id = parsePositiveId(c.req.param('id'));
+    if (id === null) return c.json(statsJson('sessionTimeline', []), 400);
     const rawLimit = c.req.query('limit');
     const limit = rawLimit === undefined ? undefined : parseIntQuery(rawLimit, 200, 1000);
     const timeline = await tracker.getSessionTimeline(id, limit);
@@ -92,8 +93,8 @@ export function registerStatsAnalyticsRoutes(
   });
 
   app.get('/api/stats/sessions/:id/events', async (c) => {
-    const id = parseIntQuery(c.req.param('id'), 0);
-    if (id <= 0) return c.json(statsJson('sessionEvents', []), 400);
+    const id = parsePositiveId(c.req.param('id'));
+    if (id === null) return c.json(statsJson('sessionEvents', []), 400);
     const limit = parseIntQuery(c.req.query('limit'), 500, 1000);
     const eventTypes = parseEventTypesQuery(c.req.query('types'));
     const events = await tracker.getSessionEvents(id, limit, eventTypes);
@@ -101,8 +102,8 @@ export function registerStatsAnalyticsRoutes(
   });
 
   app.get('/api/stats/sessions/:id/known-words-timeline', async (c) => {
-    const id = parseIntQuery(c.req.param('id'), 0);
-    if (id <= 0) return c.json(statsJson('sessionKnownWordsTimeline', []), 400);
+    const id = parsePositiveId(c.req.param('id'));
+    if (id === null) return c.json(statsJson('sessionKnownWordsTimeline', []), 400);
 
     const knownWordsSet = loadKnownWordsSet(options?.knownWordCachePath) ?? new Set<string>();
 
diff --git a/src/core/services/stats-server/integration-routes.ts b/src/core/services/stats-server/integration-routes.ts
index cdc26510..d8c68219 100644
--- a/src/core/services/stats-server/integration-routes.ts
+++ b/src/core/services/stats-server/integration-routes.ts
@@ -1,19 +1,23 @@
-import type { Hono } from 'hono';
+import type { Context, Hono } from 'hono';
 import type { AnkiConnectConfig } from '../../../types.js';
 import {
   statsJson,
   type StatsAnilistSearchResult,
   type StatsAnkiBrowseResponse,
 } from '../../../types/stats-http-contract.js';
+import { isTmdbMediaType } from '../../../shared/media-kind.js';
 import type { AnilistRateLimiter } from '../anilist/rate-limiter.js';
+import { TmdbApiKeyMissingError, type TmdbClient } from '../tmdb/tmdb-client.js';
 import { registerStatsCoverRoutes } from '../stats-cover-routes.js';
 import type { ImmersionTrackerService } from '../immersion-tracker-service.js';
 import {
   buildAnkiNotePreview,
   countKnownWords,
   enrichSessionsWithKnownWordMetrics,
+  isPositiveSafeInteger,
   loadKnownWordsSet,
-  parseIntQuery,
+  parsePositiveId,
+  parsePositiveIdList,
 } from './route-support.js';
 
 const ANKI_CONNECT_FETCH_TIMEOUT_MS = 3_000;
@@ -27,6 +31,7 @@ export function registerStatsIntegrationRoutes(
     ankiConnectConfig?: AnkiConnectConfig;
     getAnkiConnectConfig?: () => AnkiConnectConfig | undefined;
     anilistRateLimiter?: AnilistRateLimiter;
+    tmdbClient?: TmdbClient;
     resolveAnkiNoteId?: (noteId: number) => number;
   },
 ): void {
@@ -71,6 +76,51 @@ export function registerStatsIntegrationRoutes(
     }
   });
 
+  const tmdbUnavailable = (c: Context, err: unknown) => {
+    if (err instanceof TmdbApiKeyMissingError) {
+      return c.json(statsJson('error', { error: err.message }), 503);
+    }
+    return c.json(statsJson('error', { error: 'TMDB request failed' }), 502);
+  };
+
+  app.get('/api/stats/tmdb/search', async (c) => {
+    const query = (c.req.query('q') ?? '').trim();
+    if (!query) return c.json(statsJson('tmdbSearch', []));
+    const tmdbClient = options?.tmdbClient;
+    if (!tmdbClient) return c.json(statsJson('tmdbSearch', []));
+    try {
+      return c.json(statsJson('tmdbSearch', await tmdbClient.search(query)));
+    } catch (err) {
+      return tmdbUnavailable(c, err);
+    }
+  });
+
+  app.patch('/api/stats/anime/:animeId/tmdb', async (c) => {
+    const animeId = parsePositiveId(c.req.param('animeId'));
+    if (animeId === null) return c.body(null, 400);
+    const body = await c.req.json().catch(() => null);
+    const tmdbId = body?.tmdbId;
+    if (
+      typeof tmdbId !== 'number' ||
+      !Number.isInteger(tmdbId) ||
+      tmdbId <= 0 ||
+      !isTmdbMediaType(body?.tmdbType)
+    ) {
+      return c.body(null, 400);
+    }
+    if (!(await tracker.hasAnime(animeId))) return c.body(null, 404);
+    const tmdbClient = options?.tmdbClient;
+    if (!tmdbClient) return c.json(statsJson('error', { error: 'TMDB is not available' }), 503);
+    try {
+      const details = await tmdbClient.getDetails(body.tmdbType, tmdbId);
+      if (!details) return c.body(null, 404);
+      await tracker.reassignAnimeTmdb(animeId, details);
+      return c.json(statsJson('reassignAnimeTmdb', { ok: true }));
+    } catch (err) {
+      return tmdbUnavailable(c, err);
+    }
+  });
+
   app.get('/api/stats/known-words', (c) => {
     const knownWordsSet = loadKnownWordsSet(options?.knownWordCachePath);
     if (!knownWordsSet) return c.json(statsJson('knownWords', []));
@@ -87,8 +137,8 @@ export function registerStatsIntegrationRoutes(
   });
 
   app.get('/api/stats/anime/:animeId/known-words-summary', async (c) => {
-    const animeId = parseIntQuery(c.req.param('animeId'), 0);
-    if (animeId <= 0) {
+    const animeId = parsePositiveId(c.req.param('animeId'));
+    if (animeId === null) {
       return c.json(
         statsJson('animeKnownWordsSummary', { totalUniqueWords: 0, knownWordCount: 0 }),
         400,
@@ -105,8 +155,8 @@ export function registerStatsIntegrationRoutes(
   });
 
   app.get('/api/stats/media/:videoId/known-words-summary', async (c) => {
-    const videoId = parseIntQuery(c.req.param('videoId'), 0);
-    if (videoId <= 0) {
+    const videoId = parsePositiveId(c.req.param('videoId'));
+    if (videoId === null) {
       return c.json(
         statsJson('mediaKnownWordsSummary', { totalUniqueWords: 0, knownWordCount: 0 }),
         400,
@@ -123,14 +173,10 @@ export function registerStatsIntegrationRoutes(
   });
 
   app.patch('/api/stats/anime/:animeId/anilist', async (c) => {
-    const animeId = parseIntQuery(c.req.param('animeId'), 0);
-    if (animeId <= 0) return c.body(null, 400);
+    const animeId = parsePositiveId(c.req.param('animeId'));
+    if (animeId === null) return c.body(null, 400);
     const body = await c.req.json().catch(() => null);
-    if (
-      typeof body?.anilistId !== 'number' ||
-      !Number.isInteger(body.anilistId) ||
-      body.anilistId <= 0
-    ) {
+    if (!isPositiveSafeInteger(body?.anilistId)) {
       return c.body(null, 400);
     }
     await tracker.reassignAnimeAnilist(animeId, body);
@@ -140,8 +186,8 @@ export function registerStatsIntegrationRoutes(
   registerStatsCoverRoutes(app, tracker);
 
   app.get('/api/stats/episode/:videoId/detail', async (c) => {
-    const videoId = parseIntQuery(c.req.param('videoId'), 0);
-    if (videoId <= 0) return c.body(null, 400);
+    const videoId = parsePositiveId(c.req.param('videoId'));
+    if (videoId === null) return c.body(null, 400);
     const rawSessions = await tracker.getEpisodeSessions(videoId);
     const words = await tracker.getEpisodeWords(videoId);
     const cardEvents = await tracker.getEpisodeCardEvents(videoId);
@@ -154,8 +200,8 @@ export function registerStatsIntegrationRoutes(
   });
 
   app.post('/api/stats/anki/browse', async (c) => {
-    const noteId = parseIntQuery(c.req.query('noteId'), 0);
-    if (noteId <= 0) return c.body(null, 400);
+    const noteId = parsePositiveId(c.req.query('noteId'));
+    if (noteId === null) return c.body(null, 400);
     const ankiConfig = getAnkiConnectConfig();
     try {
       const response = await fetch(ankiConfig?.url ?? 'http://127.0.0.1:8765', {
@@ -177,19 +223,14 @@ export function registerStatsIntegrationRoutes(
 
   app.post('/api/stats/anki/notesInfo', async (c) => {
     const body = await c.req.json().catch(() => null);
-    const noteIds: number[] = Array.isArray(body?.noteIds)
-      ? body.noteIds.filter(
-          (id: unknown): id is number => typeof id === 'number' && Number.isInteger(id) && id > 0,
-        )
-      : [];
+    const noteIds = parsePositiveIdList(body?.noteIds);
+    if (!noteIds) return c.body(null, 400);
     if (noteIds.length === 0) return c.json(statsJson('ankiNotesInfo', []));
     const resolvedNoteIds = Array.from(
       new Set(
         noteIds.map((noteId) => {
           const resolvedNoteId = options?.resolveAnkiNoteId?.(noteId);
-          return Number.isInteger(resolvedNoteId) && (resolvedNoteId as number) > 0
-            ? (resolvedNoteId as number)
-            : noteId;
+          return isPositiveSafeInteger(resolvedNoteId) ? resolvedNoteId : noteId;
         }),
       ),
     );
diff --git a/src/core/services/stats-server/library-routes.ts b/src/core/services/stats-server/library-routes.ts
index f705f1ba..7fa20174 100644
--- a/src/core/services/stats-server/library-routes.ts
+++ b/src/core/services/stats-server/library-routes.ts
@@ -1,16 +1,22 @@
 import type { Hono } from 'hono';
 import { statsJson } from '../../../types/stats-http-contract.js';
-import { UNKNOWN_MOVE_TARGET_MESSAGE } from '../immersion-tracker/anime-merge.js';
+import {
+  INCOMPATIBLE_PROVIDER_MERGE_MESSAGE,
+  MEDIA_KIND_MISMATCH_MESSAGE,
+  UNKNOWN_MOVE_TARGET_MESSAGE,
+} from '../immersion-tracker/anime-merge.js';
 import type { ImmersionTrackerService } from '../immersion-tracker-service.js';
 import {
   buildSentenceSearchOptions,
   enrichSessionsWithKnownWordMetrics,
+  isPositiveSafeInteger,
+  loadKnownWordsSet,
   parseBooleanQuery,
   parseDuplicateLineCleanupBody,
   parseExcludedWordsBody,
   parseIntQuery,
+  parsePositiveId,
   parsePositiveIdList,
-  loadKnownWordsSet,
 } from './route-support.js';
 
 export function registerStatsLibraryRoutes(
@@ -113,8 +119,8 @@ export function registerStatsLibraryRoutes(
   });
 
   app.get('/api/stats/vocabulary/:wordId/detail', async (c) => {
-    const wordId = parseIntQuery(c.req.param('wordId'), 0);
-    if (wordId <= 0) return c.body(null, 400);
+    const wordId = parsePositiveId(c.req.param('wordId'));
+    if (wordId === null) return c.body(null, 400);
     const detail = await tracker.getWordDetail(wordId);
     if (!detail) return c.body(null, 404);
     const animeAppearances = await tracker.getWordAnimeAppearances(wordId);
@@ -123,8 +129,8 @@ export function registerStatsLibraryRoutes(
   });
 
   app.get('/api/stats/kanji/:kanjiId/detail', async (c) => {
-    const kanjiId = parseIntQuery(c.req.param('kanjiId'), 0);
-    if (kanjiId <= 0) return c.body(null, 400);
+    const kanjiId = parsePositiveId(c.req.param('kanjiId'));
+    if (kanjiId === null) return c.body(null, 400);
     const detail = await tracker.getKanjiDetail(kanjiId);
     if (!detail) return c.body(null, 404);
     const animeAppearances = await tracker.getKanjiAnimeAppearances(kanjiId);
@@ -138,8 +144,8 @@ export function registerStatsLibraryRoutes(
   });
 
   app.get('/api/stats/media/:videoId', async (c) => {
-    const videoId = parseIntQuery(c.req.param('videoId'), 0);
-    if (videoId <= 0) return c.json(statsJson('error', null), 400);
+    const videoId = parsePositiveId(c.req.param('videoId'));
+    if (videoId === null) return c.json(statsJson('error', null), 400);
     const [detail, rawSessions, rollups] = await Promise.all([
       tracker.getMediaDetail(videoId),
       tracker.getMediaSessions(videoId, 100),
@@ -164,16 +170,16 @@ export function registerStatsLibraryRoutes(
   });
 
   app.delete('/api/stats/anime/merge-recommendations/:recommendationId', async (c) => {
-    const recommendationId = parseIntQuery(c.req.param('recommendationId'), 0);
-    if (recommendationId <= 0) return c.body(null, 400);
+    const recommendationId = parsePositiveId(c.req.param('recommendationId'));
+    if (recommendationId === null) return c.body(null, 400);
     const dismissed = await tracker.dismissAnimeMergeRecommendation(recommendationId);
     if (!dismissed) return c.body(null, 404);
     return c.json(statsJson('dismissAnimeMergeRecommendation', { ok: true }));
   });
 
   app.get('/api/stats/anime/:animeId', async (c) => {
-    const animeId = parseIntQuery(c.req.param('animeId'), 0);
-    if (animeId <= 0) return c.body(null, 400);
+    const animeId = parsePositiveId(c.req.param('animeId'));
+    if (animeId === null) return c.body(null, 400);
     const detail = await tracker.getAnimeDetail(animeId);
     if (!detail) return c.body(null, 404);
     const [episodes, anilistEntries] = await Promise.all([
@@ -184,22 +190,22 @@ export function registerStatsLibraryRoutes(
   });
 
   app.get('/api/stats/anime/:animeId/words', async (c) => {
-    const animeId = parseIntQuery(c.req.param('animeId'), 0);
+    const animeId = parsePositiveId(c.req.param('animeId'));
     const limit = parseIntQuery(c.req.query('limit'), 50, 200);
-    if (animeId <= 0) return c.body(null, 400);
+    if (animeId === null) return c.body(null, 400);
     return c.json(statsJson('animeWords', await tracker.getAnimeWords(animeId, limit)));
   });
 
   app.get('/api/stats/anime/:animeId/rollups', async (c) => {
-    const animeId = parseIntQuery(c.req.param('animeId'), 0);
+    const animeId = parsePositiveId(c.req.param('animeId'));
     const limit = parseIntQuery(c.req.query('limit'), 90, 365);
-    if (animeId <= 0) return c.body(null, 400);
+    if (animeId === null) return c.body(null, 400);
     return c.json(statsJson('animeRollups', await tracker.getAnimeDailyRollups(animeId, limit)));
   });
 
   app.patch('/api/stats/media/:videoId/watched', async (c) => {
-    const videoId = parseIntQuery(c.req.param('videoId'), 0);
-    if (videoId <= 0) return c.body(null, 400);
+    const videoId = parsePositiveId(c.req.param('videoId'));
+    if (videoId === null) return c.body(null, 400);
     const body = await c.req.json().catch(() => null);
     const watched = typeof body?.watched === 'boolean' ? body.watched : true;
     await tracker.setVideoWatched(videoId, watched);
@@ -208,44 +214,56 @@ export function registerStatsLibraryRoutes(
 
   app.delete('/api/stats/sessions', async (c) => {
     const body = await c.req.json().catch(() => null);
-    const ids = Array.isArray(body?.sessionIds)
-      ? body.sessionIds.filter(
-          (id: unknown): id is number => Number.isSafeInteger(id) && (id as number) > 0,
-        )
-      : [];
-    if (ids.length === 0) return c.body(null, 400);
+    const ids = parsePositiveIdList(body?.sessionIds);
+    if (!ids || ids.length === 0) return c.body(null, 400);
     await tracker.deleteSessions(ids);
     return c.json(statsJson('deleteSessions', { ok: true }));
   });
 
   app.delete('/api/stats/sessions/:sessionId', async (c) => {
-    const sessionId = parseIntQuery(c.req.param('sessionId'), 0);
-    if (sessionId <= 0) return c.body(null, 400);
+    const sessionId = parsePositiveId(c.req.param('sessionId'));
+    if (sessionId === null) return c.body(null, 400);
     await tracker.deleteSession(sessionId);
     return c.json(statsJson('deleteSession', { ok: true }));
   });
 
   app.delete('/api/stats/media/:videoId', async (c) => {
-    const videoId = parseIntQuery(c.req.param('videoId'), 0);
-    if (videoId <= 0) return c.body(null, 400);
+    const videoId = parsePositiveId(c.req.param('videoId'));
+    if (videoId === null) return c.body(null, 400);
     await tracker.deleteVideo(videoId);
     return c.json(statsJson('deleteVideo', { ok: true }));
   });
 
   app.delete('/api/stats/anime/:animeId', async (c) => {
-    const animeId = parseIntQuery(c.req.param('animeId'), 0);
-    if (animeId <= 0) return c.body(null, 400);
+    const animeId = parsePositiveId(c.req.param('animeId'));
+    if (animeId === null) return c.body(null, 400);
     await tracker.deleteAnime(animeId);
     return c.json(statsJson('deleteAnime', { ok: true }));
   });
 
   app.post('/api/stats/anime/:animeId/merge', async (c) => {
-    const animeId = parseIntQuery(c.req.param('animeId'), 0);
-    if (animeId <= 0) return c.body(null, 400);
+    const animeId = parsePositiveId(c.req.param('animeId'));
+    if (animeId === null) return c.body(null, 400);
     const body = await c.req.json().catch(() => null);
-    const sourceAnimeIds = parsePositiveIdList(body?.sourceAnimeIds).filter((id) => id !== animeId);
+    const parsedSourceAnimeIds = parsePositiveIdList(body?.sourceAnimeIds);
+    if (!parsedSourceAnimeIds) return c.body(null, 400);
+    const sourceAnimeIds = parsedSourceAnimeIds.filter((id) => id !== animeId);
     if (sourceAnimeIds.length === 0) return c.body(null, 400);
-    const summary = await tracker.mergeAnime(animeId, sourceAnimeIds);
+    let summary: Awaited<ReturnType<typeof tracker.mergeAnime>>;
+    try {
+      summary = await tracker.mergeAnime(animeId, sourceAnimeIds);
+    } catch (error) {
+      // Mixing providers or kinds is a rejected request, not a server fault,
+      // so the dashboard can explain it instead of showing a bare 500.
+      if (
+        error instanceof Error &&
+        (error.message === INCOMPATIBLE_PROVIDER_MERGE_MESSAGE ||
+          error.message === MEDIA_KIND_MISMATCH_MESSAGE)
+      ) {
+        return c.json(statsJson('error', { error: error.message }), 409);
+      }
+      throw error;
+    }
     // Nothing folded means the target or every source was already gone, so the
     // caller should not be told the merge succeeded.
     if (summary.mergedAnimeIds.length === 0) return c.body(null, 404);
@@ -260,11 +278,11 @@ export function registerStatsLibraryRoutes(
   });
 
   app.patch('/api/stats/media/:videoId/anime', async (c) => {
-    const videoId = parseIntQuery(c.req.param('videoId'), 0);
-    if (videoId <= 0) return c.body(null, 400);
+    const videoId = parsePositiveId(c.req.param('videoId'));
+    if (videoId === null) return c.body(null, 400);
     const body = await c.req.json().catch(() => null);
-    const animeId = Number.isSafeInteger(body?.animeId) ? (body.animeId as number) : 0;
-    if (animeId <= 0) return c.body(null, 400);
+    const animeId = body?.animeId;
+    if (!isPositiveSafeInteger(animeId)) return c.body(null, 400);
     try {
       const summary = await tracker.moveVideoToAnime(videoId, animeId);
       return c.json(
@@ -281,6 +299,9 @@ export function registerStatsLibraryRoutes(
       if (error instanceof Error && error.message === UNKNOWN_MOVE_TARGET_MESSAGE) {
         return c.body(null, 404);
       }
+      if (error instanceof Error && error.message === MEDIA_KIND_MISMATCH_MESSAGE) {
+        return c.text(MEDIA_KIND_MISMATCH_MESSAGE, 409);
+      }
       throw error;
     }
   });
diff --git a/src/core/services/stats-server/mining-routes.ts b/src/core/services/stats-server/mining-routes.ts
index d93cc90e..ab31119f 100644
--- a/src/core/services/stats-server/mining-routes.ts
+++ b/src/core/services/stats-server/mining-routes.ts
@@ -4,6 +4,7 @@ import { basename } from 'node:path';
 import { AnkiConnectClient } from '../../../anki-connect.js';
 import { getConfiguredWordFieldName } from '../../../anki-field-config.js';
 import { resolveAnimatedImageLeadInSeconds } from '../../../anki-integration/animated-image-sync.js';
+import { clampMediaEndTime } from '../../../anki-integration/media-duration.js';
 import { MediaGenerator } from '../../../media-generator.js';
 import { statsJson } from '../../../types/stats-http-contract.js';
 import {
@@ -16,7 +17,6 @@ import {
   getStatsDirectMiningAudioFieldNames,
   getStatsWordMiningAudioFieldName,
   resolveStatsNoteFieldName,
-  shouldUseStatsLapisKikuCardFields,
   statsMiningLogger,
   type StatsMiningRouteOptions,
   type StatsServerNoteInfo,
@@ -113,8 +113,7 @@ export function registerStatsMiningRoutes(app: Hono, options?: StatsMiningRouteO
 
     const startSec = startMs / 1000;
     const endSec = endMs / 1000;
-    const rawDuration = endSec - startSec;
-    const clampedEndSec = rawDuration > maxMediaDuration ? startSec + maxMediaDuration : endSec;
+    const clampedEndSec = clampMediaEndTime(startSec, endSec, maxMediaDuration);
 
     const highlightedSentence = word
       ? sentence.replace(
@@ -228,19 +227,11 @@ export function registerStatsMiningRoutes(app: Hono, options?: StatsMiningRouteO
 
       let imageBuffer = imageResult.status === 'fulfilled' ? imageResult.value : null;
       let noteInfo: StatsServerNoteInfo | null = null;
-      if (
-        audioBuffer ||
-        (syncAnimatedImageToWordAudio && generateImage) ||
-        shouldUseStatsLapisKikuCardFields(ankiConfig)
-      ) {
-        try {
-          const noteInfoResult = (await client.notesInfo([noteId])) as StatsServerNoteInfo[];
-          noteInfo = noteInfoResult[0] ?? null;
-        } catch (err) {
-          if (syncAnimatedImageToWordAudio && generateImage) {
-            errors.push(`image: ${(err as Error).message}`);
-          }
-        }
+      try {
+        const noteInfoResult = (await client.notesInfo([noteId])) as StatsServerNoteInfo[];
+        noteInfo = noteInfoResult[0] ?? null;
+      } catch (error) {
+        errors.push(`note fields: ${error instanceof Error ? error.message : String(error)}`);
       }
       if (syncAnimatedImageToWordAudio && generateImage) {
         try {
@@ -272,6 +263,24 @@ export function registerStatsMiningRoutes(app: Hono, options?: StatsMiningRouteO
       const imageFieldName = ankiConfig.fields?.image ?? 'Picture';
 
       mediaFields[sentenceFieldName] = highlightedSentence;
+      const furiganaFieldName = noteInfo
+        ? resolveStatsNoteFieldName(noteInfo, 'SentenceFurigana')
+        : null;
+      if (furiganaFieldName) {
+        let furigana: string | null = null;
+        try {
+          furigana =
+            (await options?.generateSentenceFurigana?.(
+              sentence,
+              ankiConfig.behavior?.highlightWord === false ? undefined : word,
+            )) ?? null;
+        } catch (error) {
+          statsMiningLogger.warn('Failed to generate sentence furigana:', error);
+        }
+        mediaFields[furiganaFieldName] = furigana ?? '';
+        if (furigana === null)
+          errors.push('furigana: unavailable; using the full sentence without readings');
+      }
       applyStatsWordCardFields(mediaFields, noteInfo, ankiConfig);
 
       if (audioBuffer) {
diff --git a/src/core/services/stats-server/mining-support.ts b/src/core/services/stats-server/mining-support.ts
index bdb2c9c8..af986ef8 100644
--- a/src/core/services/stats-server/mining-support.ts
+++ b/src/core/services/stats-server/mining-support.ts
@@ -39,6 +39,7 @@ export type StatsMiningRouteOptions = {
     input: RetimedSecondarySubtitleInput,
   ) => Promise<string> | string;
   addYomitanNote?: (word: string) => Promise<number | null>;
+  generateSentenceFurigana?: (text: string, highlightedText?: string) => Promise<string | null>;
   createMediaGenerator?: () => StatsServerMediaGenerator;
   onMiningTiming?: (event: StatsMiningTimingEvent) => void;
   nowMs?: () => number;
diff --git a/src/core/services/stats-server/request-safety.ts b/src/core/services/stats-server/request-safety.ts
new file mode 100644
index 00000000..0e9e1ac8
--- /dev/null
+++ b/src/core/services/stats-server/request-safety.ts
@@ -0,0 +1,42 @@
+import type { MiddlewareHandler } from 'hono';
+
+function isLoopbackUrl(url: URL): boolean {
+  return (
+    url.protocol === 'http:' &&
+    !url.username &&
+    !url.password &&
+    ['127.0.0.1', 'localhost', '[::1]'].includes(url.hostname)
+  );
+}
+
+/** Protect the local API even when a browser can reach the loopback listener. */
+export const enforceStatsRequestSafety: MiddlewareHandler = async (c, next) => {
+  const url = new URL(c.req.url);
+  if (!isLoopbackUrl(url)) return c.body(null, 403);
+
+  const host = c.req.header('host');
+  if (host !== undefined) {
+    if (!/^(localhost|127\.0\.0\.1|\[::1\])(?::[0-9]+)?$/i.test(host)) {
+      return c.body(null, 403);
+    }
+    // Node derives the request URL from Host; Bun provides them independently.
+    try {
+      if (new URL(`http://${host}`).origin !== url.origin) return c.body(null, 403);
+    } catch {
+      return c.body(null, 403);
+    }
+  }
+
+  // Compare the serialized origin exactly. Opaque origins and malformed values
+  // containing credentials, paths, or multiple origins must not gain trust.
+  const origin = c.req.header('origin');
+  if (origin !== undefined && origin !== url.origin) return c.body(null, 403);
+  const site = c.req.header('sec-fetch-site');
+  if (site === 'cross-site' || site === 'same-site') return c.body(null, 403);
+
+  if (!['GET', 'HEAD', 'OPTIONS'].includes(c.req.method) && c.req.raw.body !== null) {
+    const contentType = c.req.header('content-type')?.split(';', 1)[0]?.trim().toLowerCase();
+    if (contentType !== 'application/json') return c.body(null, 415);
+  }
+  await next();
+};
diff --git a/src/core/services/stats-server/route-support.ts b/src/core/services/stats-server/route-support.ts
index e50ef779..eda46cfc 100644
--- a/src/core/services/stats-server/route-support.ts
+++ b/src/core/services/stats-server/route-support.ts
@@ -48,6 +48,16 @@ export function parseIntQuery(
   return maxLimit === undefined ? parsed : Math.min(parsed, maxLimit);
 }
 
+export function isPositiveSafeInteger(value: unknown): value is number {
+  return typeof value === 'number' && Number.isSafeInteger(value) && value > 0;
+}
+
+export function parsePositiveId(raw: string | undefined): number | null {
+  if (raw === undefined) return null;
+  const value = Number(raw);
+  return isPositiveSafeInteger(value) && String(value) === raw ? value : null;
+}
+
 export function parseTrendRange(raw: string | undefined): '7d' | '30d' | '90d' | '365d' | 'all' {
   return raw === '7d' || raw === '30d' || raw === '90d' || raw === '365d' || raw === 'all'
     ? raw
@@ -199,16 +209,16 @@ export async function enrichSessionsWithKnownWordMetrics<
   );
 }
 
-/** Deduplicated positive integer ids from an untrusted JSON body field. */
-export function parsePositiveIdList(raw: unknown): number[] {
-  if (!Array.isArray(raw)) return [];
+/** Deduplicated positive safe integer ids from an untrusted JSON body field. */
+export function parsePositiveIdList(raw: unknown, maxItems?: number): number[] | null {
+  if (!Array.isArray(raw)) return null;
   const ids = new Set<number>();
   for (const value of raw) {
-    if (Number.isSafeInteger(value) && (value as number) > 0) {
-      ids.add(value as number);
-    }
+    if (!isPositiveSafeInteger(value)) return null;
+    ids.add(value);
   }
-  return [...ids];
+  const parsed = [...ids];
+  return maxItems === undefined ? parsed : parsed.slice(0, maxItems);
 }
 
 export function parseBooleanQuery(raw: string | undefined, fallback: boolean): boolean {
diff --git a/src/core/services/stats-sync/cli-args.test.ts b/src/core/services/stats-sync/cli-args.test.ts
index aa5c8cc1..9a9d83b0 100644
--- a/src/core/services/stats-sync/cli-args.test.ts
+++ b/src/core/services/stats-sync/cli-args.test.ts
@@ -54,6 +54,20 @@ test('parseSyncCliTokens handles the temp-dir protocol modes', () => {
   );
 });
 
+test('transfer cache keys are restricted to temp helpers and cannot contain paths', () => {
+  const key = 'a'.repeat(64);
+  for (const mode of [['--make-temp'], ['--remove-temp', '/tmp/subminer-sync-x']]) {
+    const parsed = parseSyncCliTokens(['sync', ...mode, '--transfer-cache', key]);
+    assert.equal(parsed.kind, 'run');
+    if (parsed.kind === 'run') assert.equal(parsed.args.syncTransferCacheKey, key);
+    assert.equal(
+      parseSyncCliTokens(['sync', ...mode, '--transfer-cache', '../../bad']).kind,
+      'error',
+    );
+  }
+  assert.equal(parseSyncCliTokens(['sync', 'host', '--transfer-cache', key]).kind, 'error');
+});
+
 test('parseSyncCliTokens owns the sync CLI validation rules', () => {
   assert.equal(parseSyncCliTokens([]).kind, 'error');
   assert.equal(parseSyncCliTokens(['sync']).kind, 'error');
diff --git a/src/core/services/stats-sync/cli-args.ts b/src/core/services/stats-sync/cli-args.ts
index 2f865025..050c8b54 100644
--- a/src/core/services/stats-sync/cli-args.ts
+++ b/src/core/services/stats-sync/cli-args.ts
@@ -1,4 +1,5 @@
 import type { SyncFlowArgs } from './sync-flow';
+import { isTransferCacheKey } from './transfer-cache';
 
 export const SYNC_CLI_FLAG = '--sync-cli';
 
@@ -43,6 +44,7 @@ export function parseSyncCliTokens(tokens: readonly string[]): ParsedSyncCli {
   let json = false;
   let makeTemp = false;
   let removeTemp = '';
+  let transferCacheKey = '';
   let remoteCmd = '';
   let dbPath = '';
   let logLevel = 'warn';
@@ -51,6 +53,7 @@ export function parseSyncCliTokens(tokens: readonly string[]): ParsedSyncCli {
     ['--snapshot', (value) => (snapshot = value.trim())],
     ['--merge', (value) => (merge = value.trim())],
     ['--remove-temp', (value) => (removeTemp = value.trim())],
+    ['--transfer-cache', (value) => (transferCacheKey = value.trim())],
     ['--remote-cmd', (value) => (remoteCmd = value.trim())],
     ['--db', (value) => (dbPath = value.trim())],
     ['--log-level', (value) => (logLevel = value.trim() || 'warn')],
@@ -93,6 +96,13 @@ export function parseSyncCliTokens(tokens: readonly string[]): ParsedSyncCli {
   }
 
   if (push && pull) return { kind: 'error', message: 'Sync --push and --pull cannot be combined.' };
+  if (transferCacheKey && (!isTransferCacheKey(transferCacheKey) || (!makeTemp && !removeTemp))) {
+    return {
+      kind: 'error',
+      message:
+        '--transfer-cache requires a 64-character lowercase hex key and --make-temp or --remove-temp.',
+    };
+  }
   if ((push || pull) && !host) {
     return { kind: 'error', message: 'Sync --push and --pull require a host.' };
   }
@@ -137,6 +147,7 @@ export function parseSyncCliTokens(tokens: readonly string[]): ParsedSyncCli {
       syncCheck: check,
       syncMakeTemp: makeTemp,
       syncRemoveTempPath: removeTemp,
+      syncTransferCacheKey: transferCacheKey,
       logLevel,
     },
   };
@@ -161,6 +172,7 @@ export function syncCliUsage(): string {
     '  --check              Test the SSH connection and remote SubMiner availability',
     '  --db <file>          Override the local stats database path',
     '  --remote-cmd <cmd>   SubMiner app or launcher command to run on the remote host',
+    '  --transfer-cache <key>  Reuse/save a received snapshot with temp helpers (internal)',
     '  -f, --force          Skip the running-app safety check',
     '  --json               Emit machine-readable NDJSON progress output',
     '  --log-level <level>  Log level',
diff --git a/src/core/services/stats-sync/merge-catalog.test.ts b/src/core/services/stats-sync/merge-catalog.test.ts
new file mode 100644
index 00000000..526b838c
--- /dev/null
+++ b/src/core/services/stats-sync/merge-catalog.test.ts
@@ -0,0 +1,60 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { Database, type DatabaseSync } from '../immersion-tracker/sqlite';
+import { ensureSchema } from '../immersion-tracker/storage';
+import { mergeAnime } from './merge-catalog';
+import { createEmptyMergeSummary } from './shared';
+
+const identities = {
+  unlinked: [null, null, null],
+  anilist: [42, null, null],
+  tmdb: [null, 12, 'tv'],
+  otherTmdb: [null, 13, 'tv'],
+} as const;
+
+for (const [localKind, remoteKind, sameEntry] of [
+  ['anilist', 'tmdb', false],
+  ['tmdb', 'anilist', false],
+  ['tmdb', 'otherTmdb', false],
+  ['unlinked', 'tmdb', true],
+  ['unlinked', 'anilist', true],
+  ['tmdb', 'unlinked', true],
+  ['tmdb', 'tmdb', true],
+  ['anilist', 'anilist', true],
+] as const) {
+  test(`catalog title match: ${localKind} with ${remoteKind}`, () => {
+    const local = new Database(':memory:');
+    const remote = new Database(':memory:');
+    const adapt = (db: DatabaseSync) => ({
+      query: (sql: string) => db.prepare(sql),
+      exec: (sql: string) => {
+        db.exec(sql);
+      },
+      close: () => {
+        db.close();
+      },
+    });
+    try {
+      for (const [db, kind] of [
+        [local, localKind],
+        [remote, remoteKind],
+      ] as const) {
+        ensureSchema(db);
+        db.prepare(
+          `INSERT INTO imm_anime(normalized_title_key, canonical_title, anilist_id, tmdb_id, tmdb_type, CREATED_DATE, LAST_UPDATE_DATE)
+          VALUES ('same title', 'Same title', ?, ?, ?, 1000, 1000)`,
+        ).run(...identities[kind]);
+      }
+      const summary = createEmptyMergeSummary();
+      const map = mergeAnime(adapt(local), adapt(remote), summary);
+      assert.equal(map.get(1) === 1, sameEntry);
+      assert.equal(summary.animeAdded, sameEntry ? 0 : 1);
+      const again = createEmptyMergeSummary();
+      assert.equal(mergeAnime(adapt(local), adapt(remote), again).get(1), map.get(1));
+      assert.equal(again.animeAdded, 0);
+    } finally {
+      local.close();
+      remote.close();
+    }
+  });
+}
diff --git a/src/core/services/stats-sync/merge-catalog.ts b/src/core/services/stats-sync/merge-catalog.ts
index a58b8d62..c3025441 100644
--- a/src/core/services/stats-sync/merge-catalog.ts
+++ b/src/core/services/stats-sync/merge-catalog.ts
@@ -1,7 +1,9 @@
 import { selectAll, selectOne, type SqlRow, type SyncDb } from './libsql-driver';
 import { insertRow, tableExists, type SyncMergeSummary } from './shared';
+import { sameTitleNamespaceSql } from '../../../shared/media-kind';
 
 const ANIME_COPY_COLUMNS = [
+  'media_kind',
   'normalized_title_key',
   'canonical_title',
   'anilist_id',
@@ -10,6 +12,8 @@ const ANIME_COPY_COLUMNS = [
   'title_native',
   'episodes_total',
   'description',
+  'tmdb_id',
+  'tmdb_type',
   'metadata_json',
   'CREATED_DATE',
   'LAST_UPDATE_DATE',
@@ -98,16 +102,48 @@ export function mergeAnime(
   summary: SyncMergeSummary,
 ): Map<number, number> {
   const map = new Map<number, number>();
-  const byAnilist = local.query('SELECT anime_id FROM imm_anime WHERE anilist_id = ?');
-  const byTitleKey = local.query('SELECT anime_id FROM imm_anime WHERE normalized_title_key = ?');
+  const byAnilist = local.query(
+    "SELECT anime_id FROM imm_anime WHERE anilist_id = ? AND media_kind = 'anime'",
+  );
+  const byTmdb = local.query(
+    'SELECT anime_id FROM imm_anime WHERE tmdb_id = ? AND tmdb_type = ? ORDER BY anime_id LIMIT 1',
+  );
+  // Anime and live-action rows share a title namespace; YouTube channels are
+  // looked up on their own, so a same-named anime and channel stay separate.
+  const byTitleKey = local.query(
+    `SELECT anime_id, anilist_id, tmdb_id, tmdb_type FROM imm_anime
+     WHERE normalized_title_key = ? AND ${sameTitleNamespaceSql()}`,
+  );
+  // A pre-classification channel can be repaired, but a genuine anime sharing
+  // its title must remain a separate entry.
+  const legacyChannel = local.query(`SELECT anime_id FROM imm_anime
+    WHERE normalized_title_key = ? AND media_kind = 'anime' AND (
+      normalized_title_key LIKE 'youtube channel %'
+      OR CASE WHEN json_valid(metadata_json)
+        THEN json_extract(metadata_json, '$.source') = 'youtube-channel' ELSE 0 END
+    )`);
+  const releaseChannelAnilistId = local.query(
+    "UPDATE imm_anime SET anilist_id = NULL WHERE media_kind = 'youtube' AND anilist_id = ?",
+  );
+  // A TMDB link only fills in when the local row is unlinked: a row already
+  // pinned to AniList stays anime, and vice versa, so the two link kinds never
+  // coexist on one entry. A channel match always becomes a channel.
   const fillMissing = local.query(
     `UPDATE imm_anime
      SET
+       anilist_id = CASE WHEN ? = 'youtube' THEN NULL ELSE anilist_id END,
        title_romaji = COALESCE(title_romaji, ?),
        title_english = COALESCE(title_english, ?),
        title_native = COALESCE(title_native, ?),
        episodes_total = COALESCE(episodes_total, ?),
-       description = COALESCE(description, ?)
+       description = COALESCE(description, ?),
+       tmdb_id = CASE WHEN anilist_id IS NULL THEN COALESCE(tmdb_id, ?) ELSE tmdb_id END,
+       tmdb_type = CASE WHEN anilist_id IS NULL AND tmdb_id IS NULL THEN ? ELSE tmdb_type END,
+       media_kind = CASE
+         WHEN ? = 'youtube' THEN 'youtube'
+         WHEN anilist_id IS NULL AND tmdb_id IS NULL THEN ?
+         ELSE media_kind
+       END
      WHERE anime_id = ?`,
   );
 
@@ -116,24 +152,65 @@ export function mergeAnime(
     `SELECT anime_id, ${ANIME_COPY_COLUMNS.join(', ')} FROM imm_anime`,
   )) {
     const remoteId = Number(row.anime_id);
-    const existing = ((row.anilist_id !== null ? byAnilist.get(row.anilist_id) : undefined) ??
-      byTitleKey.get(row.normalized_title_key)) as SqlRow | undefined;
+    if (row.media_kind === 'anime' && row.anilist_id !== null) {
+      // AniList identifiers belong to anime, including when an older peer
+      // incorrectly attached one to a channel.
+      releaseChannelAnilistId.run(row.anilist_id);
+    }
+    const titleMatch = byTitleKey.get(row.normalized_title_key, row.media_kind) as
+      | SqlRow
+      | undefined;
+    const compatibleTitleMatch =
+      titleMatch &&
+      ((titleMatch.anilist_id === null && titleMatch.tmdb_id === null) ||
+        (row.anilist_id === null && row.tmdb_id === null) ||
+        (titleMatch.tmdb_id === null &&
+          row.tmdb_id === null &&
+          titleMatch.anilist_id === row.anilist_id) ||
+        (titleMatch.anilist_id === null &&
+          row.anilist_id === null &&
+          titleMatch.tmdb_id === row.tmdb_id &&
+          titleMatch.tmdb_type === row.tmdb_type));
+    const existing = ((row.media_kind === 'anime' && row.anilist_id !== null
+      ? byAnilist.get(row.anilist_id)
+      : undefined) ??
+      (row.tmdb_id !== null ? byTmdb.get(row.tmdb_id, row.tmdb_type) : undefined) ??
+      (compatibleTitleMatch ? titleMatch : undefined) ??
+      (row.media_kind === 'youtube' ? legacyChannel.get(row.normalized_title_key) : undefined)) as
+      | SqlRow
+      | undefined;
     if (existing) {
       const localId = Number(existing.anime_id);
       map.set(remoteId, localId);
       fillMissing.run(
+        row.media_kind,
         row.title_romaji,
         row.title_english,
         row.title_native,
         row.episodes_total,
         row.description,
+        row.tmdb_id,
+        row.tmdb_type,
+        row.media_kind,
+        row.media_kind,
         localId,
       );
       continue;
     }
-    // No local row matched by anilist_id (checked first in `existing` above)
-    // or title key, so the remote anilist_id — if any — is free to insert as-is.
-    const values = ANIME_COPY_COLUMNS.map((column) => row[column]);
+    // Conflicting providers can share a title, but the stored title key is
+    // unique within its namespace.
+    let titleKey = row.normalized_title_key;
+    for (let suffix = 1; byTitleKey.get(titleKey, row.media_kind); suffix += 1) {
+      titleKey = `${row.normalized_title_key}:sync:${suffix}`;
+    }
+    const values = ANIME_COPY_COLUMNS.map((column) => {
+      if (column === 'normalized_title_key') return titleKey;
+      // No local row matched by anilist_id (checked first in `existing` above)
+      // or title key, so the remote anilist_id is free to insert as-is, except
+      // that channels never carry one.
+      if (column === 'anilist_id' && row.media_kind !== 'anime') return null;
+      return row[column];
+    });
     map.set(remoteId, insertRow(local, 'imm_anime', ANIME_COPY_COLUMNS, values));
     summary.animeAdded += 1;
   }
diff --git a/src/core/services/stats-sync/merge-occurrences.test.ts b/src/core/services/stats-sync/merge-occurrences.test.ts
index 1e0298aa..efc23760 100644
--- a/src/core/services/stats-sync/merge-occurrences.test.ts
+++ b/src/core/services/stats-sync/merge-occurrences.test.ts
@@ -66,7 +66,7 @@ function mergedOccurrences(dbPath: string): Array<{ word: string; seenMs: number
 for (const legacyOccurrences of [false, true]) {
   const label = legacyOccurrences ? 'a peer predating the seen_ms column' : 'a current peer';
 
-  test(`sync merge carries occurrence timestamps in from ${label}`, () => {
+  test(`sync merge carries occurrence timestamps in from ${label}`, { timeout: 15_000 }, () => {
     const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'subminer-merge-occurrences-test-'));
     try {
       const local = buildDb(dir, 'local.sqlite', {
@@ -98,3 +98,122 @@ for (const legacyOccurrences of [false, true]) {
     }
   });
 }
+
+test('sync preserves the YouTube media kind when adding a channel', () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'subminer-sync-youtube-'));
+  try {
+    const localPath = buildDb(dir, 'local.sqlite', {
+      word: '猫',
+      seenMs: BASE_MS,
+      legacyOccurrences: false,
+    });
+    const remotePath = buildDb(dir, 'remote.sqlite', {
+      word: '犬',
+      seenMs: BASE_MS,
+      legacyOccurrences: false,
+    });
+    const remote = new Database(remotePath);
+    remote.exec("UPDATE imm_anime SET media_kind = 'youtube'");
+    remote.close();
+    mergeSnapshotIntoDb(localPath, remotePath);
+    const local = new Database(localPath);
+    try {
+      const row = local
+        .prepare(
+          "SELECT media_kind FROM imm_anime WHERE normalized_title_key = 'key-remote.sqlite'",
+        )
+        .get();
+      assert.ok(row && typeof row === 'object' && 'media_kind' in row);
+      assert.equal(row.media_kind, 'youtube');
+    } finally {
+      local.close();
+    }
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('sync separates same-title kinds and repairs only identifiable legacy channels', () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'subminer-sync-kinds-'));
+  const localPath = buildDb(dir, 'local', {
+    word: 'local',
+    seenMs: BASE_MS,
+    legacyOccurrences: false,
+  });
+  const remotePath = buildDb(dir, 'remote', {
+    word: 'remote',
+    seenMs: BASE_MS,
+    legacyOccurrences: false,
+  });
+  try {
+    const local = new Database(localPath);
+    local.exec(`UPDATE imm_anime SET normalized_title_key = 'shared', anilist_id = 42;
+      INSERT INTO imm_anime(anime_id, normalized_title_key, canonical_title, metadata_json, title_english, LAST_UPDATE_DATE)
+        VALUES (2, 'legacy', 'Local channel', '{"source":"youtube-channel"}', 'Keep local', '9999999999999');
+      UPDATE imm_anime SET anilist_id = 99 WHERE anime_id = 2;
+      INSERT INTO imm_anime(anime_id, normalized_title_key, canonical_title, media_kind, anilist_id)
+        VALUES (3, 'other shared', 'Channel with bad ID', 'youtube', 77);`);
+    local.close();
+    const remote = new Database(remotePath);
+    remote.exec(`UPDATE imm_anime SET normalized_title_key = 'shared', media_kind = 'youtube', anilist_id = 42;
+      INSERT INTO imm_anime(anime_id, normalized_title_key, canonical_title, media_kind, title_english, description, LAST_UPDATE_DATE)
+        VALUES (2, 'legacy', 'Remote channel', 'youtube', 'Remote title', 'Fill missing', '1');
+      INSERT INTO imm_anime(anime_id, normalized_title_key, canonical_title, media_kind, anilist_id)
+        VALUES (3, 'other shared', 'Real anime', 'anime', 77);`);
+    remote.close();
+    mergeSnapshotIntoDb(localPath, remotePath);
+    mergeSnapshotIntoDb(localPath, remotePath);
+    const db = new Database(localPath);
+    try {
+      const rows = db
+        .prepare(
+          'SELECT media_kind FROM imm_anime WHERE normalized_title_key = ? ORDER BY media_kind',
+        )
+        .all('shared');
+      assert.deepEqual(rows, [{ media_kind: 'anime' }, { media_kind: 'youtube' }]);
+      assert.deepEqual(
+        db
+          .prepare(
+            "SELECT media_kind FROM imm_anime WHERE normalized_title_key = 'other shared' ORDER BY media_kind",
+          )
+          .all(),
+        [{ media_kind: 'anime' }, { media_kind: 'youtube' }],
+      );
+      assert.equal(
+        (
+          db.prepare('SELECT media_kind FROM imm_anime WHERE anilist_id = 77').get() as {
+            media_kind: string;
+          }
+        ).media_kind,
+        'anime',
+      );
+      assert.deepEqual(
+        db
+          .prepare(
+            'SELECT media_kind, anilist_id, title_english, description FROM imm_anime WHERE anime_id = 2',
+          )
+          .all()[0],
+        {
+          media_kind: 'youtube',
+          anilist_id: null,
+          title_english: 'Keep local',
+          description: 'Fill missing',
+        },
+      );
+      assert.equal(
+        (
+          db
+            .prepare(
+              "SELECT a.media_kind FROM imm_videos v JOIN imm_anime a ON a.anime_id = v.anime_id WHERE v.video_key = 'video-remote'",
+            )
+            .get() as { media_kind: string }
+        ).media_kind,
+        'youtube',
+      );
+    } finally {
+      db.close();
+    }
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
diff --git a/src/core/services/stats-sync/snapshot-transfer.test.ts b/src/core/services/stats-sync/snapshot-transfer.test.ts
new file mode 100644
index 00000000..e1d2d889
--- /dev/null
+++ b/src/core/services/stats-sync/snapshot-transfer.test.ts
@@ -0,0 +1,238 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import { createSnapshotTransfer, runRsync } from './snapshot-transfer';
+import { createTransferCache, transferCacheKey } from './transfer-cache';
+
+type TransferDeps = NonNullable<Parameters<typeof createSnapshotTransfer>[2]>;
+
+function commandResult(status = 0, stderr = ''): ReturnType<TransferDeps['runRsync']> {
+  return { status, stderr, stdout: '', pid: 0, output: [null, '', stderr], signal: null };
+}
+
+function makeDeps(overrides: Partial<TransferDeps> = {}): TransferDeps {
+  return {
+    platform: 'linux',
+    runRsync: () => commandResult(),
+    runSsh: () => ({ status: 0, stdout: '', stderr: '' }),
+    runScp: () => assert.fail('Unexpected scp fallback'),
+    ...overrides,
+  };
+}
+
+test('snapshot transfer falls back when rsync is unavailable or an endpoint is Windows', () => {
+  for (const scenario of ['local-missing', 'remote-missing', 'local-windows', 'remote-windows']) {
+    const copies: string[][] = [];
+    const transfer = createSnapshotTransfer(
+      'macbook',
+      scenario === 'remote-windows' ? 'windows-cmd' : 'posix',
+      makeDeps({
+        platform: scenario === 'local-windows' ? 'win32' : 'linux',
+        runRsync: () => commandResult(scenario === 'local-missing' ? 1 : 0),
+        runSsh: () => ({ status: scenario === 'remote-missing' ? 127 : 0, stdout: '', stderr: '' }),
+        runScp: (from, to) => copies.push([from, to]),
+      }),
+    );
+    assert.equal(transfer.kind, 'scp', scenario);
+    transfer.copy({
+      direction: 'download',
+      localPath: '/local.sqlite',
+      remotePath: '/remote.sqlite',
+    });
+    transfer.copy({
+      direction: 'upload',
+      localPath: '/local.sqlite',
+      remotePath: '/remote.sqlite',
+    });
+    assert.deepEqual(copies, [
+      ['macbook:/remote.sqlite', '/local.sqlite'],
+      ['/local.sqlite', 'macbook:/remote.sqlite'],
+    ]);
+  }
+});
+
+test('failed rsync transfers report errors without silently retrying through scp', () => {
+  const transfer = createSnapshotTransfer(
+    'macbook',
+    'posix',
+    makeDeps({
+      runRsync: (args) => commandResult(args.includes('--version') ? 0 : 23, 'Permission denied'),
+    }),
+  );
+  assert.throws(
+    () =>
+      transfer.copy({
+        direction: 'upload',
+        localPath: '/local.sqlite',
+        remotePath: '/remote.sqlite',
+      }),
+    /rsync upload failed for macbook: Permission denied/,
+  );
+  assert.throws(() => createSnapshotTransfer('-oProxyCommand=bad', 'posix', makeDeps()), /option/);
+});
+
+const hasRsync = process.platform !== 'win32' && spawnSync('rsync', ['--version']).status === 0;
+
+test(
+  'rsync forces SSH, preserves its environment, and fails on a process timeout',
+  { skip: process.platform === 'win32' },
+  () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'subminer-rsync-process-test-'));
+    const previousPath = process.env.PATH;
+    const previousRsh = process.env.RSYNC_RSH;
+    try {
+      process.env.PATH = `${dir}${path.delimiter}${previousPath ?? ''}`;
+      process.env.RSYNC_RSH = 'unexpected-transport';
+      const executable = path.join(dir, 'rsync');
+      fs.writeFileSync(
+        executable,
+        '#!/bin/sh\nprintf "%s\\n" "$@" "$RSYNC_RSH" "$RSYNC_OLD_ARGS"\n',
+        { mode: 0o700 },
+      );
+      const result = runRsync(['--version']);
+      assert.equal(result.status, 0);
+      assert.deepEqual(result.stdout.trim().split('\n'), [
+        '--rsh=ssh',
+        '--version',
+        'unexpected-transport',
+        '1',
+      ]);
+
+      fs.writeFileSync(executable, '#!/bin/sh\nexec /bin/sleep 5\n');
+      const transfer = createSnapshotTransfer(
+        'macbook',
+        'posix',
+        makeDeps({
+          runRsync: (args) => (args.includes('--version') ? commandResult() : runRsync(args, 50)),
+        }),
+      );
+      assert.throws(
+        () =>
+          transfer.copy({
+            direction: 'download',
+            localPath: '/local.sqlite',
+            remotePath: '/remote.sqlite',
+          }),
+        /rsync download timed out for macbook/,
+      );
+    } finally {
+      if (previousPath === undefined) delete process.env.PATH;
+      else process.env.PATH = previousPath;
+      if (previousRsh === undefined) delete process.env.RSYNC_RSH;
+      else process.env.RSYNC_RSH = previousRsh;
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  },
+);
+
+for (const direction of ['download', 'upload'] as const) {
+  test(
+    `rsync ${direction} reuses snapshot blocks and preserves the basis`,
+    { skip: !hasRsync },
+    () => {
+      const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'subminer-transfer-test-'));
+      try {
+        const localDir = path.join(dir, 'local');
+        const remoteDir = path.join(dir, "remote space ' $(false)");
+        fs.mkdirSync(localDir);
+        fs.mkdirSync(remoteDir);
+        // Emulate SSH's remote shell with real rsync processes, without sshd.
+        const remoteShell = path.join(dir, 'remote-shell');
+        fs.writeFileSync(remoteShell, '#!/bin/sh\nshift\nexec /bin/sh -c "$*"\n', { mode: 0o700 });
+        const localPath = path.join(
+          localDir,
+          direction === 'download' ? 'incoming' : '',
+          'snapshot.sqlite',
+        );
+        const remotePath = path.join(
+          remoteDir,
+          direction === 'upload' ? 'incoming' : '',
+          'snapshot.sqlite',
+        );
+        const source = direction === 'download' ? remotePath : localPath;
+        const destination = direction === 'download' ? localPath : remotePath;
+        const basis = path.join(path.dirname(destination), '..', 'snapshot.sqlite');
+        // Incompressible data ensures savings come from matching blocks.
+        const original = randomBytes(4 * 1024 * 1024);
+        fs.writeFileSync(basis, original);
+        fs.mkdirSync(path.dirname(destination), { recursive: true });
+        fs.writeFileSync(destination, original);
+        const updated = Buffer.from(original);
+        updated.fill(42, 65536, 69632);
+        fs.writeFileSync(source, updated);
+        let stats = '';
+        const transfer = createSnapshotTransfer(
+          'test-peer',
+          'posix',
+          makeDeps({
+            runRsync: (args) => {
+              const result = spawnSync(
+                'rsync',
+                [
+                  `--rsh=${remoteShell}`,
+                  ...args.map((arg) => (arg === '--quiet' ? '--stats' : arg)),
+                ],
+                { encoding: 'utf8', env: { ...process.env, RSYNC_OLD_ARGS: '1', LC_ALL: 'C' } },
+              );
+              stats = result.stdout;
+              return result;
+            },
+          }),
+        );
+        assert.equal(transfer.kind, 'rsync');
+        transfer.copy({ direction, localPath, remotePath });
+        assert.deepEqual(fs.readFileSync(destination), updated);
+        assert.deepEqual(fs.readFileSync(basis), original);
+        const matched = /Matched data: ([\d,]+) (?:bytes|B)/.exec(stats)?.[1];
+        assert.ok(matched, stats);
+        assert.ok(Number(matched.replaceAll(',', '')) > original.length * 0.95, stats);
+
+        const coldDir = path.join(dir, 'cold');
+        fs.mkdirSync(coldDir);
+        const coldDestination = path.join(coldDir, 'incoming', 'snapshot.sqlite');
+        transfer.copy({
+          direction,
+          localPath: direction === 'download' ? coldDestination : localPath,
+          remotePath: direction === 'upload' ? coldDestination : remotePath,
+        });
+        assert.deepEqual(fs.readFileSync(coldDestination), updated);
+
+        // A later sync starts in a new directory and reuses the prior peer's
+        // received file even when the source has grown since that transfer.
+        const cache = createTransferCache(path.join(dir, 'cache'));
+        const key = transferCacheKey('peer');
+        cache.remember(key, direction === 'download' ? localDir : remoteDir);
+        const nextDir = path.join(dir, 'next');
+        cache.seed(key, nextDir);
+        const grown = Buffer.concat([updated, randomBytes(4096)]);
+        fs.writeFileSync(source, grown);
+        const nextDestination = path.join(nextDir, 'incoming', 'snapshot.sqlite');
+        transfer.copy({
+          direction,
+          localPath: direction === 'download' ? nextDestination : localPath,
+          remotePath: direction === 'upload' ? nextDestination : remotePath,
+        });
+        assert.deepEqual(fs.readFileSync(nextDestination), grown);
+        const cachedMatches = /Matched data: ([\d,]+) (?:bytes|B)/.exec(stats)?.[1];
+        assert.ok(cachedMatches, stats);
+        assert.ok(Number(cachedMatches.replaceAll(',', '')) > updated.length * 0.95, stats);
+
+        // A retry must replace stale content even if size and mtime agree.
+        updated.fill(43, 131072, 135168);
+        fs.writeFileSync(source, updated);
+        const timestamp = new Date(1_700_000_000_000);
+        fs.utimesSync(source, timestamp, timestamp);
+        fs.utimesSync(destination, timestamp, timestamp);
+        transfer.copy({ direction, localPath, remotePath });
+        assert.deepEqual(fs.readFileSync(destination), updated);
+        assert.deepEqual(fs.readFileSync(basis), original);
+      } finally {
+        fs.rmSync(dir, { recursive: true, force: true });
+      }
+    },
+  );
+}
diff --git a/src/core/services/stats-sync/snapshot-transfer.ts b/src/core/services/stats-sync/snapshot-transfer.ts
new file mode 100644
index 00000000..d58085fc
--- /dev/null
+++ b/src/core/services/stats-sync/snapshot-transfer.ts
@@ -0,0 +1,85 @@
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+import { assertSafeSshHost, runScp, runSsh, shellQuote, type RemoteShellFlavor } from './ssh';
+
+const RSYNC_OPTIONS = ['--compress', '--checksum'];
+
+export function runRsync(args: string[], timeoutMs = 30 * 60_000) {
+  return spawnSync('rsync', ['--rsh=ssh', ...args], {
+    encoding: 'utf8',
+    stdio: ['inherit', 'pipe', 'pipe'],
+    timeout: timeoutMs,
+    killSignal: 'SIGKILL',
+    // Quote remote paths ourselves for both modern rsync and macOS openrsync.
+    env: { ...process.env, RSYNC_OLD_ARGS: '1' },
+  });
+}
+
+interface TransferDeps {
+  platform: NodeJS.Platform;
+  runRsync: typeof runRsync;
+  runSsh: typeof runSsh;
+  runScp: typeof runScp;
+}
+
+export interface SnapshotTransfer {
+  kind: 'rsync' | 'scp';
+  copy: (request: {
+    direction: 'download' | 'upload';
+    localPath: string;
+    remotePath: string;
+  }) => void;
+}
+
+/**
+ * For rsync, both paths name snapshot.sqlite, with the destination inside an
+ * incoming/ directory seeded from the transfer cache. rsync creates incoming/
+ * when there is no cached basis and verifies the reconstructed file.
+ * Missing rsync and Windows endpoints use compressed scp with ordinary paths.
+ */
+export function createSnapshotTransfer(
+  host: string,
+  flavor: RemoteShellFlavor,
+  deps: TransferDeps = { platform: process.platform, runRsync, runSsh, runScp },
+): SnapshotTransfer {
+  assertSafeSshHost(host);
+  const canUseRsync =
+    deps.platform !== 'win32' &&
+    flavor === 'posix' &&
+    deps.runRsync([...RSYNC_OPTIONS, '--version']).status === 0 &&
+    deps.runSsh(host, `rsync ${RSYNC_OPTIONS.join(' ')} --version`, {
+      batchMode: true,
+      connectTimeoutSeconds: 10,
+      timeoutMs: 15_000,
+    }).status === 0;
+
+  return {
+    kind: canUseRsync ? 'rsync' : 'scp',
+    copy: ({ direction, localPath, remotePath }) => {
+      // A directory destination lets rsync create incoming/ on either end,
+      // including peers running older SubMiner versions.
+      const local =
+        canUseRsync && direction === 'download' ? `${path.dirname(localPath)}/` : localPath;
+      const remoteTarget =
+        canUseRsync && direction === 'upload' ? `${path.posix.dirname(remotePath)}/` : remotePath;
+      const remote = `${host}:${canUseRsync ? shellQuote(remoteTarget) : remoteTarget}`;
+      const [from, to] =
+        direction === 'download' ? ([remote, local] as const) : ([local, remote] as const);
+      if (!canUseRsync) {
+        deps.runScp(from, to);
+        return;
+      }
+      // --checksum prevents a same-size, same-mtime snapshot being skipped.
+      // Without --inplace, rsync replaces the staged basis only after the
+      // reconstructed file passes its transfer checksum.
+      const result = deps.runRsync([...RSYNC_OPTIONS, '--quiet', '--', from, to]);
+      if (result.error && 'code' in result.error && result.error.code === 'ETIMEDOUT') {
+        throw new Error(`rsync ${direction} timed out for ${host}`);
+      }
+      if (result.error) throw new Error(`Failed to run rsync: ${result.error.message}`);
+      if (result.status !== 0) {
+        throw new Error(`rsync ${direction} failed for ${host}: ${result.stderr.trim()}`);
+      }
+    },
+  };
+}
diff --git a/src/core/services/stats-sync/ssh.ts b/src/core/services/stats-sync/ssh.ts
index 99deb1dd..37778d7b 100644
--- a/src/core/services/stats-sync/ssh.ts
+++ b/src/core/services/stats-sync/ssh.ts
@@ -74,7 +74,7 @@ function assertSafeScpEndpoint(endpoint: string): void {
 export function runScp(from: string, to: string): void {
   assertSafeScpEndpoint(from);
   assertSafeScpEndpoint(to);
-  const result = spawnSync('scp', ['-q', from, to], {
+  const result = spawnSync('scp', ['-C', '-q', from, to], {
     encoding: 'utf8',
     stdio: ['inherit', 'inherit', 'inherit'],
   });
diff --git a/src/core/services/stats-sync/sync-flow.test.ts b/src/core/services/stats-sync/sync-flow.test.ts
index 94dc714a..e934457b 100644
--- a/src/core/services/stats-sync/sync-flow.test.ts
+++ b/src/core/services/stats-sync/sync-flow.test.ts
@@ -25,6 +25,7 @@ function makeContext(overrides: Partial<SyncFlowContext['args']> = {}): SyncFlow
       syncCheck: false,
       syncMakeTemp: false,
       syncRemoveTempPath: '',
+      syncTransferCacheKey: '',
       logLevel: 'warn',
       ...overrides,
     },
@@ -46,7 +47,8 @@ function makeDeps(overrides: Partial<SyncFlowDeps> = {}): SyncFlowDeps {
     assertSafeSshHost: () => {},
     detectRemoteShellFlavor: () => 'posix',
     resolveRemoteSubminerCommand: () => 'subminer',
-    runScp: () => {},
+    createSnapshotTransfer: () => ({ kind: 'scp', copy: () => {} }),
+    transferCache: { seed: () => {}, remember: () => {} },
     runSsh: () => ok(),
     canConnectUnixSocket: async () => false,
     realpathSync: (candidate) => candidate,
@@ -116,9 +118,9 @@ test('runSyncFlow dispatches snapshot, merge, host, and missing-target modes', a
       calls.push(`ssh:${command}`);
       return command.includes(' sync --make-temp') ? ok('/tmp/subminer-sync-remote\n') : ok();
     },
-    runScp: (from, to) => {
+    createSnapshotTransfer: scpTransfer((from, to) => {
       calls.push(`scp:${from}->${to}`);
-    },
+    }),
   });
 
   await runSyncFlow(
@@ -146,6 +148,19 @@ test('runSyncFlow dispatches snapshot, merge, host, and missing-target modes', a
   );
 });
 
+function scpTransfer(
+  copy: (from: string, to: string) => void,
+): SyncFlowDeps['createSnapshotTransfer'] {
+  return (host) => ({
+    kind: 'scp',
+    copy: ({ direction, localPath, remotePath }) => {
+      const remote = `${host}:${remotePath}`;
+      if (direction === 'download') copy(remote, localPath);
+      else copy(localPath, remote);
+    },
+  });
+}
+
 function makeHostDeps(calls: string[], overrides: Partial<SyncFlowDeps> = {}): SyncFlowDeps {
   return makeDeps({
     createDbSnapshot: (_dbPath, outPath) => {
@@ -164,10 +179,10 @@ function makeHostDeps(calls: string[], overrides: Partial<SyncFlowDeps> = {}): S
       if (command.includes(' sync --make-temp')) return ok('/tmp/subminer-sync-remote\n');
       return ok();
     },
-    runScp: (from, to) => {
+    createSnapshotTransfer: scpTransfer((from, to) => {
       calls.push(`scp:${from}->${to}`);
       if (!to.includes(':')) fs.writeFileSync(to, 'pulled');
-    },
+    }),
     ...overrides,
   });
 }
@@ -248,6 +263,153 @@ test('runHostSync pull only snapshots remotely and merges locally', async () =>
   assert.ok(!calls.some((call) => call.includes(' sync --merge ')));
 });
 
+for (const direction of ['push', 'pull', 'both'] as const) {
+  test(`runHostSync ${direction} snapshots sources and maintains receiver caches`, async () => {
+    const calls: string[] = [];
+    const copies: string[] = [];
+    const cacheCalls: string[] = [];
+    await runSyncFlow(
+      makeContext({
+        syncDbPath: '/tmp/local.sqlite',
+        syncHost: 'media-box',
+        syncDirection: direction,
+      }),
+      makeHostDeps(calls, {
+        transferCache: {
+          seed: (key) => cacheCalls.push(`seed:${key}`),
+          remember: (key) => cacheCalls.push(`remember:${key}`),
+        },
+        createSnapshotTransfer: () => ({
+          kind: 'rsync',
+          copy: ({ direction: copyDirection, localPath, remotePath }) => {
+            assert.equal(
+              calls.some((call) => call.startsWith('snapshot:')),
+              direction !== 'pull',
+            );
+            assert.equal(
+              calls.some((call) => call.includes(' sync --snapshot ')),
+              direction !== 'push',
+            );
+            if (copyDirection === 'upload')
+              assert.equal(fs.readFileSync(localPath, 'utf8'), 'snapshot');
+            assert.equal(path.posix.basename(remotePath), 'snapshot.sqlite');
+            assert.equal(
+              path.posix.basename(path.posix.dirname(remotePath)),
+              copyDirection === 'upload' ? 'incoming' : 'subminer-sync-remote',
+            );
+            copies.push(copyDirection);
+          },
+        }),
+      }),
+    );
+    assert.deepEqual(
+      copies,
+      direction === 'both'
+        ? ['download', 'upload']
+        : direction === 'pull'
+          ? ['download']
+          : ['upload'],
+    );
+    assert.equal(calls.includes('local-merge'), direction !== 'push');
+    assert.equal(cacheCalls.length, direction === 'push' ? 0 : 2);
+    if (cacheCalls.length) assert.equal(cacheCalls[0]?.slice(5), cacheCalls[1]?.slice(9));
+    const remoteCacheCalls = calls.filter((call) => call.includes('--transfer-cache'));
+    assert.equal(remoteCacheCalls.length, direction === 'pull' ? 0 : 2);
+    if (remoteCacheCalls.length) {
+      assert.ok(remoteCacheCalls[0]?.includes('--make-temp'));
+      assert.ok(remoteCacheCalls[1]?.includes('--remove-temp'));
+      assert.equal(
+        remoteCacheCalls[0]?.split('--transfer-cache ')[1],
+        remoteCacheCalls[1]?.split('--transfer-cache ')[1],
+      );
+    }
+    assert.equal(
+      calls.some((call) => call.includes(' sync --merge ')),
+      direction !== 'pull',
+    );
+  });
+}
+
+test('runHostSync does not merge an incomplete transfer and removes its temp files', async () => {
+  const calls: string[] = [];
+  let localTmpDir = '';
+  await assert.rejects(
+    () =>
+      runSyncFlow(
+        makeContext({ syncDbPath: '/tmp/local.sqlite', syncHost: 'media-box' }),
+        makeHostDeps(calls, {
+          transferCache: {
+            seed: () => {},
+            remember: () => assert.fail('Failed sync must not update cache'),
+          },
+          mkdtempSync: (prefix) => {
+            localTmpDir = fs.mkdtempSync(prefix);
+            return localTmpDir;
+          },
+          createSnapshotTransfer: () => ({
+            kind: 'rsync',
+            copy: () => {
+              throw new Error('connection lost');
+            },
+          }),
+        }),
+      ),
+    /connection lost/,
+  );
+  assert.ok(!calls.includes('local-merge'));
+  assert.ok(!calls.some((call) => call.includes(' sync --merge ')));
+  assert.ok(calls.some((call) => call.includes(' sync --remove-temp ')));
+  assert.equal(fs.existsSync(localTmpDir), false);
+  assert.ok(
+    !calls.some((call) => call.includes('--remove-temp') && call.includes('--transfer-cache')),
+  );
+});
+
+for (const stderr of [
+  'Unknown sync option: --transfer-cache',
+  "error: unknown option '--transfer-cache'\n\nUsage: subminer sync [options] [host]",
+]) {
+  test(`runHostSync falls back when the peer reports ${stderr.split('\n')[0]}`, async () => {
+    const calls: string[] = [];
+    await runSyncFlow(
+      makeContext({ syncDbPath: '/tmp/local.sqlite', syncHost: 'media-box' }),
+      makeHostDeps(calls, {
+        createSnapshotTransfer: () => ({ kind: 'rsync', copy: () => {} }),
+        runSsh: (_host, command) => {
+          calls.push(command);
+          if (command.includes('--transfer-cache')) return { status: 2, stdout: '', stderr };
+          return command.includes('--make-temp') ? ok('/tmp/subminer-sync-remote') : ok();
+        },
+      }),
+    );
+    assert.equal(calls.filter((call) => call.includes('--make-temp')).length, 2);
+    assert.ok(
+      calls.some((call) => call.includes('--remove-temp') && !call.includes('--transfer-cache')),
+    );
+  });
+}
+
+test('runHostSync does not retry unrelated remote temp failures', async () => {
+  const calls: string[] = [];
+  await assert.rejects(
+    runSyncFlow(
+      makeContext({ syncDbPath: '/tmp/local.sqlite', syncHost: 'media-box' }),
+      makeHostDeps(calls, {
+        createSnapshotTransfer: () => ({
+          kind: 'rsync',
+          copy: () => assert.fail('Must not transfer'),
+        }),
+        runSsh: (_host, command) => {
+          calls.push(command);
+          return { status: 1, stdout: '', stderr: 'Permission denied' };
+        },
+      }),
+    ),
+    /Could not create a temporary directory on media-box.*\nPermission denied/,
+  );
+  assert.equal(calls.filter((call) => call.includes('--make-temp')).length, 1);
+});
+
 test('runSyncFlow --json emits NDJSON progress events and a final result', async () => {
   const lines: string[] = [];
   const remoteSummary = {
@@ -436,10 +598,10 @@ test('runHostSync speaks Windows shells: app command, double quotes, temp protoc
       if (command.includes(' sync --make-temp')) return ok(`${winTemp}\r\n`);
       return ok();
     },
-    runScp: (from, to) => {
+    createSnapshotTransfer: scpTransfer((from, to) => {
       scpCalls.push(`${from}->${to}`);
       if (!to.includes(':')) fs.writeFileSync(to, 'pulled');
-    },
+    }),
   });
 
   await runSyncFlow(makeContext({ syncDbPath: '/tmp/local.sqlite', syncHost: 'win-box' }), deps);
diff --git a/src/core/services/stats-sync/sync-flow.ts b/src/core/services/stats-sync/sync-flow.ts
index 415a0cc8..e0fed8ed 100644
--- a/src/core/services/stats-sync/sync-flow.ts
+++ b/src/core/services/stats-sync/sync-flow.ts
@@ -3,6 +3,8 @@ import path from 'node:path';
 import { formatMergeSummary } from './merge';
 import { quoteForRemoteShell } from './ssh';
 import type { RemoteRunResult, RemoteShellFlavor, RunSshOptions } from './ssh';
+import type { createSnapshotTransfer } from './snapshot-transfer';
+import { transferCacheKey, type createTransferCache } from './transfer-cache';
 import {
   parseSyncProgressLine,
   type SyncMergeSummary,
@@ -22,6 +24,7 @@ export interface SyncFlowArgs {
   syncCheck: boolean;
   syncMakeTemp: boolean;
   syncRemoveTempPath: string;
+  syncTransferCacheKey: string;
   logLevel: string;
 }
 
@@ -31,7 +34,7 @@ export interface SyncFlowContext {
 }
 
 /**
- * Process/IO seams the sync flow needs stubbed in tests: SSH/scp, the DB
+ * Process/IO seams the sync flow needs stubbed in tests: SSH/transfers, the DB
  * snapshot/merge engine, filesystem, and progress/bookkeeping output. The
  * app's --sync-cli mode (src/main/sync-cli.ts) provides the only production
  * binding; pure helpers are imported directly.
@@ -51,7 +54,8 @@ export interface SyncFlowDeps {
     flavor: RemoteShellFlavor,
     runRemote?: (host: string, remoteCommand: string) => RemoteRunResult,
   ) => string;
-  runScp: (from: string, to: string) => void;
+  createSnapshotTransfer: typeof createSnapshotTransfer;
+  transferCache: ReturnType<typeof createTransferCache>;
   runSsh: (host: string, remoteCommand: string, options?: RunSshOptions) => RemoteRunResult;
   canConnectUnixSocket: (socketPath: string) => Promise<boolean>;
   realpathSync: (candidate: string) => string;
@@ -95,12 +99,17 @@ function assertRemovableSyncTempDir(target: string): string {
   return resolved;
 }
 
-function runMakeTempMode(deps: SyncFlowDeps): void {
-  deps.consoleLog(makeSyncTempDir(deps.mkdtempSync));
+function runMakeTempMode(context: SyncFlowContext, deps: SyncFlowDeps): void {
+  const dir = makeSyncTempDir(deps.mkdtempSync);
+  if (context.args.syncTransferCacheKey)
+    deps.transferCache.seed(context.args.syncTransferCacheKey, dir);
+  deps.consoleLog(dir);
 }
 
 function runRemoveTempMode(context: SyncFlowContext, deps: SyncFlowDeps): void {
   const target = assertRemovableSyncTempDir(context.args.syncRemoveTempPath);
+  if (context.args.syncTransferCacheKey)
+    deps.transferCache.remember(context.args.syncTransferCacheKey, target);
   deps.rmSync(target, { recursive: true, force: true });
 }
 
@@ -260,9 +269,10 @@ function cleanupRemote(
   remoteTmpDir: string,
   quote: (value: string) => string,
   deps: SyncFlowDeps,
+  cacheFlag = '',
 ): void {
   if (!path.posix.basename(remoteTmpDir).startsWith(SYNC_TEMP_PREFIX)) return;
-  deps.runSsh(host, `${remoteCmd} sync --remove-temp ${quote(remoteTmpDir)}`);
+  deps.runSsh(host, `${remoteCmd} sync --remove-temp ${quote(remoteTmpDir)}${cacheFlag}`);
 }
 
 /**
@@ -309,19 +319,37 @@ export async function runHostSync(
 
   const flavor = deps.detectRemoteShellFlavor(host, deps.runSsh);
   const remoteCmd = deps.resolveRemoteSubminerCommand(host, args.syncRemoteCmd || null, flavor);
+  const transfer = deps.createSnapshotTransfer(host, flavor);
   const quote = (value: string) => quoteForRemoteShell(flavor, value);
   if (args.logLevel === 'debug') {
     console.error(`Remote subminer command (${flavor}): ${remoteCmd}`);
   }
 
   const localTmpDir = makeSyncTempDir(deps.mkdtempSync);
+  const localCacheKey = transferCacheKey(`download\0${dbPath}\0${host}`);
+  const remoteCacheKey = transferCacheKey(`upload\0${os.hostname()}\0${dbPath}`);
+  let remoteCacheFlag = transfer.kind === 'rsync' ? ` --transfer-cache ${remoteCacheKey}` : '';
+  let syncSucceeded = false;
   let remoteTmpDir = '';
   let pulledSummary: SyncMergeSummary | null = null;
   try {
     // Signal failures by throwing (not fail(), which exits synchronously and
     // would skip the finally cleanup, leaking temp dirs holding snapshot data).
     // main().catch() reports the message the same way fail() would.
-    const mktemp = deps.runSsh(host, `${remoteCmd} sync --make-temp`);
+    if (transfer.kind === 'rsync' && shouldPull)
+      deps.transferCache.seed(localCacheKey, localTmpDir);
+    let mktemp = deps.runSsh(
+      host,
+      `${remoteCmd} sync --make-temp${shouldPush ? remoteCacheFlag : ''}`,
+    );
+    if (
+      mktemp.status !== 0 &&
+      (mktemp.stderr.includes('Unknown sync option: --transfer-cache') ||
+        mktemp.stderr.includes("error: unknown option '--transfer-cache'"))
+    ) {
+      remoteCacheFlag = '';
+      mktemp = deps.runSsh(host, `${remoteCmd} sync --make-temp`);
+    }
     remoteTmpDir = mktemp.status === 0 ? parseRemoteTempDir(mktemp.stdout) : '';
     if (!remoteTmpDir) {
       throw new Error(
@@ -331,7 +359,7 @@ export async function runHostSync(
 
     const forceFlag = args.syncForce ? ' --force' : '';
 
-    const localSnapshot = path.join(localTmpDir, 'local.sqlite');
+    const localSnapshot = path.join(localTmpDir, 'snapshot.sqlite');
     if (shouldPush) {
       deps.consoleLog(`Snapshotting local database (${dbPath})...`);
       deps.emitEvent({
@@ -355,19 +383,30 @@ export async function runHostSync(
       }
     }
 
-    const pulledSnapshot = path.join(localTmpDir, 'remote.sqlite');
+    const pulledSnapshot = path.join(
+      localTmpDir,
+      transfer.kind === 'rsync' ? 'incoming/snapshot.sqlite' : 'remote.sqlite',
+    );
     if (shouldPull) {
       deps.emitEvent({
         type: 'stage',
         stage: 'download',
         message: `Copying snapshot from ${host}`,
       });
-      deps.runScp(`${host}:${remoteSnapshot}`, pulledSnapshot);
+      transfer.copy({
+        direction: 'download',
+        remotePath: remoteSnapshot,
+        localPath: pulledSnapshot,
+      });
     }
-    const incomingSnapshot = `${remoteTmpDir}/incoming.sqlite`;
+    const incomingSnapshot = `${remoteTmpDir}/${transfer.kind === 'rsync' ? 'incoming/snapshot.sqlite' : 'incoming.sqlite'}`;
     if (shouldPush) {
       deps.emitEvent({ type: 'stage', stage: 'upload', message: `Copying snapshot to ${host}` });
-      deps.runScp(localSnapshot, `${host}:${incomingSnapshot}`);
+      transfer.copy({
+        direction: 'upload',
+        localPath: localSnapshot,
+        remotePath: incomingSnapshot,
+      });
     }
 
     if (shouldPull) {
@@ -416,6 +455,7 @@ export async function runHostSync(
       }
     }
 
+    syncSucceeded = true;
     deps.consoleLog('\nSync complete.');
     deps.recordHostSyncResult(host, 'success', formatHostSyncDetail(direction, pulledSummary));
   } catch (error) {
@@ -430,10 +470,19 @@ export async function runHostSync(
     }
     throw error;
   } finally {
+    if (syncSucceeded && transfer.kind === 'rsync' && shouldPull)
+      deps.transferCache.remember(localCacheKey, localTmpDir);
     deps.rmSync(localTmpDir, { recursive: true, force: true });
     if (remoteTmpDir) {
       try {
-        cleanupRemote(host, remoteCmd, remoteTmpDir, quote, deps);
+        cleanupRemote(
+          host,
+          remoteCmd,
+          remoteTmpDir,
+          quote,
+          deps,
+          syncSucceeded && shouldPush ? remoteCacheFlag : '',
+        );
       } catch {
         // best effort
       }
@@ -451,7 +500,7 @@ export async function runSyncFlow(
 
   try {
     if (args.syncMakeTemp) {
-      runMakeTempMode(deps);
+      runMakeTempMode(context, deps);
     } else if (args.syncRemoveTempPath) {
       runRemoveTempMode(context, deps);
     } else {
diff --git a/src/core/services/stats-sync/transfer-cache.test.ts b/src/core/services/stats-sync/transfer-cache.test.ts
new file mode 100644
index 00000000..041a6521
--- /dev/null
+++ b/src/core/services/stats-sync/transfer-cache.test.ts
@@ -0,0 +1,59 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { createTransferCache, transferCacheKey } from './transfer-cache';
+
+test('transfer cache isolates peers and active transfers while replacing previous snapshots', () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'subminer-cache-test-'));
+  try {
+    const cacheDir = path.join(root, 'cache');
+    const cache = createTransferCache(cacheDir);
+    const key = transferCacheKey('peer');
+    const first = path.join(root, 'first');
+    fs.mkdirSync(path.join(first, 'incoming'), { recursive: true });
+    const incoming = path.join(first, 'incoming', 'snapshot.sqlite');
+    fs.writeFileSync(incoming, 'first received snapshot');
+    cache.remember(key, first);
+    const second = path.join(root, 'second');
+    cache.seed(key, second);
+    fs.writeFileSync(incoming, 'next received snapshot');
+    cache.remember(key, first);
+    assert.equal(
+      fs.readFileSync(path.join(second, 'incoming', 'snapshot.sqlite'), 'utf8'),
+      'first received snapshot',
+    );
+    const third = path.join(root, 'third');
+    cache.seed(key, third);
+    assert.equal(
+      fs.readFileSync(path.join(third, 'incoming', 'snapshot.sqlite'), 'utf8'),
+      'next received snapshot',
+    );
+    assert.deepEqual(fs.readdirSync(cacheDir), [`${key}.sqlite`]);
+    const other = path.join(root, 'other');
+    cache.seed(transferCacheKey('other peer'), other);
+    assert.equal(fs.existsSync(path.join(other, 'incoming', 'snapshot.sqlite')), false);
+    assert.throws(() => cache.seed('../outside', other), /Invalid/);
+    assert.throws(() => cache.remember('../outside', first), /Invalid/);
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test('unavailable cache storage and missing incoming snapshots do not prevent sync', () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'subminer-cache-test-'));
+  try {
+    const unavailable = path.join(root, 'file');
+    fs.writeFileSync(unavailable, 'not a directory');
+    const cache = createTransferCache(unavailable);
+    const key = transferCacheKey('peer');
+    const temp = path.join(root, 'transfer');
+    assert.doesNotThrow(() => cache.seed(key, temp));
+    assert.doesNotThrow(() => cache.remember(key, temp));
+    fs.writeFileSync(path.join(temp, 'incoming', 'snapshot.sqlite'), 'received');
+    assert.doesNotThrow(() => cache.remember(key, temp));
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
diff --git a/src/core/services/stats-sync/transfer-cache.ts b/src/core/services/stats-sync/transfer-cache.ts
new file mode 100644
index 00000000..91c344b4
--- /dev/null
+++ b/src/core/services/stats-sync/transfer-cache.ts
@@ -0,0 +1,61 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { getDefaultConfigDir } from '../../../shared/setup-state';
+
+export function transferCacheKey(peer: string): string {
+  return createHash('sha256').update(peer).digest('hex');
+}
+
+export function isTransferCacheKey(value: string): boolean {
+  return /^[a-f0-9]{64}$/.test(value);
+}
+
+/**
+ * Keep one previously received snapshot per peer as an rsync basis. Copies
+ * isolate active transfers from concurrent cache replacements. A missing or
+ * unusable cache only costs bandwidth; it must never prevent a sync.
+ */
+export function createTransferCache(
+  directory = path.join(getDefaultConfigDir(), 'sync-transfer-cache'),
+) {
+  function cachePath(key: string): string {
+    if (!isTransferCacheKey(key)) throw new Error('Invalid sync transfer cache key');
+    return path.join(directory, `${key}.sqlite`);
+  }
+
+  return {
+    seed(key: string, tempDir: string): void {
+      const source = cachePath(key);
+      const incoming = path.join(tempDir, 'incoming', 'snapshot.sqlite');
+      try {
+        fs.mkdirSync(path.dirname(incoming), { recursive: true, mode: 0o700 });
+        fs.copyFileSync(source, incoming, fs.constants.COPYFILE_FICLONE);
+      } catch {
+        // A cold transfer sends a complete compressed snapshot.
+      }
+    },
+
+    remember(key: string, tempDir: string): void {
+      const target = cachePath(key);
+      const incoming = path.join(tempDir, 'incoming', 'snapshot.sqlite');
+      let staging = '';
+      try {
+        if (!fs.existsSync(incoming)) return;
+        fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+        staging = fs.mkdtempSync(path.join(directory, '.write-'));
+        const snapshot = path.join(staging, 'snapshot.sqlite');
+        fs.copyFileSync(incoming, snapshot, fs.constants.COPYFILE_FICLONE);
+        fs.renameSync(snapshot, target);
+      } catch {
+        // An older basis is still valid. Never publish a partially copied file.
+      } finally {
+        try {
+          if (staging) fs.rmSync(staging, { recursive: true, force: true });
+        } catch {
+          // Cache cleanup is optional too.
+        }
+      }
+    },
+  };
+}
diff --git a/src/core/services/stats-window-runtime.ts b/src/core/services/stats-window-runtime.ts
index 50bfabe2..db4a52cf 100644
--- a/src/core/services/stats-window-runtime.ts
+++ b/src/core/services/stats-window-runtime.ts
@@ -220,13 +220,8 @@ export function scheduleStatsWindowPostShowReconciles(
   }
 }
 
-export function buildStatsWindowLoadFileOptions(apiBaseUrl?: string): {
-  query: Record<string, string>;
-} {
-  return {
-    query: {
-      overlay: '1',
-      ...(apiBaseUrl ? { apiBase: apiBaseUrl } : {}),
-    },
-  };
+export function buildStatsWindowUrl(apiBaseUrl: string): string {
+  const url = new URL('/', apiBaseUrl);
+  url.searchParams.set('overlay', '1');
+  return url.toString();
 }
diff --git a/src/core/services/stats-window.test.ts b/src/core/services/stats-window.test.ts
index e1359884..ed123482 100644
--- a/src/core/services/stats-window.test.ts
+++ b/src/core/services/stats-window.test.ts
@@ -1,7 +1,7 @@
 import assert from 'node:assert/strict';
 import test from 'node:test';
 import {
-  buildStatsWindowLoadFileOptions,
+  buildStatsWindowUrl,
   buildStatsWindowOptions,
   buildStatsNativeConfirmDialogOptions,
   demoteVisibleStatsWindowBelowDialogs,
@@ -169,21 +169,12 @@ test('shouldHideStatsWindowForInput matches Escape and configured bare toggle ke
   );
 });
 
-test('buildStatsWindowLoadFileOptions enables overlay rendering mode', () => {
-  assert.deepEqual(buildStatsWindowLoadFileOptions(), {
-    query: {
-      overlay: '1',
-    },
-  });
+test('buildStatsWindowUrl enables overlay rendering on the local HTTP origin', () => {
+  assert.equal(buildStatsWindowUrl('http://127.0.0.1:6969'), 'http://127.0.0.1:6969/?overlay=1');
 });
 
-test('buildStatsWindowLoadFileOptions includes provided stats API base URL', () => {
-  assert.deepEqual(buildStatsWindowLoadFileOptions('http://127.0.0.1:6123'), {
-    query: {
-      overlay: '1',
-      apiBase: 'http://127.0.0.1:6123',
-    },
-  });
+test('buildStatsWindowUrl uses the active server port as the document origin', () => {
+  assert.equal(buildStatsWindowUrl('http://127.0.0.1:6123'), 'http://127.0.0.1:6123/?overlay=1');
 });
 
 test('resolveStatsWindowOuterBoundsForContent compensates for Wayland content insets', () => {
diff --git a/src/core/services/stats-window.ts b/src/core/services/stats-window.ts
index 3715c925..ab94af7a 100644
--- a/src/core/services/stats-window.ts
+++ b/src/core/services/stats-window.ts
@@ -1,9 +1,9 @@
 import { BrowserWindow, dialog, ipcMain } from 'electron';
-import * as path from 'path';
+import { createLogger } from '../../logger.js';
 import type { WindowGeometry } from '../../types.js';
 import { IPC_CHANNELS } from '../../shared/ipc/contracts.js';
 import {
-  buildStatsWindowLoadFileOptions,
+  buildStatsWindowUrl,
   buildStatsWindowOptions,
   demoteVisibleStatsWindowBelowDialogs,
   presentStatsWindow,
@@ -26,17 +26,19 @@ import {
 } from './stats-window-layer.js';
 
 let statsWindow: BrowserWindow | null = null;
+let statsWindowGeneration = 0;
 let toggleRegistered = false;
 let nativeDialogLayerRegistered = false;
 const nativeDialogLayerSuspension = createStatsWindowLayerSuspensionState();
+const logger = createLogger('main:stats-window');
 
 export interface StatsWindowOptions {
-  /** Absolute path to stats/dist/ directory */
-  staticDir: string;
   /** Absolute path to the compiled preload-stats.js */
   preloadPath: string;
   /** Resolve the active stats API base URL */
-  getApiBaseUrl?: () => string;
+  getApiBaseUrl: () => Promise<string> | string;
+  /** Report server startup failure through the configured notification surface. */
+  onStartupError?: (error: unknown) => void;
   /** Resolve the active stats toggle key from config */
   getToggleKey: () => string;
   /** Resolve the tracked overlay/mpv bounds */
@@ -179,8 +181,16 @@ function registerStatsNativeDialogLayerHandlers(): void {
  * Toggle the stats overlay window: create on first call, then show/hide.
  * The React app stays mounted across toggles — state is preserved.
  */
-export function toggleStatsOverlay(options: StatsWindowOptions): void {
+export async function toggleStatsOverlay(options: StatsWindowOptions): Promise<void> {
   if (!statsWindow) {
+    const generation = statsWindowGeneration;
+    const apiBaseUrl = await Promise.resolve()
+      .then(() => options.getApiBaseUrl())
+      .catch((error: unknown) => {
+        options.onStartupError?.(error);
+        throw error;
+      });
+    if (generation !== statsWindowGeneration || statsWindow) return;
     statsWindow = new BrowserWindow(
       buildStatsWindowOptions({
         preloadPath: options.preloadPath,
@@ -194,8 +204,7 @@ export function toggleStatsOverlay(options: StatsWindowOptions): void {
       statsWindow?.setTitle(STATS_WINDOW_TITLE);
     });
 
-    const indexPath = path.join(options.staticDir, 'index.html');
-    statsWindow.loadFile(indexPath, buildStatsWindowLoadFileOptions(options.getApiBaseUrl?.()));
+    statsWindow.loadURL(buildStatsWindowUrl(apiBaseUrl));
 
     statsWindow.on('closed', () => {
       options.onVisibilityChanged?.(false);
@@ -243,7 +252,9 @@ export function registerStatsOverlayToggle(options: StatsWindowOptions): void {
   if (toggleRegistered) return;
   toggleRegistered = true;
   ipcMain.on(IPC_CHANNELS.command.toggleStatsOverlay, () => {
-    toggleStatsOverlay(options);
+    void toggleStatsOverlay(options).catch((error: unknown) => {
+      logger.error('Failed to open stats overlay:', error);
+    });
   });
 }
 
@@ -252,6 +263,7 @@ export function registerStatsOverlayToggle(options: StatsWindowOptions): void {
  * Call during app quit.
  */
 export function destroyStatsWindow(): void {
+  statsWindowGeneration += 1;
   if (statsWindow && !statsWindow.isDestroyed()) {
     statsWindow.destroy();
     statsWindow = null;
diff --git a/src/core/services/subtitle-cue-dedup.ts b/src/core/services/subtitle-cue-dedup.ts
index 376a9b2e..6a0b6a25 100644
--- a/src/core/services/subtitle-cue-dedup.ts
+++ b/src/core/services/subtitle-cue-dedup.ts
@@ -149,8 +149,8 @@ function collectRepeatedPhaseRuns(cues: AnnotatedSubtitleCue[]): RepeatedPhaseRu
       const isFlush =
         Math.abs(next.startTime - current.endTime) <= DUPLICATE_CUE_GAP_TOLERANCE_SECONDS;
       if (
-        first.source === 'canonical-ass' ||
-        next.source === 'canonical-ass' ||
+        first.source !== undefined ||
+        next.source !== undefined ||
         next.text !== first.text ||
         assStyleKey(next) !== styleKey ||
         !isFlush
@@ -223,7 +223,7 @@ function countFramesShorterThan(run: AnnotatedSubtitleCue[], maxSeconds: number)
  * anything wrapped in `\t(...)`), an animated `Effect` column, or a value that actually
  * changes from event to event, which is how per-frame typesetting is authored.
  */
-export function hasAssAnimationEvidence(run: AnnotatedSubtitleCue[]): boolean {
+export function hasAssAnimationEvidence(run: readonly AnnotatedSubtitleCue[]): boolean {
   if (run.every((cue) => hasAssTemporalOverride(cue.overrides))) {
     return true;
   }
diff --git a/src/core/services/subtitle-cue-navigation.test.ts b/src/core/services/subtitle-cue-navigation.test.ts
new file mode 100644
index 00000000..00198fb4
--- /dev/null
+++ b/src/core/services/subtitle-cue-navigation.test.ts
@@ -0,0 +1,108 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import {
+  resolveSanitizedSubtitleSeekCommand,
+  subtitleCueListSeekTime,
+  subtitleCueSeekTime,
+} from './subtitle-cue-navigation';
+
+test('next subtitle navigation skips generated ASS events and seeks to the next sanitized cue', () => {
+  const cues = [
+    {
+      startTime: 10,
+      endTime: 13,
+      text: 'first lyric',
+      source: 'canonical-ass' as const,
+      animationStartTime: 9.7,
+      animationEndTime: 13.4,
+    },
+    {
+      startTime: 13,
+      endTime: 16,
+      text: 'second lyric',
+      source: 'canonical-ass' as const,
+      animationStartTime: 12.7,
+      animationEndTime: 16.4,
+    },
+  ];
+
+  assert.deepEqual(resolveSanitizedSubtitleSeekCommand(['sub-seek', 1], cues, 10.2), [
+    'seek',
+    13.08,
+    'absolute+exact',
+  ]);
+});
+
+test('next subtitle navigation treats simultaneous sanitized cues as one line boundary', () => {
+  const cues = [
+    { startTime: 10, endTime: 13, text: 'romaji' },
+    { startTime: 10.02, endTime: 13, text: 'English' },
+    { startTime: 13, endTime: 16, text: 'next romaji' },
+    { startTime: 13.02, endTime: 16, text: 'Next English' },
+  ];
+
+  assert.deepEqual(resolveSanitizedSubtitleSeekCommand(['sub-seek', 1], cues, 10.1), [
+    'seek',
+    13.08,
+    'absolute+exact',
+  ]);
+});
+
+test('next subtitle navigation advances past the latest overlapping lyric', () => {
+  const cues = [
+    { startTime: 10, endTime: 14, text: 'exiting lyric' },
+    { startTime: 13, endTime: 16, text: 'current lyric' },
+    { startTime: 16, endTime: 19, text: 'next lyric' },
+  ];
+
+  assert.deepEqual(resolveSanitizedSubtitleSeekCommand(['sub-seek', 1], cues, 13.2), [
+    'seek',
+    16.08,
+    'absolute+exact',
+  ]);
+});
+
+test('previous subtitle navigation leaves the current cue and seeks to the prior cue', () => {
+  const cues = [
+    { startTime: 10, endTime: 12, text: 'first line' },
+    { startTime: 13, endTime: 16, text: 'current line' },
+  ];
+
+  assert.deepEqual(resolveSanitizedSubtitleSeekCommand(['sub-seek', -1], cues, 14.5), [
+    'seek',
+    10.08,
+    'absolute+exact',
+  ]);
+});
+
+test('subtitle navigation falls back when no sanitized destination exists', () => {
+  const cues = [{ startTime: 10, endTime: 13, text: 'only line' }];
+
+  assert.equal(resolveSanitizedSubtitleSeekCommand(['sub-seek', 1], cues, 10.2), null);
+  assert.equal(resolveSanitizedSubtitleSeekCommand(['seek', 5], cues, 10.2), null);
+});
+
+test('sidebar cue seeks share the boundary-safe sanitized cue timestamp', () => {
+  assert.equal(subtitleCueSeekTime({ startTime: 1, endTime: 2, text: 'line' }), 1.08);
+  assert.equal(subtitleCueSeekTime({ startTime: 1, endTime: 1.04, text: 'short' }), 1.03);
+});
+
+test('sidebar cue selection clears an overlapping previous lyric', () => {
+  const cues = [
+    { startTime: 1, endTime: 3.4, text: 'previous lyric' },
+    { startTime: 3, endTime: 5, text: 'selected lyric' },
+  ];
+
+  assert.equal(subtitleCueListSeekTime(cues, cues[1]!), 3.48);
+});
+
+test('sidebar cue selection remains inside a short cue when overlap cannot be cleared', () => {
+  const cues = [
+    { startTime: 1, endTime: 3.4, text: 'previous lyric' },
+    { startTime: 3, endTime: 3.2, text: 'selected lyric' },
+  ];
+
+  const seekTime = subtitleCueListSeekTime(cues, cues[1]!);
+  assert.ok(seekTime >= 3.19);
+  assert.ok(seekTime < cues[1]!.endTime);
+});
diff --git a/src/core/services/subtitle-cue-navigation.ts b/src/core/services/subtitle-cue-navigation.ts
new file mode 100644
index 00000000..f0248102
--- /dev/null
+++ b/src/core/services/subtitle-cue-navigation.ts
@@ -0,0 +1,128 @@
+import type { SubtitleCue } from './subtitle-cue-parser';
+
+const CUE_START_GROUP_TOLERANCE_SECONDS = 0.05;
+const CUE_BOUNDARY_SEEK_OFFSET_SECONDS = 0.08;
+const CUE_END_GUARD_SECONDS = 0.01;
+
+type CueGroup = {
+  startTime: number;
+  endTime: number;
+  cue: SubtitleCue;
+};
+
+function isValidCue(cue: SubtitleCue): boolean {
+  return (
+    Number.isFinite(cue.startTime) && Number.isFinite(cue.endTime) && cue.endTime > cue.startTime
+  );
+}
+
+function groupCueBoundaries(cues: readonly SubtitleCue[]): CueGroup[] {
+  const sorted = cues.filter(isValidCue).sort((left, right) => {
+    return left.startTime - right.startTime || left.endTime - right.endTime;
+  });
+  const groups: CueGroup[] = [];
+
+  for (const cue of sorted) {
+    const current = groups.at(-1);
+    if (current && cue.startTime - current.startTime <= CUE_START_GROUP_TOLERANCE_SECONDS) {
+      current.endTime = Math.max(current.endTime, cue.endTime);
+      continue;
+    }
+    groups.push({ startTime: cue.startTime, endTime: cue.endTime, cue });
+  }
+
+  return groups;
+}
+
+/** A small offset avoids asking mpv to render exactly on a subtitle boundary. */
+export function subtitleCueSeekTime(cue: SubtitleCue): number {
+  return Math.max(
+    cue.startTime,
+    Math.min(cue.endTime - CUE_END_GUARD_SECONDS, cue.startTime + CUE_BOUNDARY_SEEK_OFFSET_SECONDS),
+  );
+}
+
+/**
+ * Choose a stable point inside a selected cue. Karaoke lines can overlap while the
+ * previous line animates out, so a sidebar selection should clear that overlap when
+ * the selected cue has enough time remaining.
+ */
+export function subtitleCueListSeekTime(
+  cues: readonly SubtitleCue[],
+  selectedCue: SubtitleCue,
+): number {
+  const groups = groupCueBoundaries(cues);
+  const selectedGroupIndex = groups.findIndex(
+    (group) =>
+      selectedCue.startTime >= group.startTime &&
+      selectedCue.startTime - group.startTime <= CUE_START_GROUP_TOLERANCE_SECONDS,
+  );
+  const previousGroupEndTime =
+    selectedGroupIndex > 0 ? groups[selectedGroupIndex - 1]?.endTime : undefined;
+  if (previousGroupEndTime === undefined || previousGroupEndTime <= selectedCue.startTime) {
+    return subtitleCueSeekTime(selectedCue);
+  }
+
+  return Math.max(
+    selectedCue.startTime,
+    Math.min(
+      selectedCue.endTime - CUE_END_GUARD_SECONDS,
+      previousGroupEndTime + CUE_BOUNDARY_SEEK_OFFSET_SECONDS,
+    ),
+  );
+}
+
+/**
+ * Translate mpv subtitle-line navigation onto parsed cues. Generated ASS karaoke can
+ * contain hundreds of subtitle events for one visible line, while the parsed list has
+ * already collapsed those events into the authored lines the user expects to navigate.
+ */
+export function resolveSanitizedSubtitleSeekCommand(
+  command: readonly (string | number)[],
+  cues: readonly SubtitleCue[],
+  currentTimeSec: number,
+): (string | number)[] | null {
+  if (
+    command.length < 2 ||
+    command[0] !== 'sub-seek' ||
+    (command[1] !== -1 && command[1] !== 1) ||
+    !Number.isFinite(currentTimeSec)
+  ) {
+    return null;
+  }
+
+  const groups = groupCueBoundaries(cues);
+  if (groups.length === 0) {
+    return null;
+  }
+
+  let activeIndex = -1;
+  for (const [index, group] of groups.entries()) {
+    if (group.startTime <= currentTimeSec && group.endTime > currentTimeSec) {
+      activeIndex = index;
+    }
+  }
+
+  let destination: CueGroup | undefined;
+  if (command[1] === 1) {
+    destination =
+      activeIndex >= 0
+        ? groups[activeIndex + 1]
+        : groups.find((group) => group.startTime > currentTimeSec);
+  } else if (activeIndex >= 0) {
+    destination = groups[activeIndex - 1];
+  } else {
+    for (let index = groups.length - 1; index >= 0; index -= 1) {
+      const group = groups[index]!;
+      if (group.startTime < currentTimeSec) {
+        destination = group;
+        break;
+      }
+    }
+  }
+
+  if (!destination) {
+    return null;
+  }
+  return ['seek', subtitleCueSeekTime(destination.cue), 'absolute+exact'];
+}
diff --git a/src/core/services/subtitle-cue-parser.test.ts b/src/core/services/subtitle-cue-parser.test.ts
index af9ef6b6..fe4ed0be 100644
--- a/src/core/services/subtitle-cue-parser.test.ts
+++ b/src/core/services/subtitle-cue-parser.test.ts
@@ -35,6 +35,12 @@ test('parseSrtCues handles multi-line subtitle text', () => {
   assert.equal(cues[0]!.text, 'これは\nテストです');
 });
 
+test('parseSrtCues preserves lines that only resemble malformed ASS controls', () => {
+  const content = ['1', '00:01:00,000 --> 00:01:05,000', '\\', '{\\fr0', ''].join('\n');
+
+  assert.equal(parseSrtCues(content)[0]?.text, '\\\n{\\fr0');
+});
+
 test('parseSrtCues strips HTML-like markup while preserving line breaks', () => {
   const content = [
     '1',
@@ -550,6 +556,29 @@ test('parseSubtitleCues recovers a full Dialogue line surrounding generated frag
   ]);
 });
 
+test('parseSubtitleCues replaces animated glyph copies of a static canonical Dialogue line', () => {
+  const content = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    'Dialogue: 1,0:00:01.00,0:00:04.00,OP - JP,,0,0,0,,重複字幕',
+    'Dialogue: 2,0:00:01.00,0:00:04.00,OP - JP,,0,0,0,,{\\pos(400,50)\\t(0,100,\\fry0)}重',
+    'Dialogue: 2,0:00:01.10,0:00:04.00,OP - JP,,0,0,0,,{\\pos(440,50)\\t(0,100,\\fry0)}複',
+    'Dialogue: 2,0:00:01.20,0:00:04.00,OP - JP,,0,0,0,,{\\pos(480,50)\\t(0,100,\\fry0)}字',
+    'Dialogue: 2,0:00:01.30,0:00:04.00,OP - JP,,0,0,0,,{\\pos(520,50)\\t(0,100,\\fry0)}幕',
+  ].join('\n');
+
+  assert.deepEqual(parseSubtitleCues(content, 'test.ass'), [
+    {
+      startTime: 1,
+      endTime: 4,
+      text: '重複字幕',
+      source: 'canonical-ass',
+      animationStartTime: 1,
+      animationEndTime: 4,
+    },
+  ]);
+});
+
 test('parseSubtitleCues does not promote a short animated fragment as a complete line', () => {
   const content = [
     '[Events]',
@@ -570,6 +599,63 @@ test('parseSubtitleCues does not promote a short animated fragment as a complete
   );
 });
 
+test('parseSubtitleCues keeps short animated English dialogue as separate cues', () => {
+  const content = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    'Dialogue: 0,0:00:01.00,0:00:02.00,English Dialogue,,0,0,0,,{\\t(0,100,\\fscx110)}Hi',
+    'Dialogue: 0,0:00:02.00,0:00:03.00,English Dialogue,,0,0,0,,{\\t(0,100,\\fscx110)}No',
+  ].join('\n');
+
+  assert.deepEqual(parseSubtitleCues(content, 'test.ass'), [
+    { startTime: 1, endTime: 2, text: 'Hi' },
+    { startTime: 2, endTime: 3, text: 'No' },
+  ]);
+});
+
+test('parseSubtitleCues does not reconstruct an already canonical English cue', () => {
+  const content = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    'Comment: 0,0:00:01.00,0:00:03.00,OP English,,0,0,0,,{\\move(100,100,120,100)}POOF',
+    'Dialogue: 0,0:00:01.00,0:00:01.04,OP English,,0,0,0,,{\\pos(100,100)\\clip(m 1 1)}POOF',
+    'Dialogue: 0,0:00:01.04,0:00:01.08,OP English,,0,0,0,,{\\pos(100,100)\\clip(m 2 2)}POOF',
+    'Dialogue: 0,0:00:01.08,0:00:03.00,OP English,,0,0,0,,{\\pos(100,100)\\clip(m 3 3)}POOF',
+  ].join('\n');
+
+  assert.deepEqual(parseSubtitleCues(content, 'test.ass'), [
+    {
+      startTime: 1,
+      endTime: 3,
+      text: 'POOF',
+      source: 'canonical-ass',
+      animationStartTime: 1,
+      animationEndTime: 3,
+    },
+  ]);
+});
+
+test('parseSubtitleCues reconstructs a short positioned fragment without a lyric style name', () => {
+  const content = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    'Dialogue: 0,0:00:01.00,0:00:03.00,Karaoke,,0,0,0,,{\\pos(100,100)\\t(0,100,\\fscx110)}Oh',
+    'Dialogue: 1,0:00:01.00,0:00:03.00,Karaoke,,0,0,0,,{\\pos(100,100)\\t(0,100,\\fscx110)}Oh',
+  ].join('\n');
+
+  assert.deepEqual(parseSubtitleCues(content, 'test.ass'), [
+    {
+      startTime: 1,
+      endTime: 3,
+      text: 'Oh',
+      source: 'reconstructed-ass',
+      animationStartTime: 1,
+      animationEndTime: 3,
+      assStyle: 'Karaoke',
+    },
+  ]);
+});
+
 test('parseSubtitleCues ignores timed comments without a matching animated dialogue cluster', () => {
   const content = [
     '[Events]',
@@ -964,3 +1050,1227 @@ test('parseSubtitleCues detects subtitle formats from remote URLs', () => {
   assert.equal(cues.length, 1);
   assert.equal(cues[0]!.text, 'URLテスト');
 });
+
+test('parseSubtitleCues skips zero-duration ASS metadata events', () => {
+  const content = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    'Dialogue: 0,0:00:00.00,0:00:00.00,Default,,0,0,0,,[Script Info]',
+    'Dialogue: 0,0:00:01.00,0:00:02.00,Default,,0,0,0,,Real subtitle',
+  ].join('\n');
+
+  assert.deepEqual(parseSubtitleCues(content, 'test.ass'), [
+    { startTime: 1, endTime: 2, text: 'Real subtitle' },
+  ]);
+});
+
+test('parseSubtitleCues drops malformed ASS spacer reset debris', () => {
+  const content = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    'Dialogue: 0,0:00:01.00,0:00:02.00,Background,,0,0,0,,{\\pos(10,10)}\\h\\h\\h\\{\\fr0',
+    'Dialogue: 1,0:00:01.00,0:00:02.00,Default,,0,0,0,,Visible line',
+  ].join('\n');
+
+  assert.deepEqual(parseSubtitleCues(content, 'test.ass'), [
+    { startTime: 1, endTime: 2, text: 'Visible line' },
+  ]);
+});
+
+test('parseSubtitleCues recovers spaces encoded only by positioned Latin glyph gaps', () => {
+  const glyphs = [
+    ['T', 100],
+    ['h', 118],
+    ['e', 136],
+    ['s', 164],
+    ['t', 178],
+    ['a', 194],
+    ['r', 210],
+    ['s', 227],
+    ['I', 255],
+    ['s', 275],
+    ['e', 293],
+    ['e', 311],
+  ] as const;
+  const content = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    ...[0, 1].flatMap((layer) =>
+      glyphs.map(
+        ([glyph, x], index) =>
+          `Dialogue: ${layer},0:00:01.00,0:00:04.00,OP English,,0,0,0,,{\\pos(${x},110)\\t(${index * 2},${index * 2 + 100},\\fscx120)}${glyph}`,
+      ),
+    ),
+  ].join('\n');
+
+  assert.equal(parseSubtitleCues(content, 'test.ass')[0]?.text, 'The stars I see');
+});
+
+test('parseSubtitleCues does not split narrow letters inside positioned English words', () => {
+  const text = 'carryinghappiness';
+  const positions = [
+    323, 341, 356, 369, 383, 396, 410, 428, 456, 474, 493, 512, 526, 540, 558, 575, 590,
+  ];
+  const content = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    ...[0, 1].flatMap((layer) =>
+      [...text].map(
+        (glyph, index) =>
+          `Dialogue: ${layer},0:00:01.00,0:00:04.00,OP English,,0,0,0,,{\\pos(${positions[index]},110)\\t(${index * 2},${index * 2 + 100},\\fscx120)}${glyph}`,
+      ),
+    ),
+  ].join('\n');
+
+  assert.equal(parseSubtitleCues(content, 'test.ass')[0]?.text, 'carrying happiness');
+});
+
+test('parseSubtitleCues keeps proportional-font variation inside positioned English words', () => {
+  const text = 'sendsripplesacrossthestillnessofyourheart';
+  const positions = [
+    32, 46, 60, 78, 95, 121, 131, 144, 163, 177, 189, 203, 232, 248, 261, 274, 288, 302, 329, 346,
+    363, 390, 405, 416, 423, 432, 443, 457, 471, 485, 512, 525, 551, 564, 579, 593, 622, 639, 655,
+    670, 684,
+  ];
+  const content = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    ...[0, 1].flatMap((layer) =>
+      [...text].map(
+        (glyph, index) =>
+          `Dialogue: ${layer},0:00:01.00,0:00:04.00,Insert English,,0,0,0,,{\\pos(${positions[index]},110)\\t(${index * 2},${index * 2 + 100},\\fscx120)}${glyph}`,
+      ),
+    ),
+  ].join('\n');
+
+  assert.equal(
+    parseSubtitleCues(content, 'test.ass')[0]?.text,
+    'sends ripples across the stillness of your heart',
+  );
+});
+
+test('parseSubtitleCues keeps a short capitalized word when the following gap is larger', () => {
+  const text = 'IfIgrow';
+  const positions = [347, 365, 397, 430, 446, 463, 485];
+  const content = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    ...[0, 1].flatMap((layer) =>
+      [...text].map(
+        (glyph, index) =>
+          `Dialogue: ${layer},0:00:01.00,0:00:04.00,Insert English,,0,0,0,,{\\pos(${positions[index]},110)\\t(${index * 2},${index * 2 + 100},\\fscx120)}${glyph}`,
+      ),
+    ),
+  ].join('\n');
+
+  assert.equal(parseSubtitleCues(content, 'test.ass')[0]?.text, 'If I grow');
+});
+
+// Geometry taken from a real per-glyph ED line. The `waves within` gap crosses a wide
+// `w`, so the width-normalized ratio reads it as a common advance; only the constant
+// extra distance of the authored word space gives it away.
+test('parseSubtitleCues recovers a word gap measured across a wide glyph', () => {
+  const text = 'youcanhearthesoundofthewaveswithinmyheart';
+  const positions = [
+    202, 223, 244, 274, 296, 317, 346, 367, 389, 408, 433, 450, 470, 499, 517, 538, 557, 578, 609,
+    627, 651, 668, 688, 723, 748, 770, 792, 811, 843, 863, 875, 892, 907, 922, 957, 983, 1013, 1034,
+    1055, 1075, 1090,
+  ];
+  const content = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    ...[0, 1].flatMap((layer) =>
+      [...text].map(
+        (glyph, index) =>
+          `Dialogue: ${layer},0:00:01.00,0:00:04.00,ED English,,0,0,0,,{\\pos(${positions[index]},687)\\t(${index * 2},${index * 2 + 100},\\fscx120)}${glyph}`,
+      ),
+    ),
+  ].join('\n');
+
+  assert.equal(
+    parseSubtitleCues(content, 'test.ass')[0]?.text,
+    'you can hear the sound of the waves within my heart',
+  );
+});
+
+// A single short word gives too few gap samples to trust the excess rule: its narrow
+// glyphs skew the common advance low and `w e` would read as a word gap.
+test('parseSubtitleCues does not split a short single positioned word', () => {
+  const text = 'Swelling';
+  const positions = [592, 613, 635, 647, 655, 662, 673, 689];
+  const content = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    ...[0, 1].flatMap((layer) =>
+      [...text].map(
+        (glyph, index) =>
+          `Dialogue: ${layer},0:00:01.00,0:00:04.00,ED English,,0,0,0,,{\\pos(${positions[index]},682)\\t(${index * 2},${index * 2 + 100},\\fscx120)}${glyph}`,
+      ),
+    ),
+  ].join('\n');
+
+  assert.equal(parseSubtitleCues(content, 'test.ass')[0]?.text, 'Swelling');
+});
+
+// A capitalized word whose first letter sits before a wide glyph (`S|miles`) overruns
+// the width table; the excess rule must not split a capital from its lowercase run.
+test('parseSubtitleCues keeps a capitalized word intact under the excess rule', () => {
+  const text = 'Smilesarebudding';
+  const positions = [37, 63, 80, 88, 99, 113, 142, 157, 171, 201, 217, 235, 255, 269, 280, 295];
+  const content = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    ...[0, 1].flatMap((layer) =>
+      [...text].map(
+        (glyph, index) =>
+          `Dialogue: ${layer},0:00:01.00,0:00:04.00,ED English,,0,0,0,,{\\pos(${positions[index]},682)\\t(${index * 2},${index * 2 + 100},\\fscx120)}${glyph}`,
+      ),
+    ),
+  ].join('\n');
+
+  assert.equal(parseSubtitleCues(content, 'test.ass')[0]?.text, 'Smiles are budding');
+});
+
+// Mirrors a real ED: per-syllable romaji at y=34 overlaid with animated single letters
+// at y=29 rendered through `\fn` in a symbol font, where `a` draws as a sparkle. The
+// letters must neither join the reconstructed line nor survive as their own cues.
+test('parseSubtitleCues drops symbol-font glyph decoration from a reconstructed line', () => {
+  const syllables = [
+    ['so', 479],
+    ['t', 505],
+    ['to', 529],
+    ['mi', 577],
+    ['mi', 618],
+    ['ni', 663],
+    ['a', 699],
+    ['te', 728],
+    ['ru', 764],
+    ['to', 810],
+  ] as const;
+  const decoration = [
+    ['a', 479, '0:00:01.25'],
+    ['z', 577, '0:00:02.51'],
+    ['x', 618, '0:00:02.78'],
+    ['q', 505, '0:00:04.20'],
+  ] as const;
+  const content = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    ...[0, 1].flatMap((layer) =>
+      syllables.map(
+        ([syllable, x], index) =>
+          `Dialogue: ${layer},0:00:01.00,0:00:05.37,ED Romaji,,0,0,0,fx,{\\an5\\pos(${x},34)\\t(${index * 2},${index * 2 + 100},\\fscx120)}${syllable}`,
+      ),
+    ),
+    ...decoration.map(
+      ([glyph, x, start]) =>
+        `Dialogue: 0,${start},0:00:05.37,ED Romaji,,0,0,0,fx,{\\pos(${x},29)\\fnSplit splat splodge\\fs28\\t(3870,3970,\\fscx105)}${glyph}`,
+    ),
+  ].join('\n');
+
+  const cues = parseSubtitleCues(content, 'test.ass');
+  assert.equal(cues.length, 1);
+  assert.equal(cues[0]?.text, 'sotto mimi ni ateru to');
+});
+
+test('parseSubtitleCues drops clipped repeated-glyph texture text', () => {
+  const content = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    "Dialogue: 10,0:00:01.00,0:00:04.00,Default,,0,0,0,,I'm blocking them.",
+    'Dialogue: 2,0:00:01.00,0:00:04.00,MarySigns,,0,0,0,,{\\pos(960,80)\\fnSerangkaian Pattern Regular\\clip(800,20,1120,140)}LLLLLLLLLLLLLLLLLLLLLLLL',
+    'Dialogue: 3,0:00:01.00,0:00:04.00,MarySigns,,0,0,0,,{\\pos(960,150)\\fnSF Pro Display}Enter a message',
+  ].join('\n');
+
+  assert.deepEqual(
+    parseSubtitleCues(content, 'test.ass').map((cue) => cue.text),
+    ["I'm blocking them.", 'Enter a message'],
+  );
+});
+
+test('parseSubtitleCues preserves opaque same-font text beside texture fragments', () => {
+  const content = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    'Dialogue: 2,0:00:01.00,0:00:04.00,MarySigns,seed,0,0,0,,{\\pos(960,80)\\fnSerangkaian Pattern Regular\\clip(800,20,1120,140)}LLLLLLLLLLLLLLLLLLLLLLLL',
+    'Dialogue: 2,0:00:01.00,0:00:04.00,MarySigns,piece,0,0,0,,{\\pos(960,110)\\fnSerangkaian Pattern Regular\\clip(800,20,1120,140)}LLLL',
+    'Dialogue: 3,0:00:01.00,0:00:04.00,MarySigns,label,0,0,0,,{\\pos(960,150)\\fnSerangkaian Pattern Regular}Keep this label',
+  ].join('\n');
+
+  assert.deepEqual(
+    parseSubtitleCues(content, 'test.ass').map((cue) => cue.text),
+    ['Keep this label'],
+  );
+});
+
+test('parseSubtitleCues drops tiny alpha payloads from a proven texture font', () => {
+  const content = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    'Dialogue: 2,0:00:01.00,0:00:04.00,FrogSigns,,0,0,0,,{\\pos(580,95)\\fnGrain Medium\\clip(500,40,660,150)}LLLLLLLLLLLL',
+    "Dialogue: 1,0:00:06.00,0:00:09.00,FrogSigns,,0,0,0,,{\\pos(580,95)\\fnGrain\\fs10\\alpha&H70&}q26D'vrA;\\NE? GS\\NESLhlawEv",
+    'Dialogue: 3,0:00:06.00,0:00:09.00,FrogSigns,,0,0,0,,{\\pos(1040,620)\\fnSF Pro Display\\fs66}Waiting!',
+  ].join('\n');
+
+  assert.deepEqual(
+    parseSubtitleCues(content, 'test.ass').map((cue) => cue.text),
+    ['Waiting!'],
+  );
+});
+
+test('parseSubtitleCues preserves a small multiline translation using an unverified transparent font', () => {
+  const content = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    'Dialogue: 2,0:00:01.00,0:00:04.00,Transition,,0,0,0,,{\\pos(580,95)\\fnPhone UI\\fs60\\alpha&HF0&}Faded transition',
+    'Dialogue: 3,0:00:06.00,0:00:09.00,Phone,,0,0,0,,{\\pos(1040,620)\\fnPhone UI\\fs10\\alpha&H70&}Call me when you arrive.\\NI will still be awake.\\NDo not rush.',
+  ].join('\n');
+
+  assert.deepEqual(
+    parseSubtitleCues(content, 'test.ass').map((cue) => cue.text),
+    ['Faded transition', 'Call me when you arrive.\nI will still be awake.\nDo not rush.'],
+  );
+});
+
+test('parseSubtitleCues drops clipped repeated-glyph texture text without a font override', () => {
+  const content = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    'Dialogue: 0,0:00:01.00,0:00:04.00,FrogSigns,,0,0,0,,{\\an7\\pos(736.49,152.99)\\fscy150\\fs10\\bord3\\c&H657BC8&\\3c&H657BC8&\\blur3\\clip}lllllllllllll',
+    'Dialogue: 0,0:00:01.00,0:00:04.00,FrogSigns,,0,0,0,,{\\an7\\pos(769.9,106.18)\\fscy150\\fs12\\bord3\\c&H66729F&\\3c&H66729F&\\blur5\\clip}llll',
+    'Dialogue: 5,0:00:01.00,0:00:04.00,FrogSigns,,0,0,0,,{\\pos(893,311)}Read',
+  ].join('\n');
+
+  assert.deepEqual(
+    parseSubtitleCues(content, 'test.ass').map((cue) => cue.text),
+    ['Read'],
+  );
+});
+
+test('parseSubtitleCues drops per-character alpha texture text', () => {
+  const content = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    "Dialogue: 10,0:00:01.00,0:00:04.00,Default,Girl,0,0,0,,So Doloris was actually Uika-chan from sumimi! That's amazing!",
+    "Dialogue: 2,0:00:01.00,0:00:04.00,MarySigns,,0,0,0,,{\\pos(960,240)\\fnCinzel}Hanasakigawa Girl's School",
+    'Dialogue: 3,0:00:01.00,0:00:04.00,MarySigns,,0,0,0,,{\\pos(960,300)\\fnSplit splat splodge\\clip(800,200,1120,400)}d{\\2a1}s{\\2a0}h{\\2a1}f{\\2a0}k{\\2a1}h{\\2a0}f{\\2a1}s{\\2a0}d{\\2a1}f{\\2a0}e',
+    'Dialogue: 3,0:00:01.00,0:00:04.00,MarySigns,,0,0,0,,{\\pos(980,340)\\fnSplit splat splodge}f {\\2a1}a',
+    'Dialogue: 4,0:00:01.00,0:00:04.00,MarySigns,,0,0,0,,{\\pos(960,360)\\fnGrain SemiBold}5{\\2a1}X{\\2a0}N{\\2a1}T{\\2a0}f{\\2a1}I{\\2a0}g{\\2a1}F{\\2a0}B{\\2a1}?{\\2a0}k{\\2a1}u{\\2a0}C{\\2a1}m',
+  ].join('\n');
+
+  assert.deepEqual(
+    parseSubtitleCues(content, 'test.ass').map((cue) => cue.text),
+    [
+      "So Doloris was actually Uika-chan from sumimi! That's amazing!",
+      "Hanasakigawa Girl's School",
+    ],
+  );
+});
+
+test('parseSubtitleCues drops transparent texture payloads across an animated sign', () => {
+  const content = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    "Dialogue: 90,0:00:01.00,0:00:04.00,Alt,,0,0,0,,Even if you want to see her, she doesn't want to see you!",
+    'Dialogue: 0,0:00:01.00,0:00:01.08,FrogSigns,,0,0,0,,{\\pos(699,803)\\fnSerangkaian Pattern Regular\\clip(300,380,1130,1050)}L{\\2a1}L{\\2a0}L{\\2a1}L{\\2a0}L{\\2a0}L{\\2a0}L{\\2a1}L{\\2a0}L{\\2a1}L{\\2a0}L{\\2a1}L{\\2a0}L{\\2a1}L{\\2a0}L{\\\\\\\\\\\\\\\\\\\\\\',
+    'Dialogue: 3,0:00:01.00,0:00:01.08,FrogSigns,Street,0,0,0,,{\\pos(285,653)\\fnGrain\\alpha&HE0&}Street performance by Mortis from\\NMujica - Acting prodigy in action!',
+    'Dialogue: 5,0:00:01.00,0:00:01.08,FrogSigns,Street,0,0,0,,{\\pos(285,653)\\fnRoboto Medium\\alpha&H00&}Street performance by Mortis from\\NMujica - Acting prodigy in action!',
+    'Dialogue: 6,0:00:01.00,0:00:01.08,FrogSigns,Street,0,0,0,,{\\pos(285,653)\\fnGrain\\alpha&HE0&}H1.4igcAhGYHVWD"kHcVlG2W9eKEWj"!X\\N\'uNVaEVpTXMd9rk7dnRX\'P!RhsS"Wn90k6',
+    'Dialogue: 6,0:00:01.00,0:00:01.08,FrogSigns,18K,0,0,0,,{\\pos(284,821)\\fnGrain\\alpha&HE0&}ou:QepiiPqQ.4n.IYbFaGHtPzWyKI9CUSq:',
+    'Dialogue: 1,0:00:01.08,0:00:04.00,FrogSigns,,0,0,0,,{\\pos(581,921)\\fnSerangkaian Pattern Regular\\clip(195,495,986,1120)}L{\\2a1}L{\\2a0}L{\\2a1}L{\\2a0}L{\\2a1}L{\\2a0}L{\\2a1}L{\\2a0}L{\\2a1}L{\\2a0}L{\\2a1}L{\\2a0}L{',
+    'Dialogue: 3,0:00:01.08,0:00:04.00,FrogSigns,,0,0,0,,{\\pos(151,769)\\fnGrain\\alpha&HE0&}Street performance by Mortis from\\NMujica - Acting prodigy in action!',
+    'Dialogue: 5,0:00:01.08,0:00:04.00,FrogSigns,,0,0,0,,{\\pos(151,769)\\fnRoboto Medium\\alpha&H00&}Street performance by Mortis from\\NMujica - Acting prodigy in action!',
+    'Dialogue: 3,0:00:01.08,0:00:04.00,FrogSigns,,0,0,0,,{\\pos(151,769)\\fnGrain\\alpha&HF0&}9LF\'GpPCTlOkLxBLV:QN,8R8NUVM"ha.s\\NNUUPNTBdJih4jUthK34i,yYe;9EBgLXbET',
+    "Dialogue: 6,0:00:01.08,0:00:04.00,FrogSigns,,0,0,0,,{\\pos(150,936)\\fnGrain\\alpha&HE0&}JS7vl:lD;'PzkCb!bGT;.7TbA.KCkEH0LOk",
+  ].join('\n');
+
+  assert.deepEqual(
+    parseSubtitleCues(content, 'test.ass').map((cue) => cue.text),
+    [
+      'Street performance by Mortis from\nMujica - Acting prodigy in action!',
+      "Even if you want to see her, she doesn't want to see you!",
+      'Street performance by Mortis from\nMujica - Acting prodigy in action!',
+    ],
+  );
+});
+
+test('parseSubtitleCues does not reconstruct short texture pieces under another actor', () => {
+  const content = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    'Dialogue: 4,0:00:01.00,0:00:04.00,FrogSigns,bubble,0,0,0,,{\\pos(245,-102)\\fnSerangkaian Pattern Regular\\clip(224,-1,831,106)}L{\\2a1}L{\\2a0}L{\\2a1}L{\\2a0}L{\\2a1}L{\\2a0}L{\\2a1}L{\\2a0}L{\\2a1}L',
+    'Dialogue: 4,0:00:01.00,0:00:04.00,FrogSigns,read,0,0,0,,{\\pos(917,293)\\alpha&H20&\\fnSerangkaian Pattern Regular\\clip(904,289,1010,336)}L{\\2a0}L{\\2a1}L{\\2a0}L',
+    'Dialogue: 4,0:00:01.00,0:00:04.00,FrogSigns,read,0,0,0,,{\\pos(911,293)\\alpha&H58&\\fnSerangkaian Pattern Regular\\clip(904,289,1010,336)}L{\\2a0}L{\\2a1}L{\\2a0}L',
+    'Dialogue: 4,0:00:01.00,0:00:04.00,FrogSigns,read,0,0,0,,{\\pos(845,300)\\alpha&H00&\\fnSerangkaian Pattern Regular\\clip(904,289,1010,336)}L{\\2a0}L{\\2a1}L{\\2a0}L',
+    'Dialogue: 7,0:00:01.00,0:00:04.00,FrogSigns,read,0,0,0,,{\\pos(907,293)\\alpha&HD0&\\fnSerangkaian Pattern Regular\\clip(891,289,1010,338)}L{\\2a0}L{\\2a1}L{\\2a0}L',
+    'Dialogue: 7,0:00:01.00,0:00:04.00,FrogSigns,read,0,0,0,,{\\pos(911,293)\\alpha&HD0&\\fnSerangkaian Pattern Regular\\clip(891,289,1010,338)}L{\\2a0}L{\\2a1}L{\\2a0}L',
+    'Dialogue: 7,0:00:01.00,0:00:04.00,FrogSigns,read,0,0,0,,{\\pos(922,130)\\alpha&HD0&\\fnSerangkaian Pattern Regular\\clip(891,120,1010,173)}L{\\2a0}L{\\2a1}L{\\2a0}L',
+    'Dialogue: 5,0:00:01.00,0:00:04.00,FrogSigns,,0,0,0,,{\\pos(893,311)\\fnSFProDisplay-Regular-STR}Read 3',
+  ].join('\n');
+
+  assert.deepEqual(
+    parseSubtitleCues(content, 'test.ass').map((cue) => cue.text),
+    ['Read 3'],
+  );
+});
+
+test('parseSubtitleCues separates overlapping positioned English lyric sequences', () => {
+  const fragments = [
+    ['my', 642, '0:00:01.00', '0:00:04.05'],
+    ['song!', 713, '0:00:01.00', '0:00:04.05'],
+    ['I', 533, '0:00:01.67', '0:00:04.09'],
+    ['h', 557, '0:00:01.67', '0:00:04.09'],
+    ['u', 575, '0:00:01.67', '0:00:04.09'],
+    ['m', 597, '0:00:01.67', '0:00:04.09'],
+  ] as const;
+  const content = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    ...[0, 1].flatMap((layer) =>
+      fragments.map(
+        ([text, x, start, end], index) =>
+          `Dialogue: ${layer},${start},${end},OP English,,0,0,0,,{\\pos(${x},110)\\t(${index * 2},${index * 2 + 100},\\fscx120)}${text}`,
+      ),
+    ),
+  ].join('\n');
+
+  assert.equal(parseSubtitleCues(content, 'test.ass')[0]?.text, 'my song! I hum');
+});
+
+const eventsHeader = [
+  '[Events]',
+  'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+];
+
+test('parseSubtitleCues keeps tall CC-style base dialogue publishable after removing furigana', () => {
+  const content = [
+    ...eventsHeader,
+    'Dialogue: 0,0:00:06.11,0:00:10.11,Default,,0,0,0,,{\\pos(212,383)\\fscx50\\fscy50}たき',
+    'Dialogue: 0,0:00:06.11,0:00:10.11,Default,,0,0,0,,{\\pos(172,437)\\fscx50}（{\\fscx100}立希{\\fscx50}）',
+    'Dialogue: 0,0:00:06.11,0:00:10.11,Default,,0,0,0,,{\\pos(332,443)\\fscx50\\fscy50}ともり',
+    'Dialogue: 0,0:00:06.11,0:00:10.11,Default,,0,0,0,,{\\pos(192,497)}お前…{\\fscx50}　{\\fscx100}燈をバンドに誘ったの？',
+    // A second labeled turn, so the script reads as broadcast captions.
+    'Dialogue: 0,0:00:10.11,0:00:12.00,Default,,0,0,0,,{\\pos(192,497)\\fscx50}（{\\fscx100}燈{\\fscx50}）{\\fscx100}うん。',
+  ].join('\n');
+
+  const cues = parseSubtitleCues(content, 'test.ass');
+  // The bare speaker label row joins the dialogue row beneath it as one cue.
+  assert.deepEqual(
+    cues.map((cue) => cue.text),
+    ['（立希）\nお前…　燈をバンドに誘ったの？', '（燈）うん。'],
+  );
+  assert.deepEqual(cues[0]?.assFurigana, ['たき', 'ともり']);
+  assert.ok(cues.every((cue) => cue.assLayout?.kind === 'positioned'));
+});
+
+test('parseSubtitleCues removes half-size positioned furigana from broadcast captions', () => {
+  const content = [
+    '[Script Info]',
+    'PlayResY: 540',
+    '',
+    ...eventsHeader,
+    'Dialogue: 0,0:02:38.20,0:02:41.87,Default,,0,0,0,,{\\pos(192,77)\\fscx50}（{\\fscx100}山田{\\fscx50}）{\\fscx100}ごめん{\\fscx50}　{\\fscx100}結局{\\fscx50}　{\\fscx100}ぬれたな{\\fscx50}。',
+    'Dialogue: 0,0:02:38.20,0:02:41.87,Default,,0,0,0,,{\\pos(552,113)\\fscx50\\fscy50}だいじょうぶ',
+    'Dialogue: 0,0:02:38.20,0:02:41.87,Default,,0,0,0,,{\\pos(552,167)}大丈夫{\\fscx50}。',
+    'Dialogue: 0,0:03:51.34,0:03:53.68,Default,,0,0,0,,{\\pos(232,407)\\fscx50}（{\\fscx100}山田の母{\\fscx50}）{\\fscx100}ほんなら',
+    'Dialogue: 0,0:03:51.34,0:03:53.68,Default,,0,0,0,,{\\pos(232,443)\\fscx50\\fscy50}かく',
+    'Dialogue: 0,0:03:51.34,0:03:53.68,Default,,0,0,0,,{\\pos(312,443)\\fscx50\\fscy50}ちょぞう',
+    'Dialogue: 0,0:03:51.34,0:03:53.68,Default,,0,0,0,,{\\pos(232,497)}隠し貯蔵のミルクまんじゅう➡',
+    'Dialogue: 0,0:04:00.00,0:04:03.00,Default,,0,0,0,,{\\pos(232,443)\\fscx50\\fscy50}ぜったい　ちが',
+    'Dialogue: 0,0:04:00.00,0:04:03.00,Default,,0,0,0,,{\\pos(232,497)}絶対違う',
+  ].join('\n');
+
+  const cues = parseSubtitleCues(content, 'polar-opposites-s02e08.ass');
+
+  assert.deepEqual(
+    cues.map((cue) => cue.text),
+    [
+      '（山田）ごめん　結局　ぬれたな。',
+      '大丈夫。',
+      '（山田の母）ほんなら\n隠し貯蔵のミルクまんじゅう➡',
+      '絶対違う',
+    ],
+  );
+  assert.deepEqual(cues[1]?.assFurigana, ['だいじょうぶ']);
+  assert.deepEqual(cues[2]?.assFurigana, ['かく', 'ちょぞう']);
+  assert.deepEqual(cues[3]?.assFurigana, ['ぜったい　ちが']);
+});
+
+// Broadcast-caption rows from You and I Are Polar Opposites S02E09. Every pair shares
+// timing, style, and the bottom band; only the text tells a wrap from a second speaker.
+const captionRowsHeader = ['[Script Info]', 'PlayResY: 540', '', ...eventsHeader];
+
+function captionRow(start: string, end: string, x: number, y: number, text: string): string {
+  return `Dialogue: 0,${start},${end},Default,,0,0,0,,{\\pos(${x},${y})}${text}`;
+}
+
+test('parseSubtitleCues joins caption rows that wrap one sentence across two events', () => {
+  const content = [
+    ...captionRowsHeader,
+    captionRow('0:00:19.08', '0:00:22.66', 172, 437, '⸨ぶっちゃけ'),
+    captionRow(
+      '0:00:19.08',
+      '0:00:22.66',
+      172,
+      497,
+      '早く{\\fscx50}　{\\fscx100}この勉強生活　終えたいし⸩',
+    ),
+    // No bracket at all: the upper row simply has not reached sentence punctuation.
+    captionRow('0:02:42.33', '0:02:44.43', 232, 437, '（東）≪好きだと'),
+    captionRow('0:02:42.33', '0:02:44.43', 232, 497, '自覚してしまったものの➡'),
+    // Rows are centred independently, so a wrap can change x between rows.
+    captionRow('0:00:42.21', '0:00:45.21', 252, 407, '≪ちょっとしたことで'),
+    captionRow('0:00:42.21', '0:00:45.21', 292, 497, '勝手に落ち込んだり➡'),
+    // A quote closed with 」 inside a still-open ≪…≫ span is not the end of the line.
+    captionRow('0:19:02.84', '0:19:05.00', 212, 437, '≪「つきあえる自信がない」'),
+    captionRow('0:19:02.84', '0:19:05.00', 452, 497, 'じゃない≫'),
+    // An in-sentence 「 quote on the lower row is not a new turn.
+    captionRow('0:18:35.55', '0:18:38.00', 232, 437, '今　「好きだ」と'),
+    captionRow('0:18:35.55', '0:18:38.00', 192, 497, '「心地いい」と感じてるのも➡'),
+  ].join('\n');
+
+  const cues = parseSubtitleCues(content, 'polar-opposites-s02e09.ass');
+
+  assert.deepEqual(
+    cues.map((cue) => cue.text),
+    [
+      '⸨ぶっちゃけ\n早く　この勉強生活　終えたいし⸩',
+      '≪ちょっとしたことで\n勝手に落ち込んだり➡',
+      '（東）≪好きだと\n自覚してしまったものの➡',
+      '今　「好きだ」と\n「心地いい」と感じてるのも➡',
+      '≪「つきあえる自信がない」\nじゃない≫',
+    ],
+  );
+  assert.ok(cues.every((cue) => cue.assLayout?.kind === 'positioned'));
+});
+
+test('parseSubtitleCues keeps simultaneous caption rows from two speakers separate', () => {
+  const content = [
+    ...captionRowsHeader,
+    // Both unlabeled: the upper row finished its sentence.
+    captionRow('0:03:56.10', '0:04:00.04', 172, 437, 'なあ　車両　変えね？'),
+    captionRow('0:03:56.10', '0:04:00.04', 632, 497, 'えっ？➡'),
+    // Lower row opens a labeled turn.
+    captionRow('0:03:38.48', '0:03:42.05', 592, 437, 'おはよう！'),
+    captionRow('0:03:38.48', '0:03:42.05', 272, 497, '（平）あっ　声　でかっ。'),
+    // A closed monologue span above a sound effect.
+    captionRow('0:08:16.83', '0:08:19.50', 372, 437, '≪落ち着け　落ち着け≫'),
+    captionRow('0:08:16.83', '0:08:19.50', 272, 497, 'ドクン　ドクン　ドクン…'),
+    // Two labeled speakers.
+    captionRow('0:09:27.90', '0:09:31.07', 312, 437, '（平）ぐぅ…。'),
+    captionRow('0:09:27.90', '0:09:31.07', 352, 497, '（東）≪ちくしょう～！≫'),
+    // A bare label never swallows a differently labeled row.
+    captionRow('0:11:43.24', '0:11:45.00', 212, 437, '（長谷川）'),
+    captionRow('0:11:43.24', '0:11:45.00', 412, 497, '（早乙女）ん？'),
+    // A short sentence-final 。 closes the upper row like any other.
+    captionRow('0:12:31.55', '0:12:33.55', 172, 437, '⚞（東）平。'),
+    captionRow('0:12:31.55', '0:12:33.55', 532, 497, 'あっ。'),
+  ].join('\n');
+
+  const cues = parseSubtitleCues(content, 'polar-opposites-s02e09.ass');
+
+  assert.deepEqual(
+    cues.map((cue) => cue.text),
+    [
+      'おはよう！',
+      '（平）あっ　声　でかっ。',
+      'なあ　車両　変えね？',
+      'えっ？➡',
+      '≪落ち着け　落ち着け≫',
+      'ドクン　ドクン　ドクン…',
+      '（平）ぐぅ…。',
+      '（東）≪ちくしょう～！≫',
+      '（長谷川）',
+      '（早乙女）ん？',
+      '⚞（東）平。',
+      'あっ。',
+    ],
+  );
+});
+
+test('parseSubtitleCues keeps caption rows apart across styles, bands, and timing', () => {
+  const content = [
+    ...captionRowsHeader,
+    // Same wording as a wrap, but the rows sit in different vertical bands.
+    captionRow('0:01:00.00', '0:01:02.00', 172, 77, '≪ちょっとしたことで'),
+    captionRow('0:01:00.00', '0:01:02.00', 172, 497, '勝手に落ち込んだり➡'),
+    // Same band, but a sign style beside dialogue.
+    'Dialogue: 0,0:01:05.00,0:01:07.00,Sign,,0,0,0,,{\\pos(172,437)}ちょっとしたことで',
+    captionRow('0:01:05.00', '0:01:07.00', 172, 497, '勝手に落ち込んだり➡'),
+    // Same rows, but the lower one ends later.
+    captionRow('0:01:10.00', '0:01:12.00', 172, 437, '≪ちょっとしたことで'),
+    captionRow('0:01:10.00', '0:01:13.00', 172, 497, '勝手に落ち込んだり➡'),
+    // Style-aligned rows without \pos are never caption rows.
+    'Dialogue: 0,0:01:15.00,0:01:17.00,Default,,0,0,0,,{\\an8}≪ちょっとしたことで',
+    'Dialogue: 0,0:01:15.00,0:01:17.00,Default,,0,0,0,,{\\an2}勝手に落ち込んだり➡',
+    // Same height: the events sit side by side, not one above the other.
+    captionRow('0:01:20.00', '0:01:22.00', 172, 497, '≪ちょっとしたことで'),
+    captionRow('0:01:20.00', '0:01:22.00', 612, 497, '勝手に落ち込んだり➡'),
+    // Same bottom band, but further apart than two text rows.
+    captionRow('0:01:25.00', '0:01:27.00', 172, 367, '≪ちょっとしたことで'),
+    captionRow('0:01:25.00', '0:01:27.00', 172, 497, '勝手に落ち込んだり➡'),
+  ].join('\n');
+
+  const cues = parseSubtitleCues(content, 'test.ass');
+
+  assert.equal(cues.length, 12);
+  assert.ok(cues.every((cue) => !cue.text.includes('\n')));
+});
+
+test('parseSubtitleCues leaves typeset rows alone in scripts that are not broadcast captions', () => {
+  // Fansub typesetting stacks positioned rows for signs, chat bubbles, and headlines. Such
+  // text carries no caption punctuation, so without the script-level gate every stacked
+  // pair here would read as an unfinished sentence and merge.
+  const content = [
+    ...captionRowsHeader,
+    captionRow('0:00:10.00', '0:00:14.00', 640, 200, 'Shocking Statement Leaves'),
+    captionRow('0:00:10.00', '0:00:14.00', 640, 260, 'Listeners Speechless!'),
+    captionRow('0:01:00.00', '0:01:04.00', 400, 300, 'shes here AGAIN'),
+    captionRow('0:01:00.00', '0:01:04.00', 400, 360, 'make sakiko-chan go home'),
+    // Japanese typesetting in the same script is held back by the same gate.
+    captionRow('0:02:00.00', '0:02:04.00', 300, 400, '定休日'),
+    captionRow('0:02:00.00', '0:02:04.00', 300, 460, '毎週水曜日'),
+  ].join('\n');
+
+  const cues = parseSubtitleCues(content, 'test.ass');
+
+  assert.deepEqual(
+    cues.map((cue) => cue.text),
+    [
+      'Shocking Statement Leaves',
+      'Listeners Speechless!',
+      'shes here AGAIN',
+      'make sakiko-chan go home',
+      '定休日',
+      '毎週水曜日',
+    ],
+  );
+});
+
+test('parseSubtitleCues never joins caption rows that carry no Japanese', () => {
+  // Even inside a caption script, romaji or English rows are not the wrapped Japanese
+  // sentences this pass targets.
+  const content = [
+    ...captionRowsHeader,
+    captionRow('0:00:10.00', '0:00:13.00', 172, 437, '（東）≪好きだと'),
+    captionRow('0:00:10.00', '0:00:13.00', 172, 497, '自覚してしまったものの➡'),
+    captionRow('0:00:20.00', '0:00:23.00', 172, 437, '（平）ん？'),
+    captionRow('0:00:30.00', '0:00:34.00', 640, 437, 'NOW LOADING'),
+    captionRow('0:00:30.00', '0:00:34.00', 640, 497, 'please wait'),
+  ].join('\n');
+
+  const cues = parseSubtitleCues(content, 'test.ass');
+
+  assert.deepEqual(
+    cues.map((cue) => cue.text),
+    ['（東）≪好きだと\n自覚してしまったものの➡', '（平）ん？', 'NOW LOADING', 'please wait'],
+  );
+});
+
+test('parseSubtitleCues scales furigana geometry by PlayResY', () => {
+  const content = [
+    '[Script Info]',
+    'PlayResY: 1080',
+    '',
+    ...eventsHeader,
+    'Dialogue: 0,0:02:38.20,0:02:41.87,Default,,0,0,0,,{\\pos(1104,226)\\fscx50\\fscy50}だいじょうぶ',
+    'Dialogue: 0,0:02:38.20,0:02:41.87,Default,,0,0,0,,{\\pos(1104,334)}大丈夫{\\fscx50}。',
+  ].join('\n');
+
+  const cues = parseSubtitleCues(content, 'test.ass');
+  assert.deepEqual(
+    cues.map((cue) => cue.text),
+    ['大丈夫。'],
+  );
+  assert.deepEqual(cues[0]?.assFurigana, ['だいじょうぶ']);
+});
+
+test('parseSubtitleCues preserves small kana without a matching kanji base caption', () => {
+  const content = [
+    ...eventsHeader,
+    'Dialogue: 0,0:00:01.00,0:00:04.00,Default,,0,0,0,,{\\pos(200,200)\\fscx50\\fscy50}ひそひそ',
+    'Dialogue: 0,0:00:01.00,0:00:04.00,Default,,0,0,0,,{\\pos(200,254)}ordinary dialogue',
+  ].join('\n');
+
+  assert.deepEqual(
+    parseSubtitleCues(content, 'test.ass').map((cue) => cue.text),
+    ['ひそひそ', 'ordinary dialogue'],
+  );
+});
+
+test('parseSubtitleCues preserves small kana horizontally separated from a kanji caption', () => {
+  const content = [
+    ...eventsHeader,
+    'Dialogue: 0,0:00:01.00,0:00:04.00,Default,,0,0,0,,{\\pos(800,200)\\fscx50\\fscy50}ひそひそ',
+    'Dialogue: 0,0:00:01.00,0:00:04.00,Default,,0,0,0,,{\\pos(200,254)}漢字',
+  ].join('\n');
+
+  const cues = parseSubtitleCues(content, 'test.ass');
+  assert.match(cues.map((cue) => cue.text).join('\n'), /ひそひそ/);
+  assert.deepEqual(
+    cues.flatMap((cue) => cue.assFurigana ?? []),
+    [],
+  );
+});
+
+test('parseSubtitleCues marks re-shown countdown frames as a fragment grid', () => {
+  const rows = [
+    ['juu', '10'],
+    ['juu', '10'],
+    ['kyuu', '9'],
+    ['kyuu', '9'],
+    ['hachi', '8'],
+    ['hachi', '8'],
+  ] as const;
+  const content = [
+    ...eventsHeader,
+    ...rows.flatMap(([word, num], index) => {
+      const timestamp = (seconds: number) => `0:00:${seconds.toFixed(2).padStart(5, '0')}`;
+      const start = timestamp(6 + index * 0.4);
+      const end = timestamp(6 + index * 0.4 + 0.4);
+      return [0, 1].flatMap((layer) => [
+        `Dialogue: ${layer},${start},${end},ED Romaji,,0,0,0,,{\\pos(${300 + index * 8},40)\\t(0,100,\\fscx120)}${word}`,
+        `Dialogue: ${layer},${start},${end},ED Romaji,,0,0,0,,{\\pos(${300 + index * 8},93)\\t(0,100,\\fscx120)}${num}`,
+      ]);
+    }),
+  ].join('\n');
+
+  assert.equal(parseSubtitleCues(content, 'test.ass')[0]?.assLayout?.kind, 'fragment-grid');
+});
+
+test('parseSubtitleCues marks scattered single-glyph typesetting as a fragment grid', () => {
+  const glyphs = ['の', 'こ', '部', 'そ', '屋'];
+  const content = [
+    ...eventsHeader,
+    ...[0, 1].flatMap((layer) =>
+      glyphs.map(
+        (glyph, index) =>
+          `Dialogue: ${layer},0:00:06.00,0:00:09.00,OP-JP,,0,0,0,,{\\pos(${500 + index * 30},${-30 + index * 35})\\t(0,100,\\fscx120)}${glyph}`,
+      ),
+    ),
+  ].join('\n');
+
+  assert.equal(parseSubtitleCues(content, 'test.ass')[0]?.assLayout?.kind, 'fragment-grid');
+});
+
+test('parseSubtitleCues marks a repeated-token sign wall as a fragment grid', () => {
+  const content = [
+    ...eventsHeader,
+    ...[0, 1].flatMap((layer) =>
+      Array.from(
+        { length: 6 },
+        (_, index) =>
+          `Dialogue: ${layer},0:00:06.00,0:00:09.00,Sign,,0,0,0,,{\\pos(${200 + index * 60},${100 + index * 30})\\t(0,100,\\fscx120)}${index % 2 === 0 ? 'Maid' : 'Cafe'}`,
+      ),
+    ),
+  ].join('\n');
+
+  assert.equal(parseSubtitleCues(content, 'test.ass')[0]?.assLayout?.kind, 'fragment-grid');
+});
+
+test('parseSubtitleCues keeps a wrapped lyric with a staggered repeated token publishable', () => {
+  const fragments = [
+    ['dreams', 300, 115, '0:00:01.00'],
+    ['ju', 250, 39, '0:00:01.00'],
+    ['n', 280, 39, '0:00:01.00'],
+    ['jo', 300, 39, '0:00:01.00'],
+    ['u', 330, 39, '0:00:01.00'],
+    ['to', 360, 39, '0:00:01.00'],
+    ['jo', 395, 39, '0:00:01.02'],
+    ['u', 425, 39, '0:00:01.00'],
+    ['ne', 455, 39, '0:00:01.00'],
+    ['tsu!', 485, 39, '0:00:01.00'],
+  ] as const;
+  const content = [
+    ...eventsHeader,
+    ...[0, 1].flatMap((layer) =>
+      fragments.map(
+        ([text, x, y, start], index) =>
+          `Dialogue: ${layer},${start},0:00:04.00,ED Romaji,,0,0,0,,{\\pos(${x},${y})\\t(${index * 2},${index * 2 + 100},\\fscx120)}${text}`,
+      ),
+    ),
+  ].join('\n');
+
+  const cue = parseSubtitleCues(content, 'test.ass')[0];
+  assert.notEqual(cue?.assLayout?.kind, 'fragment-grid');
+});
+
+test('parseSubtitleCues adds a missing word space after positioned punctuation', () => {
+  const fragments = [
+    ['H', 100],
+    ['i,', 119],
+    ['t', 153],
+    ['h', 168],
+    ['e', 186],
+    ['r', 202],
+    ['e', 216],
+  ] as const;
+  const content = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    ...[0, 1].flatMap((layer) =>
+      fragments.map(
+        ([fragment, x], index) =>
+          `Dialogue: ${layer},0:00:01.00,0:00:04.00,OP English,,0,0,0,,{\\pos(${x},110)\\t(${index * 2},${index * 2 + 100},\\fscx120)}${fragment}`,
+      ),
+    ),
+  ].join('\n');
+
+  assert.equal(parseSubtitleCues(content, 'test.ass')[0]?.text, 'Hi, there');
+});
+
+test('parseSubtitleCues does not split a positioned thousands separator', () => {
+  const fragments = [
+    ['1,', 100],
+    ['000', 145],
+    ['0', 185],
+    ['0', 205],
+    ['0', 225],
+  ] as const;
+  const content = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    ...[0, 1].flatMap((layer) =>
+      fragments.map(
+        ([fragment, x], index) =>
+          `Dialogue: ${layer},0:00:01.00,0:00:04.00,OP English,,0,0,0,,{\\pos(${x},110)\\t(${index * 2},${index * 2 + 100},\\fscx120)}${fragment}`,
+      ),
+    ),
+  ].join('\n');
+
+  assert.equal(parseSubtitleCues(content, 'test.ass')[0]?.text, '1,000000');
+});
+
+test('parseSubtitleCues does not split a wide glyph from its punctuated suffix', () => {
+  const fragments = [
+    ['v', 904],
+    ['o', 924],
+    ['i', 939],
+    ['c', 955],
+    ['e', 976],
+    ['r', 1004],
+    ['e', 1021],
+    ['a', 1042],
+    ['c', 1063],
+    ['h', 1083],
+    ['e', 1104],
+    ['d', 1125],
+    ['m', 1161],
+    ['e,', 1193],
+  ] as const;
+  const content = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    ...[0, 1].flatMap((layer) =>
+      fragments.map(
+        ([fragment, x], index) =>
+          `Dialogue: ${layer},0:00:01.00,0:00:04.00,OP English,,0,0,0,,{\\pos(${x},110)\\t(${index * 2},${index * 2 + 100},\\fscx120)}${fragment}`,
+      ),
+    ),
+  ].join('\n');
+
+  assert.equal(parseSubtitleCues(content, 'test.ass')[0]?.text, 'voice reached me,');
+});
+
+test('parseSubtitleCues spaces positioned lyric fragments across authored rows', () => {
+  const fragments = [
+    ['My', 472, 39],
+    ['song!', 543, 39],
+    ['My', 507, 78],
+    ['song!', 578, 78],
+    ['ku', 643, 39],
+    ['chi', 683, 39],
+    ['zu', 722, 39],
+    ['sa', 757, 39],
+    ['n', 783, 39],
+    ['de', 811, 39],
+  ] as const;
+  const content = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    ...[0, 1].flatMap((layer) =>
+      fragments.map(
+        ([fragment, x, y], index) =>
+          `Dialogue: ${layer},0:00:01.00,0:00:04.00,OP Romaji,,0,0,0,,{\\pos(${x},${y})\\t(${index * 2},${index * 2 + 100},\\fscx120)}${fragment}`,
+      ),
+    ),
+  ].join('\n');
+
+  assert.equal(parseSubtitleCues(content, 'test.ass')[0]?.text, 'My song! My song! kuchizusande');
+});
+
+test('parseSubtitleCues recovers positioned word gaps between romaji fragments', () => {
+  const fragments = [
+    ['sa', 380],
+    ['ga', 421],
+    ['shi', 467],
+    ['te', 510],
+    ['ta', 545],
+    ['ha', 593],
+    ['ji', 624],
+    ['ke', 655],
+    ['ta', 693],
+    ['i', 726],
+    ['ro', 749],
+    ['no', 798],
+    ['yu', 849],
+    ['me', 895],
+  ] as const;
+  const content = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    ...[0, 1].flatMap((layer) =>
+      fragments.map(
+        ([fragment, x], index) =>
+          `Dialogue: ${layer},0:00:01.00,0:00:04.00,OP Romaji,,0,0,0,,{\\pos(${x},110)\\t(${index * 2},${index * 2 + 100},\\fscx120)}${fragment}`,
+      ),
+    ),
+  ].join('\n');
+
+  assert.equal(parseSubtitleCues(content, 'test.ass')[0]?.text, 'sagashiteta hajiketa iro no yume');
+});
+
+test('parseSubtitleCues recovers clear word gaps in a short romaji line', () => {
+  const fragments = [
+    ['bo', 542],
+    ['ku', 584],
+    ['wo', 640],
+    ['yo', 697],
+    ['bu', 738],
+  ] as const;
+  const content = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    ...[0, 1].flatMap((layer) =>
+      fragments.map(
+        ([fragment, x], index) =>
+          `Dialogue: ${layer},0:00:01.00,0:00:04.00,OP Romaji,,0,0,0,,{\\pos(${x},110)\\t(${index * 2},${index * 2 + 100},\\fscx120)}${fragment}`,
+      ),
+    ),
+  ].join('\n');
+
+  assert.equal(parseSubtitleCues(content, 'test.ass')[0]?.text, 'boku wo yobu');
+});
+
+test('parseSubtitleCues suppresses a karaoke highlight sweep without publishing it', () => {
+  // Main lyric: per-glyph fragments alive together for the whole line.
+  const lineFragments = [
+    ['to', 972],
+    ['so', 1051],
+    ['u', 1113],
+    ['o', 1166],
+    ['mo', 1204],
+  ] as const;
+  // Highlight sweep: one syllable at a time over the same lyric, each event ending
+  // exactly as the next begins, so no two syllables are ever on screen together.
+  const sweepFragments = [
+    ['to', 972, '0:00:01.00', '0:00:01.40'],
+    ['so', 1051, '0:00:01.40', '0:00:01.80'],
+    ['u', 1113, '0:00:01.80', '0:00:02.20'],
+    ['o', 1166, '0:00:02.20', '0:00:02.60'],
+    ['mo', 1204, '0:00:02.60', '0:00:03.00'],
+  ] as const;
+  const content = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    ...[0, 1].flatMap((layer) =>
+      lineFragments.map(
+        ([fragment, x], index) =>
+          `Dialogue: ${layer},0:00:01.00,0:00:04.00,ED Romaji,,0,0,0,fx,{\\pos(${x},60)\\t(${index * 2},${index * 2 + 100},\\fscx120)}${fragment}`,
+      ),
+    ),
+    ...sweepFragments.flatMap(([fragment, x, start, end]) =>
+      [
+        [40, x, 60],
+        [41, x + 4, 64],
+      ].map(
+        ([layer, copyX, copyY]) =>
+          `Dialogue: ${layer},${start},${end},ED Romaji2,,0,0,0,fx,{\\an5\\pos(${copyX},${copyY})\\t(150,290,\\1a&HFF&)}${fragment}`,
+      ),
+    ),
+    'Dialogue: 42,0:00:01.20,0:00:01.30,ED Romaji2,,0,0,0,fx,{\\fnWebdings\\pos(900,50)\\t(0,100,\\fscx120)}a',
+    'Dialogue: 42,0:00:04.00,0:00:04.20,ED Romaji2,,0,0,0,fx,{\\fnWebdings\\pos(900,50)\\t(0,100,\\fscx120)}z',
+  ].join('\n');
+
+  const cues = parseSubtitleCues(content, 'test.ass');
+  assert.equal(cues.length, 2);
+  assert.equal(cues[0]?.text.replace(/\s+/gu, ''), 'tosouomo');
+  assert.equal(cues[1]?.text, 'z');
+});
+
+test('parseSubtitleCues collapses drop-shadow layer copies offset by a few pixels', () => {
+  const fragments = [
+    ['me', 580],
+    ['no', 668],
+    ['mae', 770],
+    ['ni', 864],
+    ['no', 939],
+    ['bi', 996],
+    ['ru', 1049],
+  ] as const;
+  const content = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    ...fragments.flatMap(([fragment, x], index) => [
+      `Dialogue: 30,0:01:42.00,0:01:46.92,OP Romaji,,0,0,0,fx,{\\pos(${x},25)\\bord0\\t(${index * 2},${index * 2 + 120},\\blur0.5)}${fragment}`,
+      // Shadow copy sits 4px off the base glyph and must not read as a second syllable.
+      `Dialogue: 29,0:01:42.00,0:01:46.92,OP Romaji,,0,0,0,fx,{\\pos(${x + 4},29)\\c&HFFFFFF&\\t(${index * 2},${index * 2 + 120},\\blur9)}${fragment}`,
+      `Dialogue: 28,0:01:42.00,0:01:46.92,OP Romaji,,0,0,0,fx,{\\pos(${x},25)\\c&HFFFFFF&\\t(${index * 2},${index * 2 + 120},\\blur9)}${fragment}`,
+    ]),
+  ].join('\n');
+
+  const cues = parseSubtitleCues(content, 'test.ass');
+  assert.equal(cues.length, 1);
+  assert.equal(cues[0]?.text.replace(/\s+/gu, ''), 'menomaeninobiru');
+});
+
+test('parseSubtitleCues recovers positional word gaps beside an authored space', () => {
+  // Real ED line: every glyph is placed by `\move`, but the `star` fragment alone carries
+  // a literal leading space. The authored space must not disable positional recovery for
+  // the rest of the line.
+  const fragments = [
+    ['s', 633],
+    ['e', 665],
+    ['a', 697],
+    ['r', 723],
+    ['c', 747],
+    ['h', 774],
+    ['i', 793],
+    ['n', 813],
+    ['g', 838],
+    ['f', 884],
+    ['o', 911],
+    ['r', 937],
+    ['a', 986],
+    ['s', 1041],
+    ['h', 1070],
+    ['o', 1098],
+    ['o', 1128],
+    ['t', 1153],
+    ['i', 1169],
+    ['n', 1188],
+    ['g', 1214],
+    [' s', 1264],
+    ['t', 1290],
+    ['a', 1316],
+    ['r', 1342],
+  ] as const;
+  const content = [
+    ...eventsHeader,
+    ...[0, 1].flatMap((layer) =>
+      fragments.map(
+        ([fragment, x], index) =>
+          `Dialogue: ${layer},0:22:44.83,0:22:47.70,ED English,,0,0,0,fx,{\\move(${x},1020,${x},1020,0,300)\\t(${index * 2},${index * 2 + 300},\\fs90)}${fragment}`,
+      ),
+    ),
+  ].join('\n');
+
+  assert.equal(parseSubtitleCues(content, 'test.ass')[0]?.text, 'searching for a shooting star');
+});
+
+test('parseSubtitleCues splits chunked words whose gap only the excess rule catches', () => {
+  // `Choices|presumably` normalizes to just under the ratio threshold because both
+  // neighbors are wide three-letter chunks; its constant word-space excess still shows.
+  const fragments = [
+    ['Ch', 526],
+    ['oi', 584],
+    ['ces', 648],
+    ['pre', 747],
+    ['su', 819],
+    ['mab', 904],
+    ['ly', 981],
+    ['ma', 1059],
+    ['de', 1128],
+    ['by', 1203],
+    ['cha', 1295],
+    ['nce', 1385],
+  ] as const;
+  const content = [
+    ...eventsHeader,
+    ...[0, 1].flatMap((layer) =>
+      fragments.map(
+        ([fragment, x], index) =>
+          `Dialogue: ${layer},0:01:53.01,0:01:55.52,OP English,,0,0,0,fx,{\\pos(${x},1055)\\t(${index * 2},${index * 2 + 120},\\blur0.5)}${fragment}`,
+      ),
+    ),
+  ].join('\n');
+
+  assert.equal(
+    parseSubtitleCues(content, 'test.ass')[0]?.text,
+    'Choices presumably made by chance',
+  );
+});
+
+test('parseSubtitleCues rebuilds a line from per-glyph phase stacks with staggered timing', () => {
+  // Each glyph lives as four events anchored at one point: a transparent pre-echo until
+  // its syllable is sung, a short highlight, a rising exit ghost, and a steady hold.
+  // No timing window is shared across the phases, only the anchor ties them together.
+  const glyphs = [
+    ['エ', 559],
+    ['ネ', 601],
+    ['ル', 643],
+    ['ギ', 686],
+    ['ー', 728],
+  ] as const;
+  const timestamp = (seconds: number) => `0:00:${seconds.toFixed(2).padStart(5, '0')}`;
+  const content = [
+    ...eventsHeader,
+    ...glyphs.flatMap(([glyph, x], index) => {
+      const highlightStart = 20.9 + index * 0.4;
+      return [
+        `Dialogue: 3,${timestamp(20 + index * 0.03)},${timestamp(highlightStart)},OP - JP,,0,0,0,,{\\blur1.5\\bord2\\c&H404040&\\3c&HFFFFFF&\\an5\\pos(${x},50)\\fad(300,0)\\1a&HFF&}${glyph}`,
+        `Dialogue: 3,${timestamp(highlightStart)},${timestamp(highlightStart + 0.4)},OP - JP,,0,0,0,,{\\an5\\pos(${x},50)\\bord2\\c&H404040&\\3c&HFFFFFF&\\t(120,240,\\3c&H007A7A7A&\\blur0)\\fad(0,300)}${glyph}`,
+        `Dialogue: 3,${timestamp(highlightStart)},${timestamp(highlightStart + 2.4)},OP - JP,,0,0,0,,{\\an5\\move(${x},50,${x},0)\\bord0\\shad0\\t(\\c&HFFFFFF&\\blur5\\alpha&HFF&)}${glyph}`,
+        `Dialogue: 3,${timestamp(highlightStart + 0.4)},${timestamp(26.1 + index * 0.05)},OP - JP,,0,0,0,,{\\an5\\pos(${x},50)\\bord2\\c&H404040&\\3c&HFFFFFF&\\fad(0,300)}${glyph}`,
+      ];
+    }),
+  ].join('\n');
+
+  const cues = parseSubtitleCues(content, 'test.ass');
+  assert.equal(cues.length, 1);
+  assert.equal(cues[0]?.text, 'エネルギー');
+  assert.equal(cues[0]?.source, 'reconstructed-ass');
+  // Published from the first sung syllable to the end of the hold, so the transparent
+  // lead-in and the exit ghosts' fade tail never overlap the neighboring lines. The
+  // full generated span stays available as the animation window.
+  assert.equal(cues[0]?.startTime, 20.9);
+  assert.equal(cues[0]?.endTime, 26.3);
+  assert.equal(cues[0]?.animationStartTime, 20);
+  assert.equal(cues[0]?.animationEndTime, 26.3);
+});
+
+test('parseSubtitleCues drops transparent glow echoes and merges an exit replay', () => {
+  // The visible line sits at one row while transparent-fill glow copies duplicate every
+  // glyph on another row, and the exit shatters each glyph into copies launched from a
+  // shared anchor. Only the authored line may publish, as a single unbroken cue.
+  const glyphs = [
+    ['さ', 686],
+    ['あ', 728],
+    ['預', 770],
+    ['け', 812],
+    ['て', 854],
+  ] as const;
+  const content = [
+    ...eventsHeader,
+    ...glyphs.flatMap(([glyph, x]) => [
+      `Dialogue: 3,0:00:16.28,0:00:18.71,OP - JP,,0,0,0,,{\\an2\\pos(${x},85)\\fad(200,0)\\fry-90\\c&H404040&\\3c&HF4F4F4&\\bord2\\t(0,300,\\fry0)}${glyph}`,
+      ...[0, 1].map(
+        () =>
+          `Dialogue: 3,0:00:16.28,0:00:20.01,OP - JP,,0,0,0,,{\\pos(${x},15)\\blur5.8\\fry-90\\1a&HFF&\\fad(200,0)\\3c&H3F26AA&\\t(0,300,\\fry0)\\t(2596,3222,\\bord0\\3a&HFF&)}${glyph}`,
+      ),
+      ...[0, 1].map(
+        (copy) =>
+          `Dialogue: 3,0:00:18.71,0:00:20.89,OP - JP,,0,0,0,,{\\an5\\bord2\\fad(0,200)\\move(${x},50,${x + 25 + copy * 3},${17 - copy * 39},1605,2055)\\t(450,792,\\c&H3500DE&\\bord0)\\t(1605,2055,\\blur15\\fscx20\\fscy20\\1a&H50&\\3a&H50&)}${glyph}`,
+      ),
+    ]),
+  ].join('\n');
+
+  const cues = parseSubtitleCues(content, 'test.ass');
+  assert.equal(cues.length, 1);
+  assert.equal(cues[0]?.text, 'さあ預けて');
+  assert.equal(cues[0]?.startTime, 16.28);
+  assert.equal(cues[0]?.endTime, 20.89);
+});
+
+test('parseSubtitleCues does not double a line rendered whole beside its glyph swarm', () => {
+  // An assembly effect shows the authored line as one positioned event while dozens of
+  // per-glyph particle copies converge onto each glyph's anchor. The whole event and
+  // the swarm spell the same text and must publish as one line, once.
+  const glyphs = [
+    ['可', 854],
+    ['笑', 896],
+    ['し', 938],
+    ['い', 980],
+    ['わ', 1022],
+    ['ね', 1064],
+  ] as const;
+  const wholeLine = glyphs.map(([glyph]) => `{\\an5\\fad(300,500)\\pos(960,50)}${glyph}`).join('');
+  const content = [
+    ...eventsHeader,
+    `Dialogue: 1,0:00:17.29,0:00:18.99,OP - JP,,0,0,0,,${wholeLine}`,
+    ...glyphs.flatMap(([glyph, x], index) =>
+      [0, 1, 2].map(
+        (copy) =>
+          `Dialogue: 2,0:00:17.${30 + index * 5 + copy},0:00:19.10,OP - JP,,0,0,0,,{\\bord4\\blur4\\an5\\fad(500,0)\\move(${x - 60 - copy * 17},${120 + copy * 6},${x},50,20,900)\\clip(${x - 70},80,${x - 66},84)\\t(20,900,\\clip(${x - 4},7,${x},11))}${glyph}`,
+      ),
+    ),
+  ].join('\n');
+
+  const cues = parseSubtitleCues(content, 'test.ass');
+  assert.equal(cues.length, 1);
+  assert.equal(cues[0]?.text, '可笑しいわね');
+});
+
+test('parseSubtitleCues drops a wall of near-invisible positioned texture strings', () => {
+  // An image drawn by \p1 vector events carries no texture seed, but its glyph payload
+  // is still dozens of near-transparent positioned strings sharing one window. A real
+  // faint translation is one or two events and stays published.
+  const content = [
+    ...eventsHeader,
+    "Dialogue: 90,0:00:12.66,0:00:14.91,Default,,0,0,0,,We'll play as a band, and then...",
+    ...Array.from(
+      { length: 12 },
+      (_, index) =>
+        `Dialogue: 9,0:00:12.66,0:00:14.91,MarySigns,,0,0,0,,{\\an7\\pos(${640 + index * 13},${4 + index * 40})\\fnGrain SemiBold\\c&H000000&\\alpha&HFD&}gtO${index}x!`,
+    ),
+    'Dialogue: 9,0:00:12.66,0:00:14.91,OtherSign,,0,0,0,,{\\pos(151,769)\\fnGrain\\alpha&HE0&}A faint but real translation',
+  ].join('\n');
+
+  assert.deepEqual(
+    parseSubtitleCues(content, 'test.ass').map((cue) => cue.text),
+    ["We'll play as a band, and then...", 'A faint but real translation'],
+  );
+});
+
+test('parseSubtitleCues drops zero-scaled zero-clipped hidden warning text', () => {
+  const content = [
+    ...eventsHeader,
+    'Dialogue: 99,0:00:00.00,0:00:15.16,Default,,0,0,0,,{\\org(0,0)\\fscx0\\fscy0\\clip(0,0,0,0)}Your media player does not support the subtitle format.',
+    'Dialogue: 0,0:00:01.00,0:00:04.00,Default,,0,0,0,,{\\fscx0\\t(0,300,\\fscx100)}見えるセリフ',
+  ].join('\n');
+
+  assert.deepEqual(
+    parseSubtitleCues(content, 'test.ass').map((cue) => cue.text),
+    ['見えるセリフ'],
+  );
+});
+
+test('parseSubtitleCues keeps hidden events hidden when a transform animates an unrelated tag', () => {
+  // `\t(...)` only reveals a zero-scaled or fully clipped event when it animates the
+  // scale or the clip itself. Animating an unrelated property -- at any nesting depth --
+  // leaves the event invisible, so its text must not reach the subtitles.
+  const content = [
+    ...eventsHeader,
+    'Dialogue: 0,0:00:01.00,0:00:04.00,Default,,0,0,0,,{\\fscx0\\fscy0\\clip(0,0,0,0)\\t(0,300,\\bord5)}hidden warning',
+    'Dialogue: 0,0:00:01.00,0:00:04.00,Default,,0,0,0,,{\\clip(0,0,0,0)\\t(0,600,\\t(0,300,\\blur4))}nested hidden warning',
+    'Dialogue: 0,0:00:05.00,0:00:08.00,Default,,0,0,0,,{\\fscx0\\t(0,300,\\fscx100)}grows into view',
+    'Dialogue: 0,0:00:09.00,0:00:12.00,Default,,0,0,0,,{\\clip(0,0,0,0)\\t(0,300,\\clip(0,0,500,500))}wipes into view',
+  ].join('\n');
+
+  assert.deepEqual(
+    parseSubtitleCues(content, 'test.ass').map((cue) => cue.text),
+    ['grows into view', 'wipes into view'],
+  );
+});
+
+test('parseAssCues records the vertical band from style alignment, overrides, and \\pos', () => {
+  const ass = [
+    '[Script Info]',
+    'PlayResY: 720',
+    '',
+    '[V4+ Styles]',
+    'Format: Name, Fontname, Fontsize, PrimaryColour, Bold, Alignment, MarginV, Encoding',
+    'Style: Bottom,Arial,54,&H00FFFFFF,0,2,30,1',
+    'Style: TopSong,Arial,54,&H00FFFFFF,0,9,12,1',
+    '',
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    'Dialogue: 0,0:00:01.00,0:00:03.00,Bottom,,0,0,0,,\u4e0b\u306e\u30bb\u30ea\u30d5',
+    'Dialogue: 0,0:00:01.00,0:00:03.00,TopSong,,0,0,0,,\u6b4c\u8a5e\u306e\u884c',
+    'Dialogue: 0,0:00:01.00,0:00:03.00,Bottom,,0,0,0,,{\\an8}\u4e0a\u66f8\u304d\u306e\u884c',
+    'Dialogue: 0,0:00:01.00,0:00:03.00,Bottom,,0,0,0,,{\\pos(640,20)}\u770b\u677f\u306e\u884c',
+  ].join('\n');
+
+  const bands = parseAssCues(ass).map((cue) => cue.assLayout?.verticalBand);
+  assert.deepEqual(bands, ['bottom', 'top', 'top', 'top']);
+});
diff --git a/src/core/services/subtitle-cue-parser.ts b/src/core/services/subtitle-cue-parser.ts
index 99c970f3..f0483eb4 100644
--- a/src/core/services/subtitle-cue-parser.ts
+++ b/src/core/services/subtitle-cue-parser.ts
@@ -2,25 +2,49 @@ import {
   assOverrideSignature,
   assToPlainText,
   collectAssOverrideCommands,
+  hasAssTemporalOverride,
   parseAssEffectField,
+  removeAssControlDebrisLines,
   type AssEffectKind,
   type AssOverrideCommand,
 } from './ass-text';
 import { hasAssAnimationEvidence, mergeDuplicateCues } from './subtitle-cue-dedup';
 
+/** Vertical third of the screen a cue is authored to occupy. */
+export type AssVerticalBand = 'top' | 'middle' | 'bottom';
+
+export type AssCueLayout =
+  | {
+      kind: 'positioned';
+      sourceOrder: number;
+      x?: number;
+      y: number;
+      verticalBand?: AssVerticalBand;
+    }
+  | { kind: 'fragment-grid'; sourceOrder: number; verticalBand?: AssVerticalBand }
+  | { kind: 'source-order'; sourceOrder: number; verticalBand?: AssVerticalBand };
+
 export interface SubtitleCue {
   startTime: number;
   endTime: number;
   text: string;
-  /** A complete authored line recovered from matching generated ASS animation events. */
-  source?: 'canonical-ass';
   /**
-   * Full span of the generated animation events a canonical cue replaced. Entrance and
-   * exit frames routinely run past the authored `startTime`/`endTime`, so live-text
-   * matching must use this envelope while display and history keep the authored timing.
+   * ASS ruby text removed from the published cue. Kept only so live `sub-text` matching
+   * can account for the extra lines mpv still reports from the source track.
+   */
+  assFurigana?: readonly string[];
+  /** How a complete line was recovered from generated ASS animation events. */
+  source?: 'canonical-ass' | 'reconstructed-ass';
+  /**
+   * Full span of the generated animation events a recovered cue replaced. Entrance and
+   * exit frames can run past canonical authored timing.
    */
   animationStartTime?: number;
   animationEndTime?: number;
+  /** ASS style retained only for fragment-reconstructed lines. */
+  assStyle?: string;
+  /** Authored ASS ordering metadata used when flattening simultaneous positioned cues. */
+  assLayout?: AssCueLayout;
 }
 
 /**
@@ -29,7 +53,7 @@ export interface SubtitleCue {
  * override commands it carries, whether the `Effect` column was set -- to tell a karaoke
  * burst apart from two characters saying the same word in turn. None of it is meaningful
  * outside the parser, so the public API exposes only timing, text, and the optional
- * canonical-source marker used by live subtitle consumers.
+ * recovery marker used by live subtitle consumers.
  */
 export interface AnnotatedSubtitleCue extends SubtitleCue {
   /** Text exactly as authored, override blocks and all. */
@@ -75,15 +99,69 @@ function parseTimestamp(
  * line breaks, matching what mpv hands over for the same line played live. No layer
  * downstream decodes ASS again.
  */
+function decodeSubtitleCueText(text: string): string {
+  return assToPlainText(text, '\n').replace(HTML_SUBTITLE_TAG_PATTERN, '');
+}
+
 function sanitizeSubtitleCueText(text: string): string {
-  return assToPlainText(text, '\n').replace(HTML_SUBTITLE_TAG_PATTERN, '').trim();
+  return decodeSubtitleCueText(text).trim();
+}
+
+function sanitizeAssCueText(text: string): string {
+  return removeAssControlDebrisLines(decodeSubtitleCueText(text)).trim();
+}
+
+function attachAssMetadata<T extends SubtitleCue>(
+  cue: T,
+  assLayout: AssCueLayout | undefined,
+  assFurigana: readonly string[] | undefined,
+): T {
+  if (assLayout) {
+    Object.defineProperty(cue, 'assLayout', { value: assLayout, enumerable: false });
+  }
+  if (assFurigana?.length) {
+    Object.defineProperty(cue, 'assFurigana', { value: assFurigana, enumerable: false });
+  }
+  return cue;
 }
 
 function toPublicCues(cues: AnnotatedSubtitleCue[]): SubtitleCue[] {
-  return cues.map(({ startTime, endTime, text, source, animationStartTime, animationEndTime }) =>
-    source
-      ? { startTime, endTime, text, source, animationStartTime, animationEndTime }
-      : { startTime, endTime, text },
+  return cues.map(
+    ({
+      startTime,
+      endTime,
+      text,
+      source,
+      animationStartTime,
+      animationEndTime,
+      style,
+      assLayout,
+      assFurigana,
+    }) => {
+      const common = {
+        startTime,
+        endTime,
+        text,
+      };
+      if (source === 'reconstructed-ass') {
+        return attachAssMetadata(
+          {
+            ...common,
+            source,
+            animationStartTime,
+            animationEndTime,
+            assStyle: style,
+          },
+          assLayout,
+          assFurigana,
+        );
+      }
+      return attachAssMetadata(
+        source ? { ...common, source, animationStartTime, animationEndTime } : common,
+        assLayout,
+        assFurigana,
+      );
+    },
   );
 }
 
@@ -159,6 +237,11 @@ const MIN_CANONICAL_ANIMATION_EVENTS = 3;
 // A tiny animated fragment can itself be composed from still smaller glyph events. It is
 // not enough evidence that the fragment represents an authored line boundary.
 const MIN_CANONICAL_DIALOGUE_TEXT_LENGTH = 4;
+const MIN_FRAGMENT_LINE_EVENTS = 8;
+const MIN_FRAGMENT_LINE_PARTS = 4;
+const MAX_FRAGMENT_MEDIAN_LENGTH = 4;
+const MAX_FRAGMENT_LINE_TIMING_VARIANCE_SECONDS = 2;
+const MAX_FRAGMENT_LINE_VERTICAL_SPAN = 48;
 
 function parseAssTimestamp(raw: string): number | null {
   const match = ASS_TIMING_PATTERN.exec(raw.trim());
@@ -266,8 +349,17 @@ interface FragmentGroup {
   events: AnnotatedSubtitleCue[];
 }
 
+// Anchor extraction walks every override command, and the canonical/fragment passes
+// consult the same events once per candidate neighborhood, so heavy KFX tags make the
+// uncached form quadratic in practice.
+const placementAnchorCache = new WeakMap<AnnotatedSubtitleCue, Set<string>>();
+
 function fragmentPlacementAnchors(event: AnnotatedSubtitleCue): Set<string> {
-  const anchors = new Set<string>();
+  let anchors = placementAnchorCache.get(event);
+  if (anchors) {
+    return anchors;
+  }
+  anchors = new Set<string>();
   for (const command of event.overrides) {
     const name = command.name.toLowerCase();
     const args = command.args.split(',').map((value) => value.trim());
@@ -278,9 +370,73 @@ function fragmentPlacementAnchors(event: AnnotatedSubtitleCue): Set<string> {
       anchors.add(`move:${args[2]},${args[3]}`);
     }
   }
+  placementAnchorCache.set(event, anchors);
   return anchors;
 }
 
+// Drop-shadow layer copies sit a few pixels off their base glyph, while even tightly
+// kerned repeated glyphs in one line ("ii") measure 10px apart or more.
+const LAYER_COPY_OFFSET_TOLERANCE_PX = 6;
+
+// Copies chain only through genuine time overlap. Consecutive re-runs of one visual
+// (chant bursts, countdown frames, jitter animation frames) abut or micro-overlap at
+// frame seams, so the different-structure threshold sits above a frame seam while the
+// phases of one effect (a highlight and the exit ghost it launches) overlap far longer.
+const MIN_PHASE_OVERLAP_SECONDS = 0.04;
+
+// Decoration is timed to the line it accompanies, but a lead-in echo can end exactly
+// where the recovered line's first sung copy begins; a small tolerance keeps such
+// flush decoration attached to its line.
+const DECORATION_SPAN_TOLERANCE_SECONDS = 0.1;
+
+// Guards for pathological event volumes. Real copy stacks and repaint chains stay in
+// the hundreds; a same-text bucket or candidate sweep group in the thousands is a
+// particle field, and the quadratic passes over it would stall the main process.
+const MAX_COALESCE_BUCKET_EVENTS = 1500;
+const MAX_SWEEP_GROUP_EVENTS = 4000;
+// Fragment-layer collapsing repeatedly rescans the remaining parts after each match.
+// Genuine authored lines stay far below this limit; larger groups are particle fields.
+const MAX_FRAGMENT_COLLAPSE_PARTS = 1500;
+
+/**
+ * Sources behind a coalesced copy chain. Synthetic cues stand in for their sources
+ * during fragment recovery, but suppression and copy-count evidence must reach the
+ * original events, which are what the published dialogue list still holds.
+ */
+const coalescedSourceEvents = new WeakMap<AnnotatedSubtitleCue, AnnotatedSubtitleCue[]>();
+
+function sourceEventsOf(cue: AnnotatedSubtitleCue): readonly AnnotatedSubtitleCue[] {
+  return coalescedSourceEvents.get(cue) ?? [cue];
+}
+
+function sourceEventCount(events: readonly AnnotatedSubtitleCue[]): number {
+  return events.reduce((count, event) => count + sourceEventsOf(event).length, 0);
+}
+
+// One representative point per placement command: the `\pos` point or the `\move`
+// midpoint. Comparing raw `\move` endpoints cross-wise misreads a travel distance that
+// matches the glyph advance as a layer copy of a neighboring same-letter glyph.
+const anchorPointCache = new WeakMap<AnnotatedSubtitleCue, AssFragmentPosition[]>();
+
+function fragmentAnchorPoints(event: AnnotatedSubtitleCue): AssFragmentPosition[] {
+  let points = anchorPointCache.get(event);
+  if (points) {
+    return points;
+  }
+  points = [];
+  for (const command of event.overrides) {
+    const name = command.name.toLowerCase();
+    const args = command.args.split(',').map((value) => Number(value.trim()));
+    if (name === 'pos' && args.length >= 2 && args.slice(0, 2).every(Number.isFinite)) {
+      points.push({ x: args[0]!, y: args[1]! });
+    } else if (name === 'move' && args.length >= 4 && args.slice(0, 4).every(Number.isFinite)) {
+      points.push({ x: (args[0]! + args[2]!) / 2, y: (args[1]! + args[3]!) / 2 });
+    }
+  }
+  anchorPointCache.set(event, points);
+  return points;
+}
+
 function isRepeatedFragmentCopy(
   previous: AnnotatedSubtitleCue,
   current: AnnotatedSubtitleCue,
@@ -289,6 +445,17 @@ function isRepeatedFragmentCopy(
   if ([...fragmentPlacementAnchors(current)].some((anchor) => previousAnchors.has(anchor))) {
     return true;
   }
+  const previousPoints = fragmentAnchorPoints(previous);
+  const nearbyAnchor = fragmentAnchorPoints(current).some((point) =>
+    previousPoints.some(
+      (previousPoint) =>
+        Math.abs(point.x - previousPoint.x) <= LAYER_COPY_OFFSET_TOLERANCE_PX &&
+        Math.abs(point.y - previousPoint.y) <= LAYER_COPY_OFFSET_TOLERANCE_PX,
+    ),
+  );
+  if (nearbyAnchor) {
+    return true;
+  }
   return (
     previous.startTime === current.startTime &&
     previous.endTime === current.endTime &&
@@ -296,6 +463,1406 @@ function isRepeatedFragmentCopy(
   );
 }
 
+// Coalescing keys on where a copy is anchored: the `\pos` point and both `\move`
+// endpoints, since exit ghosts launch from the glyph anchor and entrance copies
+// converge onto it.
+function coalesceAnchorPoints(event: AnnotatedSubtitleCue): AssFragmentPosition[] {
+  const points: AssFragmentPosition[] = [];
+  for (const command of event.overrides) {
+    const name = command.name.toLowerCase();
+    const args = command.args.split(',').map((value) => Number(value.trim()));
+    if (name === 'pos' && args.length >= 2 && args.slice(0, 2).every(Number.isFinite)) {
+      points.push({ x: args[0]!, y: args[1]! });
+    } else if (name === 'move' && args.length >= 4 && args.slice(0, 4).every(Number.isFinite)) {
+      points.push({ x: args[0]!, y: args[1]! });
+      points.push({ x: args[2]!, y: args[3]! });
+    }
+  }
+  return points;
+}
+
+function shareCoalesceAnchor(
+  left: readonly AssFragmentPosition[],
+  right: readonly AssFragmentPosition[],
+): boolean {
+  return right.some((point) =>
+    left.some(
+      (other) =>
+        Math.abs(point.x - other.x) <= LAYER_COPY_OFFSET_TOLERANCE_PX &&
+        Math.abs(point.y - other.y) <= LAYER_COPY_OFFSET_TOLERANCE_PX,
+    ),
+  );
+}
+
+// The set of distinct command names, ignoring arguments and repetition. Two phases of
+// one effect (pre-echo, highlight, hold) carry different command vocabularies; a re-run
+// of the same visual (chant burst, countdown frame) repeats the same vocabulary with new
+// argument values -- including a different number of animation keyframes, which is why
+// repetition must not count.
+const structuralSignatureCache = new WeakMap<AnnotatedSubtitleCue, string>();
+
+function structuralOverrideSignature(cue: AnnotatedSubtitleCue): string {
+  let signature = structuralSignatureCache.get(cue);
+  if (signature === undefined) {
+    const names = new Set(
+      cue.overrides.map((command) => `${command.animated ? '~' : ''}${command.name.toLowerCase()}`),
+    );
+    signature = [...names].sort().join(',');
+    structuralSignatureCache.set(cue, signature);
+  }
+  return signature;
+}
+
+// A transparent lead-in ends exactly where its glyph's first sung copy begins, so the
+// echo-to-visible handoff must chain across a small seam.
+const COALESCE_SEAM_TOLERANCE_SECONDS = 0.05;
+
+/**
+ * Two same-text copies chain when their windows genuinely overlap. Structurally
+ * identical events are layers of one visual exactly when their windows substantially
+ * coincide; a frame seam or few-millisecond overlap between identical structures is a
+ * re-run (the next chant burst, the next countdown frame). Structurally different
+ * events are phases of one effect and chain across any above-seam overlap. A bare seam
+ * only joins a transparent echo to its visible phase: the lead-in before a highlight
+ * belongs to its glyph, while two visible events that merely abut (the next burst of a
+ * chant, an exit flash after a hold) are separate showings.
+ */
+function areTimeConnectedCopies(a: AnnotatedSubtitleCue, b: AnnotatedSubtitleCue): boolean {
+  const overlap = Math.min(a.endTime, b.endTime) - Math.max(a.startTime, b.startTime);
+  if (structuralOverrideSignature(a) === structuralOverrideSignature(b)) {
+    const shorterDuration = Math.min(a.endTime - a.startTime, b.endTime - b.startTime);
+    return overlap >= Math.max(MIN_PHASE_OVERLAP_SECONDS, shorterDuration / 2);
+  }
+  if (overlap >= MIN_PHASE_OVERLAP_SECONDS) {
+    return true;
+  }
+  return (
+    overlap >= -COALESCE_SEAM_TOLERANCE_SECONDS &&
+    isTransparentFillEcho(a) !== isTransparentFillEcho(b)
+  );
+}
+
+function buildCoalescedCopy(members: readonly AnnotatedSubtitleCue[]): AnnotatedSubtitleCue {
+  const ordered = [...members].sort((left, right) => left.order - right.order);
+  const representative =
+    ordered.find((member) =>
+      member.overrides.some((command) => !command.animated && command.name.toLowerCase() === 'pos'),
+    ) ?? ordered[0]!;
+  const synthetic: AnnotatedSubtitleCue = {
+    ...representative,
+    startTime: earliestStartTime(ordered),
+    endTime: latestEndTime(ordered),
+    order: ordered[0]!.order,
+  };
+  coalescedSourceEvents.set(synthetic, ordered);
+  return synthetic;
+}
+
+/**
+ * Generated glyph effects render one authored glyph as a stack of copies anchored at the
+ * same point: a transparent pre-echo until the syllable is sung, a short highlight, an
+ * exit ghost launched from the anchor, and a steady hold to the end of the line. Their
+ * windows abut rather than coincide, so per-event timing says four unrelated fragments
+ * while the anchor says one glyph. Merging each stack into a single presence spanning
+ * the union window lets timing clusters see the authored line instead of its phases.
+ */
+function coalesceAssAnchorCopies(events: readonly AnnotatedSubtitleCue[]): AnnotatedSubtitleCue[] {
+  const buckets = new Map<string, number[]>();
+  const anchorPoints: (AssFragmentPosition[] | null)[] = events.map(() => null);
+  events.forEach((event, index) => {
+    const text = compactCueMatchText(event);
+    if (!text) {
+      return;
+    }
+    const points = coalesceAnchorPoints(event);
+    if (points.length === 0) {
+      return;
+    }
+    anchorPoints[index] = points;
+    const bucket = buckets.get(text);
+    if (bucket) {
+      bucket.push(index);
+    } else {
+      buckets.set(text, [index]);
+    }
+  });
+  for (const [text, bucket] of buckets) {
+    if (bucket.length > MAX_COALESCE_BUCKET_EVENTS) {
+      // Pathological same-text volume (a whole-episode particle field). Pairing would
+      // stall the main process; uncoalesced events fall back to the burst/grid paths.
+      buckets.delete(text);
+    } else {
+      bucket.sort((left, right) => events[left]!.startTime - events[right]!.startTime);
+    }
+  }
+
+  const parent = events.map((_, index) => index);
+  const findRoot = (index: number): number => {
+    let root = index;
+    while (parent[root] !== root) {
+      root = parent[root]!;
+    }
+    while (parent[index] !== root) {
+      const next = parent[index]!;
+      parent[index] = root;
+      index = next;
+    }
+    return root;
+  };
+  const union = (left: number, right: number): void => {
+    parent[findRoot(left)] = findRoot(right);
+  };
+
+  for (const bucket of buckets.values()) {
+    // Buckets are start-sorted; copies can only connect through time proximity, so the
+    // backward scan stops once no earlier copy's window can still reach this one.
+    const prefixMaxEnd: number[] = [];
+    let maxEnd = -Infinity;
+    for (const index of bucket) {
+      maxEnd = Math.max(maxEnd, events[index]!.endTime);
+      prefixMaxEnd.push(maxEnd);
+    }
+    for (let i = 1; i < bucket.length; i += 1) {
+      const right = bucket[i]!;
+      const reachableStart = events[right]!.startTime - COALESCE_SEAM_TOLERANCE_SECONDS;
+      for (let j = i - 1; j >= 0 && prefixMaxEnd[j]! >= reachableStart; j -= 1) {
+        const left = bucket[j]!;
+        if (
+          shareCoalesceAnchor(anchorPoints[left]!, anchorPoints[right]!) &&
+          areTimeConnectedCopies(events[left]!, events[right]!)
+        ) {
+          union(left, right);
+        }
+      }
+    }
+  }
+
+  const componentsByRoot = new Map<number, AnnotatedSubtitleCue[]>();
+  events.forEach((event, index) => {
+    const root = findRoot(index);
+    const members = componentsByRoot.get(root);
+    if (members) {
+      members.push(event);
+    } else {
+      componentsByRoot.set(root, [event]);
+    }
+  });
+  if (componentsByRoot.size === events.length) {
+    return [...events];
+  }
+  return [...componentsByRoot.values()]
+    .map((members) => (members.length === 1 ? members[0]! : buildCoalescedCopy(members)))
+    .sort((left, right) => left.order - right.order);
+}
+
+function hasRelaxedAssFragmentEvidence(events: readonly AnnotatedSubtitleCue[]): boolean {
+  if (
+    sourceEventCount(events) < 2 ||
+    !events.every((event) => fragmentPlacementAnchors(event).size > 0)
+  ) {
+    return false;
+  }
+
+  const latestStart = events.reduce(
+    (latest, event) => Math.max(latest, event.startTime),
+    -Infinity,
+  );
+  const earliestEnd = events.reduce(
+    (earliest, event) => Math.min(earliest, event.endTime),
+    Infinity,
+  );
+  if (latestStart >= earliestEnd) {
+    return false;
+  }
+
+  const first = events[0]!;
+  const hasChangingOverrides = events.some(
+    (event) => event.overrideSignature !== first.overrideSignature,
+  );
+  const hasPositionedLayerCopy =
+    events.some((event) => sourceEventsOf(event).length > 1) ||
+    events.some((event, index) =>
+      events
+        .slice(0, index)
+        .some(
+          (previous) =>
+            compactCueMatchText(previous) === compactCueMatchText(event) &&
+            isRepeatedFragmentCopy(previous, event),
+        ),
+    );
+  return hasChangingOverrides || hasPositionedLayerCopy;
+}
+
+interface AssFragmentPart {
+  cue: AnnotatedSubtitleCue;
+  text: string;
+}
+
+interface AssFragmentPosition {
+  x: number;
+  y: number;
+}
+
+const MIN_LATIN_POSITION_GAP_SAMPLES = 4;
+const LATIN_FRAGMENT_WORD_GAP_RATIO = 1.16;
+const LATIN_GLYPH_WORD_GAP_RATIO = 1.4;
+// Word-space advance beyond the width-predicted glyph advance, as a fraction of the
+// line's common unit. Measured corpus extremes: widest within-word excess 0.32 (`pp`
+// with tracking), narrowest word gap 0.40 (`s w` across a wide glyph). That margin only
+// holds when the common unit is estimated from enough glyph pairs; a short single-word
+// line (`Swelling`) skews the unit low and its ordinary advances read as word gaps.
+const LATIN_GLYPH_WORD_EXCESS_RATIO = 0.36;
+const MIN_LATIN_GLYPH_EXCESS_GAP_SAMPLES = 10;
+// Multi-character syllable chunks average out proportional-font variation, so their
+// advances track the width model far more closely than single glyphs do. Measured on a
+// chunked lyric line, within-word excess stayed under 0.07 of the common unit while every
+// word gap cleared 0.31, so a tighter margin separates them without splitting words.
+const LATIN_CHUNK_WORD_EXCESS_RATIO = 0.2;
+const MIN_LATIN_CHUNK_EXCESS_GAP_SAMPLES = 6;
+const LATIN_TWO_GLYPH_WORD_NEXT_GAP_RATIO = 1.2;
+
+function fragmentPosition(cue: AnnotatedSubtitleCue): AssFragmentPosition | null {
+  for (const command of cue.overrides) {
+    if (command.animated) continue;
+    const name = command.name.toLowerCase();
+    const args = command.args.split(',').map((value) => Number(value.trim()));
+    if (
+      name === 'pos' &&
+      args.length >= 2 &&
+      Number.isFinite(args[0]) &&
+      Number.isFinite(args[1])
+    ) {
+      return { x: args[0]!, y: args[1]! };
+    }
+    if (
+      name === 'move' &&
+      args.length >= 4 &&
+      args.slice(0, 4).every((value) => Number.isFinite(value))
+    ) {
+      return { x: (args[0]! + args[2]!) / 2, y: (args[1]! + args[3]!) / 2 };
+    }
+  }
+  return null;
+}
+
+function latinGlyphWidthWeight(glyph: string): number {
+  if (/[ilIj]/u.test(glyph)) return 0.6;
+  if (/[tfr]/u.test(glyph)) return 0.8;
+  if (/[mwMW]/u.test(glyph)) return 1.4;
+  if (/[A-Z]/u.test(glyph)) return 1.1;
+  return 1;
+}
+
+function latinFragmentWidthWeight(text: string): number | null {
+  if (!/^[A-Za-z0-9'’.,!?;:-]+$/u.test(text)) return null;
+  const punctuationWeight = /^[A-Za-z0-9]['’.,!?;:-]$/u.test(text) ? 0.5 : 0.25;
+  return [...text].reduce(
+    (width, glyph) =>
+      width + (/['’.,!?;:-]/u.test(glyph) ? punctuationWeight : latinGlyphWidthWeight(glyph)),
+    0,
+  );
+}
+
+function isSingleLatinGlyphFragment(text: string): boolean {
+  return [...text].filter((glyph) => /[A-Za-z0-9]/u.test(glyph)).length <= 1;
+}
+
+interface LatinFragmentGapMeasure {
+  distance: number;
+  meanWeight: number;
+}
+
+function latinFragmentGapMeasure(
+  previous: AssFragmentPart,
+  current: AssFragmentPart,
+): LatinFragmentGapMeasure | null {
+  const previousWeight = latinFragmentWidthWeight(previous.text);
+  const currentWeight = latinFragmentWidthWeight(current.text);
+  const previousPosition = fragmentPosition(previous.cue);
+  const currentPosition = fragmentPosition(current.cue);
+  if (previousWeight === null || currentWeight === null || !previousPosition || !currentPosition) {
+    return null;
+  }
+  const xDistance = currentPosition.x - previousPosition.x;
+  const yDistance = Math.abs(currentPosition.y - previousPosition.y);
+  if (yDistance <= 2 && xDistance <= 0) return null;
+
+  // A wrapped authored line can return to the left on its next visual row. Preserve
+  // that measured row transition as a separator without treating backwards movement
+  // on the same row as a word gap.
+  const distance = yDistance <= 2 ? xDistance : Math.abs(xDistance) + yDistance;
+  return { distance, meanWeight: (previousWeight + currentWeight) / 2 };
+}
+
+function normalizedLatinFragmentGap(
+  previous: AssFragmentPart,
+  current: AssFragmentPart,
+): number | null {
+  const measure = latinFragmentGapMeasure(previous, current);
+  return measure === null ? null : measure.distance / measure.meanWeight;
+}
+
+function startsNewPositionedFragmentSequence(
+  previous: AssFragmentPart,
+  current: AssFragmentPart,
+): boolean {
+  const previousPosition = fragmentPosition(previous.cue);
+  const currentPosition = fragmentPosition(current.cue);
+  return Boolean(
+    previousPosition &&
+    currentPosition &&
+    Math.abs(currentPosition.y - previousPosition.y) <= 2 &&
+    currentPosition.x <= previousPosition.x &&
+    current.cue.startTime > previous.cue.startTime,
+  );
+}
+
+function commonLatinFragmentGap(values: readonly number[]): number {
+  const sorted = [...values].sort((left, right) => left - right);
+  // Romaji lines contain many short particles, so real word gaps can outnumber
+  // within-word transitions. A lower quantile still represents ordinary glyph advance
+  // while ignoring the narrowest character pair as an outlier.
+  return sorted[Math.floor((sorted.length - 1) * 0.35)]!;
+}
+
+function isLikelyTwoGlyphCapitalizedWord(options: {
+  parts: readonly AssFragmentPart[];
+  index: number;
+  gap: number;
+  wordGapThreshold: number;
+}): boolean {
+  const first = options.parts[options.index - 1]!;
+  const second = options.parts[options.index]!;
+  if (!/^[A-Z]$/u.test(first.text) || !/^[a-z]$/u.test(second.text)) {
+    return false;
+  }
+
+  const precedingGap =
+    options.index > 1 ? normalizedLatinFragmentGap(options.parts[options.index - 2]!, first) : null;
+  const following = options.parts[options.index + 1];
+  const followingGap = following ? normalizedLatinFragmentGap(second, following) : null;
+  const startsAtWordBoundary =
+    options.index === 1 || (precedingGap !== null && precedingGap > options.wordGapThreshold);
+
+  return (
+    startsAtWordBoundary &&
+    followingGap !== null &&
+    followingGap > options.wordGapThreshold &&
+    followingGap > options.gap * LATIN_TWO_GLYPH_WORD_NEXT_GAP_RATIO
+  );
+}
+
+/**
+ * Character-by-character typesetting often omits literal spaces because the authored
+ * word gap exists only in each glyph's `\pos`. Estimate the normal adjacent-glyph
+ * advance within that one line, then preserve only materially larger horizontal gaps.
+ * Normalizing each gap by the neighboring fragment widths supports both single glyphs
+ * and multi-character karaoke syllables without guessing from the text itself. Per-glyph
+ * runs use a wider safety margin because proportional fonts vary more than syllable chunks.
+ *
+ * The ratio test alone under-detects a word gap next to a wide fragment (`waves within`
+ * measured across `s`/`w`, or `Choices presumably` across two three-letter chunks, both
+ * normalize to nearly a common advance), so a gap also counts as a word boundary when its
+ * advance exceeds the width-predicted advance by a material fraction of the line's common
+ * unit -- a word space adds a roughly constant extra distance no matter how wide its
+ * neighbors are. Chunk runs use a tighter margin than per-glyph runs because their
+ * advances deviate less from the width model.
+ *
+ * A line may mix both conventions: one fragment carrying a literal space while its
+ * neighbors rely on position alone. Whitespace-bearing fragments have no width weight, so
+ * they drop out of the estimate and their own boundary comes from the authored space,
+ * leaving the surrounding positional gaps to be recovered normally.
+ */
+function joinAssFragmentParts(parts: readonly AssFragmentPart[]): string {
+  const normalizedGaps: number[] = [];
+  for (let index = 1; index < parts.length; index += 1) {
+    const gap = normalizedLatinFragmentGap(parts[index - 1]!, parts[index]!);
+    if (gap !== null) normalizedGaps.push(gap);
+  }
+  const isGlyphRun = parts.every((part) => isSingleLatinGlyphFragment(part.text));
+  const commonGap =
+    normalizedGaps.length >= MIN_LATIN_POSITION_GAP_SAMPLES
+      ? commonLatinFragmentGap(normalizedGaps)
+      : null;
+  const wordGapThreshold =
+    commonGap === null
+      ? Infinity
+      : commonGap * (isGlyphRun ? LATIN_GLYPH_WORD_GAP_RATIO : LATIN_FRAGMENT_WORD_GAP_RATIO);
+
+  let text = parts[0]?.text ?? '';
+  for (let index = 1; index < parts.length; index += 1) {
+    const previous = parts[index - 1]!;
+    const current = parts[index]!;
+    const hasAuthoredSpace = /\s$/u.test(previous.text) || /^\s/u.test(current.text);
+    const measure = latinFragmentGapMeasure(previous, current);
+    const normalizedGap = measure === null ? null : measure.distance / measure.meanWeight;
+    // A capital into lowercase is almost always a capitalized word's own first letters
+    // (`S|miles`), and capitals overrun the width table too easily, so the excess rule
+    // never fires there. A lone capital word like `I` is narrow enough for the ratio
+    // test to catch its word gap on its own.
+    const excessRatio = isGlyphRun ? LATIN_GLYPH_WORD_EXCESS_RATIO : LATIN_CHUNK_WORD_EXCESS_RATIO;
+    const minimumExcessSamples = isGlyphRun
+      ? MIN_LATIN_GLYPH_EXCESS_GAP_SAMPLES
+      : MIN_LATIN_CHUNK_EXCESS_GAP_SAMPLES;
+    const hasAdvanceExcess =
+      commonGap !== null &&
+      normalizedGaps.length >= minimumExcessSamples &&
+      measure !== null &&
+      !(/^[A-Z]$/u.test(previous.text) && /^[a-z]$/u.test(current.text)) &&
+      measure.distance - measure.meanWeight * commonGap > excessRatio * commonGap;
+    const hasPositionedWordGap =
+      startsNewPositionedFragmentSequence(previous, current) ||
+      (normalizedGap !== null &&
+        (normalizedGap > wordGapThreshold || hasAdvanceExcess) &&
+        !isLikelyTwoGlyphCapitalizedWord({
+          parts,
+          index,
+          gap: normalizedGap,
+          wordGapThreshold,
+        }));
+    if (!hasAuthoredSpace && hasPositionedWordGap) {
+      text += ' ';
+    }
+    text += current.text;
+  }
+  return text.trim();
+}
+
+// A tall multi-part layout is only a visual grid when its parts read like tiling
+// rather than prose: a couple of texts repeated across many fragments (sign walls),
+// the same text re-shown at the same spot over time (countdown/animation frames),
+// nothing but scattered single glyphs, or cells aligned into table columns. Wrapped
+// lyric rows with repeated karaoke syllables and CC-style dialogue blocks (speaker
+// labels plus a sentence) share the same tall geometry but stay publishable.
+function looksLikeFragmentGridParts(parts: readonly AssFragmentPart[]): boolean {
+  const positioned = parts
+    .map((part) => ({
+      text: part.text.trim(),
+      layout: part.cue.assLayout,
+      position: fragmentPosition(part.cue),
+      startTime: part.cue.startTime,
+    }))
+    .filter((part) => part.text && part.layout?.kind === 'positioned');
+  if (positioned.length === 0) return true;
+
+  const uniqueTexts = new Set(positioned.map((part) => part.text));
+  if (uniqueTexts.size * 3 <= positioned.length) return true;
+
+  if (positioned.every((part) => [...part.text].length <= 1)) return true;
+
+  const seenPlacements = new Map<string, number>();
+  for (const part of positioned) {
+    if (part.layout?.kind !== 'positioned' || !part.position) continue;
+    const placement = `${part.text}@${Math.round(part.position.x)},${Math.round(part.position.y)}`;
+    const earlierStart = seenPlacements.get(placement);
+    if (earlierStart !== undefined && Math.abs(part.startTime - earlierStart) > 0.01) {
+      return true;
+    }
+    seenPlacements.set(placement, part.startTime);
+  }
+
+  // Table cells align into columns: several x values each reused on multiple rows.
+  // Requiring two such columns holding at least half the parts keeps a wrapped lyric
+  // whose rows accidentally share one x coordinate out of the grid bucket.
+  const columnRows = new Map<number, Set<number>>();
+  for (const part of positioned) {
+    if (!part.position) continue;
+    const x = Math.round(part.position.x);
+    const rows = columnRows.get(x) ?? new Set<number>();
+    rows.add(Math.round(part.position.y));
+    columnRows.set(x, rows);
+  }
+  let alignedColumns = 0;
+  let alignedParts = 0;
+  for (const part of positioned) {
+    if (!part.position) continue;
+    if ((columnRows.get(Math.round(part.position.x))?.size ?? 0) >= 2) alignedParts += 1;
+  }
+  for (const rows of columnRows.values()) {
+    if (rows.size >= 2) alignedColumns += 1;
+  }
+  return alignedColumns >= 2 && alignedParts * 2 >= positioned.length;
+}
+
+function reconstructedAssFragmentLayout(
+  parts: readonly AssFragmentPart[],
+  owner: AnnotatedSubtitleCue,
+): AssCueLayout | undefined {
+  let positionedPartCount = 0;
+  let minimumY = Infinity;
+  let maximumY = -Infinity;
+  for (const part of parts) {
+    const layout = part.cue.assLayout;
+    if (layout?.kind !== 'positioned') continue;
+    positionedPartCount += 1;
+    minimumY = Math.min(minimumY, layout.y);
+    maximumY = Math.max(maximumY, layout.y);
+  }
+
+  if (
+    positionedPartCount >= MIN_FRAGMENT_LINE_PARTS &&
+    maximumY - minimumY > MAX_FRAGMENT_LINE_VERTICAL_SPAN &&
+    looksLikeFragmentGridParts(parts)
+  ) {
+    return { kind: 'fragment-grid', sourceOrder: owner.order };
+  }
+  return owner.assLayout;
+}
+
+interface AssFragmentTimingCluster {
+  events: AnnotatedSubtitleCue[];
+  minStartTime: number;
+  maxStartTime: number;
+  minEndTime: number;
+  maxEndTime: number;
+}
+
+function addToFragmentTimingCluster(
+  cluster: AssFragmentTimingCluster,
+  cue: AnnotatedSubtitleCue,
+): void {
+  cluster.events.push(cue);
+  cluster.minStartTime = Math.min(cluster.minStartTime, cue.startTime);
+  cluster.maxStartTime = Math.max(cluster.maxStartTime, cue.startTime);
+  cluster.minEndTime = Math.min(cluster.minEndTime, cue.endTime);
+  cluster.maxEndTime = Math.max(cluster.maxEndTime, cue.endTime);
+}
+
+function fragmentTimingDistance(
+  cluster: AssFragmentTimingCluster,
+  cue: AnnotatedSubtitleCue,
+): number {
+  const nextMinStart = Math.min(cluster.minStartTime, cue.startTime);
+  const nextMaxStart = Math.max(cluster.maxStartTime, cue.startTime);
+  const nextMinEnd = Math.min(cluster.minEndTime, cue.endTime);
+  const nextMaxEnd = Math.max(cluster.maxEndTime, cue.endTime);
+  if (
+    nextMaxStart - nextMinStart > MAX_FRAGMENT_LINE_TIMING_VARIANCE_SECONDS ||
+    nextMaxEnd - nextMinEnd > MAX_FRAGMENT_LINE_TIMING_VARIANCE_SECONDS
+  ) {
+    return Infinity;
+  }
+  return (
+    Math.abs(cue.startTime - (cluster.minStartTime + cluster.maxStartTime) / 2) +
+    Math.abs(cue.endTime - (cluster.minEndTime + cluster.maxEndTime) / 2)
+  );
+}
+
+function clusterAssFragmentEvents(
+  events: readonly AnnotatedSubtitleCue[],
+): AssFragmentTimingCluster[] {
+  const clusters: AssFragmentTimingCluster[] = [];
+  for (const cue of events) {
+    let nearest: AssFragmentTimingCluster | null = null;
+    let nearestDistance = Infinity;
+    for (const cluster of clusters) {
+      const distance = fragmentTimingDistance(cluster, cue);
+      if (distance < nearestDistance) {
+        nearest = cluster;
+        nearestDistance = distance;
+      }
+    }
+    if (nearest) {
+      addToFragmentTimingCluster(nearest, cue);
+    } else {
+      clusters.push({
+        events: [cue],
+        minStartTime: cue.startTime,
+        maxStartTime: cue.startTime,
+        minEndTime: cue.endTime,
+        maxEndTime: cue.endTime,
+      });
+    }
+  }
+  return clusters;
+}
+
+interface FragmentInterval {
+  startTime: number;
+  endTime: number;
+}
+
+/** Event time ranges with repeated same-text, same-time layer copies collapsed. */
+function distinctFragmentIntervals(events: readonly AnnotatedSubtitleCue[]): FragmentInterval[] {
+  const intervals: FragmentInterval[] = [];
+  const previousEvents: AnnotatedSubtitleCue[] = [];
+  for (const event of events) {
+    const compactText = compactCueMatchText(event);
+    const isLayerCopy = previousEvents.some(
+      (previous) =>
+        compactCueMatchText(previous) === compactText &&
+        previous.startTime === event.startTime &&
+        previous.endTime === event.endTime &&
+        isRepeatedFragmentCopy(previous, event),
+    );
+    previousEvents.push(event);
+    if (isLayerCopy) continue;
+    intervals.push({ startTime: event.startTime, endTime: event.endTime });
+  }
+  return intervals.sort((a, b) => a.startTime - b.startTime || a.endTime - b.endTime);
+}
+
+function intervalsNeverCoexist(intervals: readonly FragmentInterval[]): boolean {
+  let latestEnd = -Infinity;
+  for (const interval of intervals) {
+    if (interval.startTime < latestEnd - 0.001) {
+      return false;
+    }
+    latestEnd = Math.max(latestEnd, interval.endTime);
+  }
+  return true;
+}
+
+// A sweep progresses through the syllables of a lyric, so its events carry different
+// texts. Sequential same-text repaints are one shaking line being redrawn, and its text
+// must survive to the raw/burst path rather than be suppressed as decoration.
+function hasMultipleFragmentTexts(events: readonly AnnotatedSubtitleCue[]): boolean {
+  const first = events[0] ? compactCueMatchText(events[0]) : '';
+  return events.some((event) => compactCueMatchText(event) !== first);
+}
+
+/**
+ * A karaoke highlight sweep repaints one syllable at a time over an already-visible
+ * lyric line: each event ends as the next begins, so the cluster's concatenated text is
+ * never on screen as a whole. Publishing it would emit rolling partial copies of the
+ * lyric ("to sou omo" beside "akenakute ii to sou omotteta"). Layer copies share one
+ * placement and timing, so the test is whether any two distinct placements coexist.
+ */
+function isProgressiveHighlightSweep(events: readonly AnnotatedSubtitleCue[]): boolean {
+  if (!hasMultipleFragmentTexts(events)) {
+    return false;
+  }
+  const intervals = distinctFragmentIntervals(events);
+  return intervals.length >= 2 && intervalsNeverCoexist(intervals);
+}
+
+/**
+ * Timing clusters split a long sweep unevenly, leaving stragglers the per-cluster check
+ * cannot judge: a two-event tail reconstructs on relaxed evidence, and a lone held
+ * syllable stays raw and publishes as its own flickering cue. When an entire style group
+ * reads as one chained repaint -- many short positioned animated fragments, no two ever
+ * on screen together, transitions mostly back-to-back -- the whole group is highlight
+ * decoration and none of it is publishable text. Independent one-off signs sharing a
+ * style stay published: they are few, longer, or separated by real gaps.
+ */
+function isProgressiveHighlightSweepGroup(events: readonly AnnotatedSubtitleCue[]): boolean {
+  if (
+    events.length > MAX_SWEEP_GROUP_EVENTS ||
+    sourceEventCount(events) < MIN_FRAGMENT_LINE_EVENTS ||
+    !hasMultipleFragmentTexts(events) ||
+    !events.every((event) => fragmentPlacementAnchors(event).size > 0) ||
+    !hasAssAnimationEvidence(events)
+  ) {
+    return false;
+  }
+  const lengths = events
+    .map((event) => compactCueMatchText(event).length)
+    .sort((left, right) => left - right);
+  if ((lengths[Math.floor(lengths.length / 2)] ?? Infinity) > MAX_FRAGMENT_MEDIAN_LENGTH) {
+    return false;
+  }
+  const intervals = distinctFragmentIntervals(events);
+  if (intervals.length < 2 || !intervalsNeverCoexist(intervals)) {
+    return false;
+  }
+  let abutting = 0;
+  for (let index = 1; index < intervals.length; index += 1) {
+    if (Math.abs(intervals[index]!.startTime - intervals[index - 1]!.endTime) <= 0.1) {
+      abutting += 1;
+    }
+  }
+  return abutting * 2 >= intervals.length - 1;
+}
+
+function decodeSingleAssFragment(cue: AnnotatedSubtitleCue): string | null {
+  const visibleLines = decodeSubtitleCueText(cue.rawText)
+    .split('\n')
+    .filter((line) => line.trim().length > 0);
+  return visibleLines.length === 1 ? visibleLines[0]! : null;
+}
+
+/**
+ * One cluster can hold the same authored text at two granularities: a whole-line event
+ * and the per-glyph events that spell it (an assembly effect renders the line while its
+ * glyph particles converge). Joining both doubles the line. A consecutive run of two or
+ * more parts that concatenates to exactly another part's text is that part's fragment
+ * layer; the whole part keeps the authored spacing, so the run is dropped. Single equal
+ * parts are never dropped -- a repeated word in a lyric is real text, not a layer.
+ *
+ * Spelling alone is not proof: repeated digits after a thousands group also concatenate
+ * to the earlier fragment's text while being real continuation. A duplicate layer sits
+ * on top of its fragments, so the whole part's anchor must fall inside the run's
+ * positional span; text that merely continues the line sits beyond it.
+ */
+function isWholePartOverItsRun(whole: AssFragmentPart, run: readonly AssFragmentPart[]): boolean {
+  const wholePosition = fragmentPosition(whole.cue);
+  if (!wholePosition) {
+    return true;
+  }
+  const xs = run
+    .map((part) => fragmentPosition(part.cue)?.x)
+    .filter((x): x is number => Number.isFinite(x));
+  if (xs.length === 0) {
+    return true;
+  }
+  return wholePosition.x >= Math.min(...xs) && wholePosition.x <= Math.max(...xs);
+}
+
+function dropFragmentRunsCoveredByWholeParts(parts: AssFragmentPart[]): AssFragmentPart[] {
+  if (parts.length > MAX_FRAGMENT_COLLAPSE_PARTS) {
+    return parts;
+  }
+  const kept = [...parts];
+  let changed = true;
+  while (changed) {
+    changed = false;
+    const wholes = [...kept].sort(
+      (left, right) =>
+        compactAssMatchText(right.text).length - compactAssMatchText(left.text).length,
+    );
+    for (const whole of wholes) {
+      const wholeText = compactAssMatchText(whole.text);
+      if ([...wholeText].length < 2) {
+        break;
+      }
+      for (let start = 0; start < kept.length && !changed; start += 1) {
+        if (kept[start] === whole) {
+          continue;
+        }
+        let combined = '';
+        for (let end = start; end < kept.length; end += 1) {
+          if (kept[end] === whole) {
+            break;
+          }
+          combined += compactAssMatchText(kept[end]!.text);
+          if (!wholeText.startsWith(combined)) {
+            break;
+          }
+          if (combined === wholeText) {
+            const run = kept.slice(start, end + 1);
+            if (end > start && isWholePartOverItsRun(whole, run)) {
+              kept.splice(start, end - start + 1);
+              changed = true;
+            }
+            break;
+          }
+        }
+      }
+      if (changed) {
+        break;
+      }
+    }
+  }
+  return kept;
+}
+
+function reconstructAssFragmentLine(
+  events: readonly AnnotatedSubtitleCue[],
+): AnnotatedSubtitleCue | null {
+  const hasRelaxedEvidence = hasRelaxedAssFragmentEvidence(events);
+  const minimumEvents = hasRelaxedEvidence ? 2 : MIN_FRAGMENT_LINE_EVENTS;
+  // Coalesced copies stand in for their source events, so animation-volume thresholds
+  // count sources: a merged four-phase glyph is still four generated events of evidence.
+  if (sourceEventCount(events) < minimumEvents || !hasAssAnimationEvidence(events)) {
+    return null;
+  }
+
+  const collected: AssFragmentPart[] = [];
+  for (const cue of events) {
+    const text = decodeSingleAssFragment(cue);
+    if (text === null) {
+      return null;
+    }
+    const compactText = compactAssMatchText(text);
+    const isLayerCopy = collected.some(
+      (part) =>
+        compactAssMatchText(part.text) === compactText && isRepeatedFragmentCopy(part.cue, cue),
+    );
+    if (!isLayerCopy) {
+      collected.push({ cue, text });
+    }
+  }
+  const minimumParts = hasRelaxedEvidence ? 1 : MIN_FRAGMENT_LINE_PARTS;
+  if (
+    collected.length < minimumParts ||
+    (!hasRelaxedEvidence && collected.length === sourceEventCount(events))
+  ) {
+    return null;
+  }
+  // A cluster whose every part is one identical glyph is a particle field, not a line.
+  // Reconstructing it would also break the surviving particles' same-text chain that
+  // burst deduplication collapses downstream.
+  if (collected.length >= 2) {
+    const firstText = compactAssMatchText(collected[0]!.text);
+    if (
+      [...firstText].length === 1 &&
+      collected.every((part) => compactAssMatchText(part.text) === firstText)
+    ) {
+      return null;
+    }
+  }
+  // The granularity gate judges the cluster as authored, so it runs before redundant
+  // whole-vs-fragments layers collapse: a line plus its glyph swarm is fragment-sized
+  // work even though only the whole-line part survives into the join.
+  const lengths = collected
+    .map((part) => compactAssMatchText(part.text).length)
+    .sort((left, right) => left - right);
+  if ((lengths[Math.floor(lengths.length / 2)] ?? Infinity) > MAX_FRAGMENT_MEDIAN_LENGTH) {
+    return null;
+  }
+  const parts = dropFragmentRunsCoveredByWholeParts(collected);
+
+  const text = joinAssFragmentParts(parts);
+  if (!text) {
+    return null;
+  }
+  const owner = parts[0]!.cue;
+  const animationStartTime = earliestStartTime(events);
+  const animationEndTime = latestEndTime(events);
+  // Publish the window where the line reads as sung text. Transparent pre-echoes render
+  // the upcoming line before its first syllable, and exit ghosts fade past the hold, so
+  // the raw span makes consecutive lyrics overlap on screen. The line starts with its
+  // first opaque copy and holds until the last statically anchored one ends; a line
+  // placed entirely by `\move` has no hold phase and keeps its full visible span.
+  const sources = events.flatMap((event) => [...sourceEventsOf(event)]);
+  const visibleSources = sources.filter((source) => !isTransparentFillEcho(source));
+  const displaySources = visibleSources.length > 0 ? visibleSources : sources;
+  const heldSources = displaySources.filter((source) =>
+    source.overrides.some((command) => !command.animated && command.name.toLowerCase() === 'pos'),
+  );
+  return {
+    ...owner,
+    startTime: earliestStartTime(displaySources),
+    endTime: latestEndTime(heldSources.length > 0 ? heldSources : displaySources),
+    text,
+    rawText: text,
+    source: 'reconstructed-ass',
+    animationStartTime,
+    animationEndTime,
+    assLayout: reconstructedAssFragmentLayout(parts, owner),
+    overrides: [],
+    overrideSignature: '',
+  };
+}
+
+// `\fnSplit splat splodge` tokenizes as name `fnSplit` + args `splat splodge`, while
+// `\fnArial` is all name and `\fn04b` is all args, so the font is both pieces rejoined.
+function staticFontOverride(cue: AnnotatedSubtitleCue): string | null {
+  let font: string | null = null;
+  for (const command of cue.overrides) {
+    if (command.animated || !command.name.toLowerCase().startsWith('fn')) continue;
+    font = [command.name.slice(2), command.args].filter(Boolean).join(' ').trim().toLowerCase();
+  }
+  return font;
+}
+
+const MIN_TEXTURE_GLYPH_RUN = 8;
+const MIN_TEXTURE_ALPHA_OVERRIDES = 6;
+// Texture payloads switch secondary alpha at nearly every glyph. Authored text that a
+// typesetter styles in syllable or word chunks measures two or more glyphs per
+// override, so the seed test demands per-glyph density.
+const MAX_TEXTURE_GLYPHS_PER_ALPHA_OVERRIDE = 1.5;
+const MIN_TEXTURE_LAYER_ALPHA = 0xe0;
+const MAX_TEXTURE_PAYLOAD_FONT_SIZE = 12;
+const MIN_TEXTURE_PAYLOAD_LINES = 3;
+const ASS_ALPHA_VALUE_PATTERN = /^&?H([0-9a-f]{1,2})&?$/iu;
+const ASS_FONT_WEIGHT_SUFFIX_PATTERN =
+  /\s+(?:black|bold|heavy|light|medium|regular|semibold|thin)$/u;
+
+function hasStaticOverride(cue: AnnotatedSubtitleCue, expectedName: string): boolean {
+  return cue.overrides.some(
+    (command) => !command.animated && command.name.toLowerCase() === expectedName,
+  );
+}
+
+function isRepeatedGlyphText(cue: AnnotatedSubtitleCue): boolean {
+  const glyphs = [...compactCueMatchText(cue)];
+  return glyphs.length > 0 && glyphs.every((glyph) => glyph === glyphs[0]);
+}
+
+function isClippedRepeatedGlyphFragment(cue: AnnotatedSubtitleCue): boolean {
+  return (
+    isRepeatedGlyphText(cue) && (hasStaticOverride(cue, 'clip') || hasStaticOverride(cue, 'iclip'))
+  );
+}
+
+/**
+ * Some ASS signs build image textures from clipped placeholder glyphs, optionally through
+ * a texture font. A long clipped single-glyph run or frequent changing secondary alpha
+ * tags identifies the effect without guessing from its visible text or font name.
+ */
+function isAssTextureSeed(cue: AnnotatedSubtitleCue): boolean {
+  if (fragmentPosition(cue) === null) {
+    return false;
+  }
+
+  // A truncated capture can leave tag debris after the placeholder run, so the seed
+  // test looks for a long same-glyph run inside the clipped text rather than requiring
+  // the whole event to be uniform.
+  const glyphs = [...compactCueMatchText(cue)];
+  if (hasStaticOverride(cue, 'clip') || hasStaticOverride(cue, 'iclip')) {
+    let longestRun = 0;
+    let run = 0;
+    let previous = '';
+    for (const glyph of glyphs) {
+      run = glyph === previous ? run + 1 : 1;
+      previous = glyph;
+      longestRun = Math.max(longestRun, run);
+    }
+    if (longestRun >= MIN_TEXTURE_GLYPH_RUN) {
+      return true;
+    }
+  }
+
+  if (staticFontOverride(cue) === null) {
+    return false;
+  }
+
+  const secondaryAlpha = cue.overrides.filter(
+    (command) => !command.animated && command.name.toLowerCase() === '2a',
+  );
+  if (secondaryAlpha.length < MIN_TEXTURE_ALPHA_OVERRIDES) {
+    return false;
+  }
+  // Real signs can alternate secondary alpha between words. Texture payloads switch it
+  // per glyph, so sparse word-level styling must not seed a texture-font group.
+  if (glyphs.length > secondaryAlpha.length * MAX_TEXTURE_GLYPHS_PER_ALPHA_OVERRIDE) {
+    return false;
+  }
+  const alphaValues = secondaryAlpha.map((command) => command.args.toLowerCase());
+  return new Set(alphaValues).size >= 2;
+}
+
+function staticGlobalAlpha(cue: AnnotatedSubtitleCue): number | null {
+  return staticAlphaOverride(cue, 'alpha');
+}
+
+function staticAlphaOverride(cue: AnnotatedSubtitleCue, expectedName: string): number | null {
+  let alpha: number | null = null;
+  for (const command of cue.overrides) {
+    if (command.animated || command.name.toLowerCase() !== expectedName) continue;
+    const match = ASS_ALPHA_VALUE_PATTERN.exec(command.args.trim());
+    const alphaValue = match?.[1];
+    if (alphaValue !== undefined) {
+      alpha = Number.parseInt(alphaValue, 16);
+    }
+  }
+  return alpha;
+}
+
+function hasAnimatedAlphaOverride(cue: AnnotatedSubtitleCue): boolean {
+  return cue.overrides.some((command) => {
+    if (!command.animated) return false;
+    const name = command.name.toLowerCase();
+    return name === '1a' || name === 'alpha';
+  });
+}
+
+// `\alpha&HFF&` blanks all four layers, but a later component override can turn one
+// back on: chant overlays render entirely through `\4a&H00&` shadows. Any re-enabled
+// layer means the event draws real text.
+const ASS_COMPONENT_ALPHA_NAMES = ['1a', '2a', '3a', '4a'] as const;
+
+function hasVisibleComponentAlpha(cue: AnnotatedSubtitleCue): boolean {
+  return ASS_COMPONENT_ALPHA_NAMES.some((name) => {
+    const value = staticAlphaOverride(cue, name);
+    return value !== null && value < 0xff;
+  });
+}
+
+/**
+ * A glyph copy whose fill is statically fully transparent and never animated back in is
+ * a glow or outline echo of the real glyph, not the text itself. A coalesced copy chain
+ * counts only when every phase in it is such an echo; one opaque phase means the chain
+ * carries the authored glyph.
+ */
+function isTransparentFillEcho(cue: AnnotatedSubtitleCue): boolean {
+  return sourceEventsOf(cue).every(
+    (source) =>
+      (staticAlphaOverride(source, '1a') === 0xff ||
+        staticAlphaOverride(source, 'alpha') === 0xff) &&
+      !hasAnimatedAlphaOverride(source) &&
+      !hasVisibleComponentAlpha(source),
+  );
+}
+
+function staticFontSize(cue: AnnotatedSubtitleCue): number | null {
+  let fontSize: number | null = null;
+  for (const command of cue.overrides) {
+    if (command.animated || command.name.toLowerCase() !== 'fs') continue;
+    const value = Number(command.args.trim());
+    if (Number.isFinite(value) && value > 0) {
+      fontSize = value;
+    }
+  }
+  return fontSize;
+}
+
+function isNearlyTransparentPositionedText(cue: AnnotatedSubtitleCue): boolean {
+  const alpha = staticGlobalAlpha(cue);
+  return (
+    alpha !== null &&
+    alpha >= MIN_TEXTURE_LAYER_ALPHA &&
+    staticFontOverride(cue) !== null &&
+    fragmentPosition(cue) !== null
+  );
+}
+
+function hasAssTextureCandidateEvidence(cue: AnnotatedSubtitleCue): boolean {
+  return (
+    isClippedRepeatedGlyphFragment(cue) ||
+    isNearlyTransparentPositionedText(cue) ||
+    hasStaticOverride(cue, '2a')
+  );
+}
+
+function textureFontFamilyKey(font: string): string {
+  return font.replace(ASS_FONT_WEIGHT_SUFFIX_PATTERN, '');
+}
+
+function isTextureFontPayload(
+  cue: AnnotatedSubtitleCue,
+  textureFontFamilies: ReadonlySet<string>,
+): boolean {
+  const font = staticFontOverride(cue);
+  const fontSize = staticFontSize(cue);
+  const visibleLines = cue.text.split('\n').filter((line) => line.trim().length > 0);
+  return (
+    font !== null &&
+    textureFontFamilies.has(textureFontFamilyKey(font)) &&
+    fontSize !== null &&
+    fontSize <= MAX_TEXTURE_PAYLOAD_FONT_SIZE &&
+    staticGlobalAlpha(cue) !== null &&
+    fragmentPosition(cue) !== null &&
+    visibleLines.length >= MIN_TEXTURE_PAYLOAD_LINES
+  );
+}
+
+// A sign translation can legitimately render faint text through one or two positioned
+// events. Dozens of them sharing one window is a texture: near-invisible glyph strings
+// laid out as pixels of an image, with no visible-text sibling to anchor them.
+const MIN_TEXTURE_WALL_EVENTS = 6;
+
+function textureWallGroupKey(cue: AnnotatedSubtitleCue): string {
+  return `${cue.style}\0${cue.startTime}\0${cue.endTime}`;
+}
+
+/** Static zero scale or a degenerate static clip renders nothing, unless animation can
+ * still bring the event into view (an entrance growing from `\fscx0`, a clip wipe).
+ * Only an animated scale or clip reveals; `\t(...)` wrapping some other property leaves
+ * the event invisible. Nested `\t(...)` needs no special case because the tags it
+ * animates are recorded as animated in their own right. */
+function isInvisiblyRenderedEvent(cue: AnnotatedSubtitleCue): boolean {
+  let staticZeroScale = false;
+  let staticZeroClip = false;
+  let animatedReveal = false;
+  for (const command of cue.overrides) {
+    const name = command.name.toLowerCase();
+    if (command.animated) {
+      if (name === 'fscx' || name === 'fscy' || name === 'clip') {
+        animatedReveal = true;
+      }
+      continue;
+    }
+    if (name === 'fscx' || name === 'fscy') {
+      if (Number(command.args.trim()) === 0) {
+        staticZeroScale = true;
+      }
+    } else if (name === 'clip') {
+      const args = command.args.split(',').map((value) => Number(value.trim()));
+      if (
+        args.length >= 4 &&
+        args.slice(0, 4).every(Number.isFinite) &&
+        (args[0]! >= args[2]! || args[1]! >= args[3]!)
+      ) {
+        staticZeroClip = true;
+      }
+    }
+  }
+  return (staticZeroScale || staticZeroClip) && !animatedReveal;
+}
+
+function assFontTextureGroupKey(cue: AnnotatedSubtitleCue): string | null {
+  const font = staticFontOverride(cue);
+  return font === null ? null : `${cue.style}\0${cue.startTime}\0${cue.endTime}\0${font}`;
+}
+
+function assTextureTimingGroupKey(cue: AnnotatedSubtitleCue): string {
+  return `${cue.style}\0${cue.startTime}\0${cue.endTime}`;
+}
+
+function removeAssFontTextureEvents(events: ParsedAssEvents): ParsedAssEvents {
+  const seeds = events.dialogue.filter(isAssTextureSeed);
+  const seedSet = new Set(seeds);
+  // Short pieces can share the seeded font effect under another actor. Matching the
+  // seed's style, timing, and font only narrows the candidates; each piece must still
+  // carry structural texture evidence.
+  const textureGroups = new Set(
+    seeds.map(assFontTextureGroupKey).filter((key): key is string => key !== null),
+  );
+  const noFontTextureTimings = new Set(
+    seeds
+      .filter((seed) => staticFontOverride(seed) === null)
+      .map((seed) => assTextureTimingGroupKey(seed)),
+  );
+  // Some signs switch actor and font between the texture mask and its payload. A nearly
+  // transparent text event that overlaps a proven seed in the same style is another input
+  // to that visual effect. Opaque authored text in the same sign remains publishable.
+  const seedsByStyle = new Map<string, AnnotatedSubtitleCue[]>();
+  for (const seed of seeds) {
+    const styleSeeds = seedsByStyle.get(seed.style);
+    if (styleSeeds) {
+      styleSeeds.push(seed);
+    } else {
+      seedsByStyle.set(seed.style, [seed]);
+    }
+  }
+  const seedIndexesByStyle = new Map(
+    [...seedsByStyle].map(([style, styleSeeds]) => [style, buildAssEventGroupIndex(styleSeeds)]),
+  );
+  const isAssociatedWithTextureSeed = (cue: AnnotatedSubtitleCue): boolean => {
+    const styleSeedIndex = seedIndexesByStyle.get(cue.style);
+    return (
+      styleSeedIndex !== undefined &&
+      eventsOverlappingWindow(styleSeedIndex, cue.startTime, cue.endTime).length > 0
+    );
+  };
+  const textureFontFamilies = new Set(
+    [
+      ...seeds,
+      ...events.dialogue.filter(
+        (cue) => isNearlyTransparentPositionedText(cue) && isAssociatedWithTextureSeed(cue),
+      ),
+      ...events.comments.filter(
+        (cue) => isNearlyTransparentPositionedText(cue) && isAssociatedWithTextureSeed(cue),
+      ),
+    ]
+      .map(staticFontOverride)
+      .filter((font): font is string => font !== null)
+      .map(textureFontFamilyKey),
+  );
+
+  // Wall membership additionally requires that no component alpha turns a layer back
+  // on: `\alpha&HFF&` plus a visible `\4a` renders real text through its shadow, and a
+  // sign typeset entirely from such layers must not read as a texture.
+  const isTextureWallCandidate = (cue: AnnotatedSubtitleCue): boolean =>
+    isNearlyTransparentPositionedText(cue) && !hasVisibleComponentAlpha(cue);
+  const transparentWallCounts = new Map<string, number>();
+  for (const cue of events.dialogue) {
+    if (isTextureWallCandidate(cue)) {
+      const key = textureWallGroupKey(cue);
+      transparentWallCounts.set(key, (transparentWallCounts.get(key) ?? 0) + 1);
+    }
+  }
+
+  return {
+    dialogue: events.dialogue.filter((cue) => {
+      if (isInvisiblyRenderedEvent(cue)) {
+        return false;
+      }
+      if (seedSet.has(cue)) {
+        return false;
+      }
+      if (
+        isTextureWallCandidate(cue) &&
+        (transparentWallCounts.get(textureWallGroupKey(cue)) ?? 0) >= MIN_TEXTURE_WALL_EVENTS
+      ) {
+        return false;
+      }
+      if (
+        staticFontOverride(cue) === null &&
+        noFontTextureTimings.has(assTextureTimingGroupKey(cue)) &&
+        isClippedRepeatedGlyphFragment(cue)
+      ) {
+        return false;
+      }
+      const key = assFontTextureGroupKey(cue);
+      if (key !== null && textureGroups.has(key) && hasAssTextureCandidateEvidence(cue)) {
+        return false;
+      }
+      if (isTextureFontPayload(cue, textureFontFamilies)) {
+        return false;
+      }
+      if (!isNearlyTransparentPositionedText(cue)) {
+        return true;
+      }
+      return !isAssociatedWithTextureSeed(cue);
+    }),
+    comments: events.comments,
+  };
+}
+
+/**
+ * Generated lyric effects often layer decoration over the real syllables: single letters
+ * positioned above each glyph, animated in, and rendered through a `\fn` override to a
+ * symbol font where `a` draws as a sparkle rather than a letter. Reading them as text
+ * corrupts the reconstructed line (`sotto mimi ni ateru to` gains a trailing `a z x`).
+ * Within one style/name group, a font used only for scattered animated single glyphs --
+ * while the group's actual text renders in another font -- marks those events as
+ * decoration rather than dialogue.
+ */
+function decorativeGlyphEvents(events: readonly AnnotatedSubtitleCue[]): Set<AnnotatedSubtitleCue> {
+  const byFont = new Map<string, AnnotatedSubtitleCue[]>();
+  for (const cue of events) {
+    const font = staticFontOverride(cue);
+    if (font === null) continue;
+    const group = byFont.get(font);
+    if (group) {
+      group.push(cue);
+    } else {
+      byFont.set(font, [cue]);
+    }
+  }
+
+  const decorative = new Set<AnnotatedSubtitleCue>();
+  for (const fontEvents of byFont.values()) {
+    if (fontEvents.length * 2 >= events.length) continue;
+    const allScatteredGlyphs = fontEvents.every(
+      (cue) =>
+        [...compactCueMatchText(cue)].length === 1 &&
+        fragmentPosition(cue) !== null &&
+        hasAssTemporalOverride(cue.overrides),
+    );
+    if (allScatteredGlyphs) {
+      fontEvents.forEach((cue) => decorative.add(cue));
+    }
+  }
+  return decorative;
+}
+
+function recoverFragmentOnlyAssLines(dialogue: AnnotatedSubtitleCue[]): AnnotatedSubtitleCue[] {
+  const groups = new Map<string, AnnotatedSubtitleCue[]>();
+  for (const cue of dialogue) {
+    if (cue.source !== undefined) {
+      continue;
+    }
+    const key = assEventGroupKey(cue);
+    const group = groups.get(key);
+    if (group) {
+      group.push(cue);
+    } else {
+      groups.set(key, [cue]);
+    }
+  }
+
+  const recovered: AnnotatedSubtitleCue[] = [];
+  const suppressed = new Set<AnnotatedSubtitleCue>();
+  // The published dialogue list holds source events, so a suppressed coalesced copy
+  // chain must suppress every event behind it.
+  const suppress = (event: AnnotatedSubtitleCue): void => {
+    for (const source of sourceEventsOf(event)) {
+      suppressed.add(source);
+    }
+  };
+  for (const events of groups.values()) {
+    const units = coalesceAssAnchorCopies(events);
+    const decorative = decorativeGlyphEvents(units);
+    for (const unit of units) {
+      if (
+        !decorative.has(unit) &&
+        fragmentPlacementAnchors(unit).size > 0 &&
+        isTransparentFillEcho(unit)
+      ) {
+        decorative.add(unit);
+      }
+    }
+    const lineEvents = decorative.size ? units.filter((event) => !decorative.has(event)) : units;
+    if (isProgressiveHighlightSweepGroup(lineEvents)) {
+      lineEvents.forEach(suppress);
+      const spanStart = Math.min(...lineEvents.map((event) => event.startTime));
+      const spanEnd = Math.max(...lineEvents.map((event) => event.endTime));
+      for (const overlay of decorative) {
+        if (
+          overlay.startTime < spanEnd + DECORATION_SPAN_TOLERANCE_SECONDS &&
+          overlay.endTime > spanStart - DECORATION_SPAN_TOLERANCE_SECONDS
+        ) {
+          suppress(overlay);
+        }
+      }
+      continue;
+    }
+    for (const cluster of clusterAssFragmentEvents(lineEvents)) {
+      const line = reconstructAssFragmentLine(cluster.events);
+      if (!line) {
+        continue;
+      }
+      // A sweep only re-highlights the lyric it decorates: hide its events without
+      // publishing the reconstruction.
+      if (isProgressiveHighlightSweep(cluster.events)) {
+        cluster.events.forEach(suppress);
+        continue;
+      }
+      recovered.push(line);
+      cluster.events.forEach(suppress);
+      // Decoration is timed to the line it overlays, so it disappears with the line's
+      // full animation span. Decoration outside any recovered span stays published.
+      const spanStart = line.animationStartTime ?? line.startTime;
+      const spanEnd = line.animationEndTime ?? line.endTime;
+      for (const overlay of decorative) {
+        if (
+          overlay.startTime < spanEnd + DECORATION_SPAN_TOLERANCE_SECONDS &&
+          overlay.endTime > spanStart - DECORATION_SPAN_TOLERANCE_SECONDS
+        ) {
+          suppress(overlay);
+        }
+      }
+    }
+  }
+  if (recovered.length === 0 && suppressed.size === 0) {
+    return dialogue;
+  }
+  return [
+    ...dialogue.filter((cue) => !suppressed.has(cue)),
+    ...mergeAbuttingRecoveredLines(recovered),
+  ].sort(
+    (left, right) =>
+      left.startTime - right.startTime || left.endTime - right.endTime || left.order - right.order,
+  );
+}
+
+// One authored line can reconstruct twice from consecutive effect stages -- its steady
+// glyphs, then an exit animation replaying the same text. Publishing both would show the
+// line restarting, so identical recoveries that touch in time collapse into one span.
+const RECOVERED_LINE_MERGE_GAP_SECONDS = 0.1;
+
+function mergeAbuttingRecoveredLines(recovered: AnnotatedSubtitleCue[]): AnnotatedSubtitleCue[] {
+  const byText = new Map<string, AnnotatedSubtitleCue[]>();
+  for (const line of recovered) {
+    const key = `${assEventGroupKey(line)}\0${compactAssMatchText(line.text)}`;
+    const bucket = byText.get(key);
+    if (bucket) {
+      bucket.push(line);
+    } else {
+      byText.set(key, [line]);
+    }
+  }
+
+  const merged: AnnotatedSubtitleCue[] = [];
+  for (const bucket of byText.values()) {
+    bucket.sort((left, right) => left.startTime - right.startTime || left.order - right.order);
+    let current = bucket[0]!;
+    for (let index = 1; index < bucket.length; index += 1) {
+      const next = bucket[index]!;
+      if (next.startTime <= current.endTime + RECOVERED_LINE_MERGE_GAP_SECONDS) {
+        const endTime = Math.max(current.endTime, next.endTime);
+        current = {
+          ...current,
+          endTime,
+          animationEndTime: Math.max(
+            current.animationEndTime ?? current.endTime,
+            next.animationEndTime ?? next.endTime,
+          ),
+        };
+      } else {
+        merged.push(current);
+        current = next;
+      }
+    }
+    merged.push(current);
+  }
+  return merged;
+}
+
 function groupConsecutiveAssFragments(events: readonly AnnotatedSubtitleCue[]): FragmentGroup[] {
   const groups: FragmentGroup[] = [];
   for (const event of events) {
@@ -438,7 +2005,7 @@ function recoverCanonicalAssEvents({
       .filter(
         (cue) =>
           compactCueMatchText(cue).length >= MIN_CANONICAL_DIALOGUE_TEXT_LENGTH &&
-          hasAssAnimationEvidence([cue]),
+          (cue.assLayout?.kind === 'source-order' || hasAssAnimationEvidence([cue])),
       )
       .sort((left, right) => right.text.length - left.text.length || left.order - right.order)
       .map((cue) => ({ cue, kind: 'dialogue' as const })),
@@ -473,6 +2040,9 @@ function recoverCanonicalAssEvents({
     const animationEndTime = latestEndTime(generatedEvents, candidate.endTime);
     const startTime = kind === 'comment' ? candidate.startTime : animationStartTime;
     const endTime = kind === 'comment' ? candidate.endTime : animationEndTime;
+    const assFurigana = [
+      ...new Set([candidate, ...generatedEvents].flatMap((cue) => cue.assFurigana ?? [])),
+    ];
     const recoveredCue: AnnotatedSubtitleCue = {
       ...candidate,
       startTime,
@@ -480,6 +2050,7 @@ function recoverCanonicalAssEvents({
       animationStartTime,
       animationEndTime,
       source: 'canonical-ass',
+      ...(assFurigana.length === 0 ? {} : { assFurigana }),
     };
     recovered.push(recoveredCue);
     recoveredByOwner.set(candidate, recoveredCue);
@@ -507,7 +2078,450 @@ function recoverCanonicalAssEvents({
   );
 }
 
-function parseAnnotatedAssEvents(content: string): ParsedAssEvents {
+function bandFromNumpadAlignment(alignment: number): AssVerticalBand | null {
+  if (alignment >= 7 && alignment <= 9) return 'top';
+  if (alignment >= 4 && alignment <= 6) return 'middle';
+  if (alignment >= 1 && alignment <= 3) return 'bottom';
+  return null;
+}
+
+// SSA v4 alignment reuses the legacy `\a` codes: 1-3 bottom, +4 top, +8 middle.
+function bandFromLegacyAlignment(alignment: number): AssVerticalBand | null {
+  if (alignment >= 9 && alignment <= 11) return 'middle';
+  if (alignment >= 5 && alignment <= 7) return 'top';
+  if (alignment >= 1 && alignment <= 3) return 'bottom';
+  return null;
+}
+
+interface AssPlacementContext {
+  playResY: number | null;
+  /** Lowercased style name -> vertical band from the style's Alignment column. */
+  styleBands: Map<string, AssVerticalBand>;
+}
+
+const EMPTY_PLACEMENT_CONTEXT: AssPlacementContext = { playResY: null, styleBands: new Map() };
+
+function parseAssPlacementContext(content: string): AssPlacementContext {
+  const styleBands = new Map<string, AssVerticalBand>();
+  let playResY: number | null = null;
+  let section: 'info' | 'v4plus' | 'v4' | null = null;
+  let alignmentIndex = -1;
+  let nameIndex = -1;
+
+  for (const line of content.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (trimmed.startsWith('[') && trimmed.endsWith(']')) {
+      const sectionName = trimmed.toLowerCase();
+      section =
+        sectionName === '[script info]'
+          ? 'info'
+          : sectionName === '[v4+ styles]'
+            ? 'v4plus'
+            : sectionName === '[v4 styles]'
+              ? 'v4'
+              : null;
+      alignmentIndex = -1;
+      nameIndex = -1;
+      continue;
+    }
+    if (section === 'info') {
+      const resMatch = trimmed.match(/^playresy\s*:\s*(\d+(?:\.\d+)?)\s*$/i);
+      if (resMatch) playResY = Number(resMatch[1]);
+      continue;
+    }
+    if (section !== 'v4plus' && section !== 'v4') continue;
+    const separator = trimmed.indexOf(':');
+    if (separator < 0) continue;
+    const key = trimmed.slice(0, separator).trim().toLowerCase();
+    const fields = trimmed.slice(separator + 1).split(',');
+    if (key === 'format') {
+      const names = fields.map((field) => field.trim().toLowerCase());
+      alignmentIndex = names.indexOf('alignment');
+      nameIndex = names.indexOf('name');
+      continue;
+    }
+    if (key !== 'style' || alignmentIndex < 0 || nameIndex < 0) continue;
+    const styleName = fields[nameIndex]?.trim().toLowerCase();
+    const alignment = Number(fields[alignmentIndex]?.trim());
+    if (!styleName || !Number.isFinite(alignment)) continue;
+    const band =
+      section === 'v4plus'
+        ? bandFromNumpadAlignment(alignment)
+        : bandFromLegacyAlignment(alignment);
+    if (band) styleBands.set(styleName, band);
+  }
+
+  return { playResY, styleBands };
+}
+
+/**
+ * Where on screen mpv will draw this event: an explicit `\pos`/`\move` coordinate when
+ * the script declares its coordinate space, else an `\an`/`\a` override, else the
+ * style's Alignment. Constant for the life of the event, which is what lets simultaneous
+ * lines keep a stable stacking order in the overlay.
+ */
+function resolveVerticalBand(
+  overrides: readonly AssOverrideCommand[],
+  y: number | null,
+  style: string,
+  context: AssPlacementContext,
+): AssVerticalBand | undefined {
+  if (y !== null && context.playResY && context.playResY > 0) {
+    const ratio = y / context.playResY;
+    return ratio < 1 / 3 ? 'top' : ratio < 2 / 3 ? 'middle' : 'bottom';
+  }
+  for (const command of overrides) {
+    if (command.animated) continue;
+    const name = command.name.toLowerCase();
+    if (name !== 'an' && name !== 'a') continue;
+    const band =
+      name === 'an'
+        ? bandFromNumpadAlignment(Number(command.args))
+        : bandFromLegacyAlignment(Number(command.args));
+    if (band) return band;
+  }
+  return context.styleBands.get(style.trim().toLowerCase());
+}
+
+function parseAssCoordinate(value: string | undefined): number | null {
+  if (!value?.trim()) return null;
+  const coordinate = Number(value.trim());
+  return Number.isFinite(coordinate) ? coordinate : null;
+}
+
+function buildAssCueLayout(
+  overrides: readonly AssOverrideCommand[],
+  sourceOrder: number,
+  style: string,
+  placement: AssPlacementContext,
+): AssCueLayout {
+  let x: number | null = null;
+  let y: number | null = null;
+  for (const command of overrides) {
+    if (command.animated) continue;
+    const name = command.name.toLowerCase();
+    const args = command.args.split(',');
+    if (name === 'pos') {
+      x = parseAssCoordinate(args[0]) ?? x;
+      y = parseAssCoordinate(args[1]) ?? y;
+      continue;
+    }
+    if (name !== 'move') continue;
+    const startX = parseAssCoordinate(args[0]);
+    const startY = parseAssCoordinate(args[1]);
+    const endX = parseAssCoordinate(args[2]);
+    const endY = parseAssCoordinate(args[3]);
+    if (startX !== null && endX !== null) {
+      x = (startX + endX) / 2;
+    }
+    if (startY !== null && endY !== null) {
+      y = (startY + endY) / 2;
+    }
+  }
+  const verticalBand = resolveVerticalBand(overrides, y, style, placement);
+  const base: AssCueLayout =
+    y === null
+      ? { kind: 'source-order', sourceOrder }
+      : { kind: 'positioned', sourceOrder, ...(x === null ? {} : { x }), y };
+  return verticalBand ? { ...base, verticalBand } : base;
+}
+
+const ASS_FURIGANA_TEXT_PATTERN = /^[\p{Script=Hiragana}\p{Script=Katakana}ー・ \t\u3000]+$/u;
+const ASS_KANJI_PATTERN = /\p{Script=Han}/u;
+const MAX_ASS_FURIGANA_SCALE_PERCENT = 60;
+// The pixel geometry below is authored in the 540-line coordinate space Caption2Ass-style
+// broadcast CC converters emit, and is multiplied by PlayResY/540 so the same on-screen
+// window applies to scripts declaring other resolutions. Without a declaration the tuned
+// space is assumed.
+const ASS_FURIGANA_REFERENCE_PLAY_RES_Y = 540;
+const MIN_ASS_FURIGANA_BASE_GAP = 40;
+const MAX_ASS_FURIGANA_BASE_GAP = 68;
+const MIN_ASS_FURIGANA_HORIZONTAL_TOLERANCE = 80;
+const ASS_BASE_CHARACTER_WIDTH_ESTIMATE = 40;
+
+function assFuriganaGeometryScale(playResY: number | null): number {
+  return playResY && playResY > 0 ? playResY / ASS_FURIGANA_REFERENCE_PLAY_RES_Y : 1;
+}
+
+function staticAssScalePercent(cue: AnnotatedSubtitleCue, axis: 'fscx' | 'fscy'): number | null {
+  let scale: number | null = null;
+  for (const command of cue.overrides) {
+    if (command.animated || command.name.toLowerCase() !== axis) continue;
+    const value = Number(command.args.trim());
+    if (Number.isFinite(value) && value > 0) {
+      scale = value;
+    }
+  }
+  return scale;
+}
+
+function isAssFuriganaCandidate(cue: AnnotatedSubtitleCue): boolean {
+  const scaleX = staticAssScalePercent(cue, 'fscx');
+  const scaleY = staticAssScalePercent(cue, 'fscy');
+  return (
+    cue.assLayout?.kind === 'positioned' &&
+    ASS_FURIGANA_TEXT_PATTERN.test(cue.text) &&
+    scaleX !== null &&
+    scaleX <= MAX_ASS_FURIGANA_SCALE_PERCENT &&
+    scaleY !== null &&
+    scaleY <= MAX_ASS_FURIGANA_SCALE_PERCENT
+  );
+}
+
+function findAssFuriganaBase(
+  furigana: AnnotatedSubtitleCue,
+  cues: readonly AnnotatedSubtitleCue[],
+  geometryScale: number,
+): AnnotatedSubtitleCue | null {
+  if (furigana.assLayout?.kind !== 'positioned' || furigana.assLayout.x === undefined) {
+    return null;
+  }
+
+  let nearest: { cue: AnnotatedSubtitleCue; gap: number } | null = null;
+  for (const cue of cues) {
+    if (
+      cue === furigana ||
+      cue.startTime !== furigana.startTime ||
+      cue.endTime !== furigana.endTime ||
+      cue.style !== furigana.style ||
+      cue.layer !== furigana.layer ||
+      cue.name !== furigana.name ||
+      cue.assLayout?.kind !== 'positioned' ||
+      !ASS_KANJI_PATTERN.test(cue.text)
+    ) {
+      continue;
+    }
+    const scaleY = staticAssScalePercent(cue, 'fscy');
+    if (scaleY !== null && scaleY <= MAX_ASS_FURIGANA_SCALE_PERCENT) continue;
+
+    const gap = cue.assLayout.y - furigana.assLayout.y;
+    if (
+      gap < MIN_ASS_FURIGANA_BASE_GAP * geometryScale ||
+      gap > MAX_ASS_FURIGANA_BASE_GAP * geometryScale
+    ) {
+      continue;
+    }
+    if (cue.assLayout.x === undefined) continue;
+    const baseCharacterCount = [...cue.text.replace(/[ \t\u3000]/g, '')].length;
+    const horizontalTolerance =
+      Math.max(
+        MIN_ASS_FURIGANA_HORIZONTAL_TOLERANCE,
+        baseCharacterCount * ASS_BASE_CHARACTER_WIDTH_ESTIMATE,
+      ) * geometryScale;
+    if (Math.abs(cue.assLayout.x - furigana.assLayout.x) > horizontalTolerance) continue;
+    if (!nearest || gap < nearest.gap || (gap === nearest.gap && cue.order < nearest.cue.order)) {
+      nearest = { cue, gap };
+    }
+  }
+  return nearest?.cue ?? null;
+}
+
+function removeAssFuriganaFromCueList(
+  cues: AnnotatedSubtitleCue[],
+  geometryScale: number,
+): AnnotatedSubtitleCue[] {
+  const removed = new Set<AnnotatedSubtitleCue>();
+  for (const cue of cues) {
+    if (!isAssFuriganaCandidate(cue)) continue;
+    const base = findAssFuriganaBase(cue, cues, geometryScale);
+    if (!base) continue;
+    base.assFurigana = [...new Set([...(base.assFurigana ?? []), cue.text])];
+    removed.add(cue);
+  }
+  return removed.size === 0 ? cues : cues.filter((cue) => !removed.has(cue));
+}
+
+function removeAssFuriganaEvents(
+  events: ParsedAssEvents,
+  playResY: number | null,
+): ParsedAssEvents {
+  const geometryScale = assFuriganaGeometryScale(playResY);
+  return {
+    dialogue: removeAssFuriganaFromCueList(events.dialogue, geometryScale),
+    comments: removeAssFuriganaFromCueList(events.comments, geometryScale),
+  };
+}
+
+// Broadcast-caption converters give every visual row of one utterance its own positioned
+// event, so a sentence that wraps arrives as two simultaneous cues with the same timing,
+// style, and vertical band. Captions punctuate every finished utterance, and each turn
+// opens with a speaker label or a ≪…≫ / ⸨…⸩ span, which is what tells a wrapped sentence
+// apart from two speakers sharing the screen.
+const CAPTION_SPEAKER_LABEL_ONLY_PATTERN = /^（[^（）]*）$/u;
+const CAPTION_SPEAKER_LABEL_PATTERN = /^（/u;
+const CAPTION_TURN_OPENER_PATTERN = /^[≪⸨（]/u;
+const CAPTION_TERMINAL_PATTERN = /[。？！?!…‥～〜➡⁉⁈≫⸩）」』]$/u;
+const CAPTION_SPANS: ReadonlyArray<readonly [open: string, close: string]> = [
+  ['≪', '≫'],
+  ['⸨', '⸩'],
+];
+// Rows of one utterance sit one text row apart (about 60 units in the 540-line space the
+// furigana geometry is tuned for), or two when a ruby row lies between them. Rows at the
+// same height sit side by side, and rows further apart are separate placements.
+const MAX_CAPTION_ROW_GAP = 120;
+// Only a broadcast-caption script gets rows joined. Typesetters position rows for signs,
+// chat bubbles, and lyric stacks too, and there the continuation rule below has no
+// convention to read: sign text rarely carries sentence punctuation, so unrelated rows
+// would run together. A caption script announces itself by labelling speakers （名） and
+// bracketing off-screen speech in ≪…≫ / ⸨…⸩; typeset scripts use those in a handful of
+// lines at most. Measured over local tracks, caption scripts sit near 25% and every typeset
+// script below 1%, so the threshold has room on both sides. It is deliberately strict: a
+// caption script wrongly held back just keeps one sentence on two rows, while a typeset
+// script wrongly let through concatenates unrelated signs.
+const MIN_CAPTION_EVIDENCE_EVENTS = 2;
+const MIN_CAPTION_EVIDENCE_RATIO = 0.05;
+const CAPTION_EVIDENCE_PATTERN = /^（[^（）]{1,14}）|[≪⸨]/u;
+// Rows that carry no Japanese are not the broadcast captions this pass targets.
+const JAPANESE_SCRIPT_PATTERN = /[\p{Script=Hiragana}\p{Script=Katakana}\p{Script=Han}]/u;
+
+function hasBroadcastCaptionConventions(cues: readonly AnnotatedSubtitleCue[]): boolean {
+  let evidence = 0;
+  let published = 0;
+  for (const cue of cues) {
+    if (!cue.text.trim()) continue;
+    published += 1;
+    if (CAPTION_EVIDENCE_PATTERN.test(cue.text)) evidence += 1;
+  }
+  return (
+    evidence >= MIN_CAPTION_EVIDENCE_EVENTS && evidence >= published * MIN_CAPTION_EVIDENCE_RATIO
+  );
+}
+
+function captionSpanDepth(text: string, [open, close]: readonly [string, string]): number {
+  let depth = 0;
+  for (const char of text) {
+    if (char === open) depth += 1;
+    else if (char === close) depth -= 1;
+  }
+  return depth;
+}
+
+/**
+ * Whether `lower` continues the utterance `upper` started, both being simultaneous
+ * caption rows. A bare speaker label labels the row beneath it. Otherwise the upper row
+ * must not have finished: it ends without terminal punctuation, or a ≪…≫ / ⸨…⸩ span it
+ * opened is still open (closing 」 inside such a span is not an ending). A lower row that
+ * opens its own turn is always a different line.
+ */
+function isCaptionRowContinuation(upper: string, lower: string): boolean {
+  if (CAPTION_SPEAKER_LABEL_ONLY_PATTERN.test(upper)) {
+    return !CAPTION_SPEAKER_LABEL_PATTERN.test(lower);
+  }
+  if (CAPTION_TURN_OPENER_PATTERN.test(lower)) {
+    return false;
+  }
+  const spanContinues = CAPTION_SPANS.some(
+    (span) => captionSpanDepth(upper, span) > 0 || captionSpanDepth(lower, span) < 0,
+  );
+  return spanContinues || !CAPTION_TERMINAL_PATTERN.test(upper);
+}
+
+// A half-height row is ruby or a whispered aside, not a row of the utterance.
+function isCaptionRowCandidate(cue: AnnotatedSubtitleCue): boolean {
+  const scaleY = staticAssScalePercent(cue, 'fscy');
+  return (
+    cue.source === undefined &&
+    cue.assLayout?.kind === 'positioned' &&
+    cue.effect.trim() === '' &&
+    !cue.text.includes('\n') &&
+    !hasAssTemporalOverride(cue.overrides) &&
+    (scaleY === null || scaleY > MAX_ASS_FURIGANA_SCALE_PERCENT) &&
+    JAPANESE_SCRIPT_PATTERN.test(cue.text)
+  );
+}
+
+function captionRowGroupKey(cue: AnnotatedSubtitleCue): string {
+  return [
+    cue.startTime,
+    cue.endTime,
+    cue.style,
+    cue.layer,
+    cue.name,
+    cue.assLayout?.verticalBand ?? '',
+  ].join('\0');
+}
+
+function mergeCaptionRows(rows: readonly AnnotatedSubtitleCue[]): AnnotatedSubtitleCue {
+  const [first] = rows;
+  if (!first) throw new Error('mergeCaptionRows requires at least one row');
+  const overrides = rows.flatMap((row) => row.overrides);
+  const assFurigana = [...new Set(rows.flatMap((row) => row.assFurigana ?? []))];
+  return {
+    ...first,
+    text: rows.map((row) => row.text).join('\n'),
+    rawText: rows.map((row) => row.rawText).join('\\N'),
+    overrides,
+    overrideSignature: assOverrideSignature(overrides),
+    ...(assFurigana.length === 0 ? {} : { assFurigana }),
+  };
+}
+
+/**
+ * Join simultaneous caption rows that spell one utterance into a single cue, so the
+ * overlay can wrap or flatten it like an authored `\N` line and the sidebar and mining
+ * paths see the whole sentence. Rows stack top to bottom; each row joins the cue above it
+ * only while `isCaptionRowContinuation` holds, so a second speaker starts a new cue. The
+ * whole pass is skipped unless the script reads as broadcast captions.
+ */
+function mergeAssCaptionRows(
+  cues: AnnotatedSubtitleCue[],
+  playResY: number | null,
+): AnnotatedSubtitleCue[] {
+  if (!hasBroadcastCaptionConventions(cues)) return cues;
+
+  const groups = new Map<string, AnnotatedSubtitleCue[]>();
+  for (const cue of cues) {
+    if (!isCaptionRowCandidate(cue)) continue;
+    const key = captionRowGroupKey(cue);
+    const group = groups.get(key);
+    if (group) group.push(cue);
+    else groups.set(key, [cue]);
+  }
+
+  const maxRowGap = MAX_CAPTION_ROW_GAP * assFuriganaGeometryScale(playResY);
+  const rowY = (cue: AnnotatedSubtitleCue): number =>
+    cue.assLayout?.kind === 'positioned' ? cue.assLayout.y : 0;
+  const replacements = new Map<AnnotatedSubtitleCue, AnnotatedSubtitleCue>();
+  const removed = new Set<AnnotatedSubtitleCue>();
+  for (const group of groups.values()) {
+    if (group.length < 2) continue;
+    const rows = [...group].sort((a, b) => rowY(a) - rowY(b) || a.order - b.order);
+    let run: AnnotatedSubtitleCue[] = [];
+    const flush = (): void => {
+      if (run.length < 2) return;
+      const anchor = run.reduce((lowest, row) => (row.order < lowest.order ? row : lowest));
+      replacements.set(anchor, mergeCaptionRows(run));
+      for (const row of run) {
+        if (row !== anchor) removed.add(row);
+      }
+    };
+    for (const row of rows) {
+      const previous = run.at(-1);
+      const gap = previous ? rowY(row) - rowY(previous) : 0;
+      if (
+        previous &&
+        gap > 0 &&
+        gap <= maxRowGap &&
+        previous.text !== row.text &&
+        isCaptionRowContinuation(previous.text, row.text)
+      ) {
+        run.push(row);
+        continue;
+      }
+      flush();
+      run = [row];
+    }
+    flush();
+  }
+
+  if (replacements.size === 0) return cues;
+  return cues.flatMap((cue) => {
+    if (removed.has(cue)) return [];
+    return [replacements.get(cue) ?? cue];
+  });
+}
+
+function parseAnnotatedAssEvents(content: string, placement: AssPlacementContext): ParsedAssEvents {
   const cues: AnnotatedSubtitleCue[] = [];
   const comments: AnnotatedSubtitleCue[] = [];
   const lines = content.split(/\r?\n/);
@@ -535,6 +2549,10 @@ function parseAnnotatedAssEvents(content: string): ParsedAssEvents {
 
   for (const line of lines) {
     const trimmed = line.trim();
+    // Event text can end in an authored space. Fragmented karaoke commonly uses that
+    // space to retain word boundaries when its separately positioned events are joined
+    // back into a line, so only remove indentation before slicing the event fields.
+    const eventLine = line.trimStart();
 
     if (trimmed.startsWith('[') && trimmed.endsWith(']')) {
       inEventsSection = trimmed.toLowerCase() === '[events]';
@@ -565,9 +2583,9 @@ function parseAnnotatedAssEvents(content: string): ParsedAssEvents {
       continue;
     }
 
-    const eventPrefix = trimmed.startsWith(ASS_DIALOGUE_PREFIX)
+    const eventPrefix = eventLine.startsWith(ASS_DIALOGUE_PREFIX)
       ? ASS_DIALOGUE_PREFIX
-      : trimmed.startsWith(ASS_COMMENT_PREFIX)
+      : eventLine.startsWith(ASS_COMMENT_PREFIX)
         ? ASS_COMMENT_PREFIX
         : null;
     if (!eventPrefix) {
@@ -578,7 +2596,7 @@ function parseAnnotatedAssEvents(content: string): ParsedAssEvents {
       continue;
     }
 
-    const fields = trimmed.slice(eventPrefix.length).split(',');
+    const fields = eventLine.slice(eventPrefix.length).split(',');
     if (
       fieldIndex.start >= fields.length ||
       fieldIndex.end >= fields.length ||
@@ -589,12 +2607,12 @@ function parseAnnotatedAssEvents(content: string): ParsedAssEvents {
 
     const startTime = parseAssTimestamp(fields[fieldIndex.start]!);
     const endTime = parseAssTimestamp(fields[fieldIndex.end]!);
-    if (startTime === null || endTime === null) {
+    if (startTime === null || endTime === null || endTime <= startTime) {
       continue;
     }
 
     const rawText = fields.slice(fieldIndex.text).join(',');
-    const text = sanitizeSubtitleCueText(rawText);
+    const text = sanitizeAssCueText(rawText);
     if (!text) {
       continue;
     }
@@ -602,12 +2620,13 @@ function parseAnnotatedAssEvents(content: string): ParsedAssEvents {
     const effect = readField(fields, fieldIndex.effect);
     const layer = Number(readField(fields, fieldIndex.layer));
     const overrides = collectAssOverrideCommands(rawText);
+    const style = readField(fields, fieldIndex.style);
     const cue: AnnotatedSubtitleCue = {
       startTime,
       endTime,
       text,
       rawText,
-      style: readField(fields, fieldIndex.style),
+      style,
       layer: Number.isFinite(layer) ? layer : 0,
       name: readField(fields, fieldIndex.name),
       effect,
@@ -615,6 +2634,7 @@ function parseAnnotatedAssEvents(content: string): ParsedAssEvents {
       overrides,
       overrideSignature: assOverrideSignature(overrides),
       order: eventOrder,
+      assLayout: buildAssCueLayout(overrides, eventOrder, style, placement),
     };
     eventOrder += 1;
     if (eventPrefix === ASS_COMMENT_PREFIX) {
@@ -628,7 +2648,17 @@ function parseAnnotatedAssEvents(content: string): ParsedAssEvents {
 }
 
 function parseAnnotatedAssCues(content: string): AnnotatedSubtitleCue[] {
-  return recoverCanonicalAssEvents(parseAnnotatedAssEvents(content));
+  const placement = content.includes('[')
+    ? parseAssPlacementContext(content)
+    : EMPTY_PLACEMENT_CONTEXT;
+  const events = removeAssFuriganaEvents(
+    removeAssFontTextureEvents(parseAnnotatedAssEvents(content, placement)),
+    placement.playResY,
+  );
+  return mergeAssCaptionRows(
+    recoverFragmentOnlyAssLines(recoverCanonicalAssEvents(events)),
+    placement.playResY,
+  );
 }
 
 export function parseAssCues(content: string): SubtitleCue[] {
diff --git a/src/core/services/subtitle-generation-acceleration.test.ts b/src/core/services/subtitle-generation-acceleration.test.ts
new file mode 100644
index 00000000..d14d02fa
--- /dev/null
+++ b/src/core/services/subtitle-generation-acceleration.test.ts
@@ -0,0 +1,120 @@
+import assert from 'node:assert/strict';
+import { mkdtemp, readFile, readdir, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import test from 'node:test';
+import { detectSubtitleGenerationAcceleration } from './subtitle-generation-acceleration';
+
+async function fixture(run: (directory: string) => Promise<void>) {
+  const directory = await mkdtemp(path.join(tmpdir(), 'subtitle-acceleration-test-'));
+  try {
+    await run(directory);
+  } finally {
+    await rm(directory, { recursive: true, force: true });
+  }
+}
+
+async function executable(directory: string, name: string, body: string) {
+  const file = path.join(directory, name);
+  await writeFile(file, `#!${process.execPath}\n${body}`, { mode: 0o755 });
+  return file;
+}
+
+const cudaOutput =
+  'ggml_cuda_init: found 1 CUDA devices:\nwhisper_model_load: invalid model data (bad magic)\n';
+
+test('NVIDIA and CUDA discovery work without downloading or loading a model', () =>
+  fixture(async (directory) => {
+    await executable(directory, 'nvidia-smi', 'console.log("NVIDIA Test GPU");');
+    const whisper = await executable(
+      directory,
+      'whisper-cli',
+      `const fs = require('node:fs');
+       const model = process.argv[process.argv.indexOf('-m') + 1];
+       if (fs.readFileSync(model).length !== 4) process.exit(1);
+       fs.writeFileSync(${JSON.stringify(path.join(directory, 'probe-path'))}, model);
+       process.stderr.write(${JSON.stringify(cudaOutput)}); process.exit(3);`,
+    );
+    assert.deepEqual(
+      await detectSubtitleGenerationAcceleration(
+        { kind: 'found', path: whisper },
+        { PATH: directory },
+      ),
+      { kind: 'nvidia-cuda', gpuName: 'NVIDIA Test GPU' },
+    );
+    const model = await readFile(path.join(directory, 'probe-path'), 'utf8');
+    await assert.rejects(readdir(path.dirname(model)), { code: 'ENOENT' });
+  }));
+
+test('CPU-only, Vulkan-only, hidden CUDA devices and incomplete probes fall back safely', () =>
+  fixture(async (directory) => {
+    await executable(directory, 'nvidia-smi', 'console.log("NVIDIA Test GPU");');
+    for (const output of [
+      'usage: --no-gpu disable GPU\ninvalid model data (bad magic)',
+      'ggml_vulkan: Found 1 Vulkan devices\ninvalid model data (bad magic)',
+      'ggml_cuda_init: found 0 CUDA devices\ninvalid model data (bad magic)',
+      'ggml_cuda_init: found 1 CUDA devices\nCUDA error: driver initialization failed',
+    ]) {
+      const whisper = await executable(
+        directory,
+        'whisper-cli',
+        `process.stderr.write(${JSON.stringify(output)}); process.exit(3);`,
+      );
+      assert.deepEqual(
+        await detectSubtitleGenerationAcceleration(
+          { kind: 'found', path: whisper },
+          { PATH: directory },
+        ),
+        { kind: 'unavailable' },
+      );
+    }
+  }));
+
+test('missing tools, missing NVIDIA devices and driver errors do not recommend turbo', () =>
+  fixture(async (directory) => {
+    const whisper = await executable(
+      directory,
+      'whisper-cli',
+      `process.stderr.write(${JSON.stringify(cudaOutput)}); process.exit(3);`,
+    );
+    assert.deepEqual(
+      await detectSubtitleGenerationAcceleration(
+        { kind: 'missing', message: 'Not installed' },
+        { PATH: directory },
+      ),
+      { kind: 'unavailable' },
+    );
+    for (const driver of [
+      null,
+      'process.exit(0);',
+      'console.log("NVIDIA GPU"); process.exit(1);',
+    ]) {
+      if (driver !== null) await executable(directory, 'nvidia-smi', driver);
+      assert.deepEqual(
+        await detectSubtitleGenerationAcceleration(
+          { kind: 'found', path: whisper },
+          { PATH: directory },
+        ),
+        { kind: 'unavailable' },
+      );
+    }
+  }));
+
+test('a hung Whisper probe times out even if it printed a CUDA device', () =>
+  fixture(async (directory) => {
+    await executable(directory, 'nvidia-smi', 'console.log("NVIDIA Test GPU");');
+    const whisper = await executable(
+      directory,
+      'whisper-cli',
+      `process.stderr.write(${JSON.stringify(cudaOutput)}); setInterval(() => {}, 1000);`,
+    );
+    const started = Date.now();
+    assert.deepEqual(
+      await detectSubtitleGenerationAcceleration(
+        { kind: 'found', path: whisper },
+        { PATH: directory },
+      ),
+      { kind: 'unavailable' },
+    );
+    assert.ok(Date.now() - started < 6000);
+  }));
diff --git a/src/core/services/subtitle-generation-acceleration.ts b/src/core/services/subtitle-generation-acceleration.ts
new file mode 100644
index 00000000..dc5c05ff
--- /dev/null
+++ b/src/core/services/subtitle-generation-acceleration.ts
@@ -0,0 +1,62 @@
+import { execFile } from 'node:child_process';
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import type {
+  SubtitleGenerationAcceleration,
+  SubtitleGenerationToolStatus,
+} from '../../shared/subtitle-generation';
+
+function probe(command: string, args: string[], env: NodeJS.ProcessEnv) {
+  return new Promise<{ code: number; stdout: string; stderr: string } | null>((resolve) => {
+    execFile(
+      command,
+      args,
+      { env, timeout: 3000, killSignal: 'SIGKILL', maxBuffer: 64 * 1024, windowsHide: true },
+      (error, stdout, stderr) => {
+        const code = error?.code ?? 0;
+        if (typeof code !== 'number' || error?.killed || error?.signal) {
+          resolve(null);
+          return;
+        }
+        resolve({ code, stdout, stderr });
+      },
+    );
+  });
+}
+
+/** Require both a working NVIDIA driver and CUDA device discovery in the selected Whisper binary. */
+export async function detectSubtitleGenerationAcceleration(
+  whisper: SubtitleGenerationToolStatus,
+  env: NodeJS.ProcessEnv = process.env,
+): Promise<SubtitleGenerationAcceleration> {
+  const unavailable: SubtitleGenerationAcceleration = { kind: 'unavailable' };
+  if (whisper.kind === 'missing') return unavailable;
+  let directory: string | undefined;
+  try {
+    const nvidia = await probe('nvidia-smi', ['--query-gpu=name', '--format=csv,noheader'], env);
+    const gpuName = nvidia?.stdout.trim().split(/\r?\n/)[0]?.trim();
+    if (nvidia?.code !== 0 || !gpuName) return unavailable;
+
+    directory = await mkdtemp(path.join(tmpdir(), 'subminer-cuda-check-'));
+    const model = path.join(directory, 'probe.bin');
+    await writeFile(model, Buffer.alloc(4));
+    // whisper.cpp discovers backends before checking model magic. This deliberately invalid
+    // local file stops before allocating a model or decoding audio, even on a fresh install.
+    const result = await probe(whisper.path, ['-m', model, '-f', model], env);
+    if (
+      result &&
+      result.code !== 0 &&
+      /ggml_cuda_init:\s+found\s+[1-9]\d*\s+CUDA devices?\b/i.test(result.stderr) &&
+      /invalid model data \(bad magic\)/i.test(result.stderr)
+    ) {
+      return { kind: 'nvidia-cuda', gpuName };
+    }
+    return unavailable;
+  } catch {
+    // Detection is advisory; unsupported builds and driver failures must not block generation.
+    return unavailable;
+  } finally {
+    if (directory) await rm(directory, { recursive: true, force: true }).catch(() => {});
+  }
+}
diff --git a/src/core/services/subtitle-generation-chunks.test.ts b/src/core/services/subtitle-generation-chunks.test.ts
new file mode 100644
index 00000000..4ea1ba01
--- /dev/null
+++ b/src/core/services/subtitle-generation-chunks.test.ts
@@ -0,0 +1,125 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { appendSpeechChunkCues, splitSpeechPassages } from './subtitle-generation-chunks';
+
+test('reference starts guide long cuts ahead of VAD without dropping unreferenced audio', () => {
+  const chunks = splitSpeechPassages(
+    [{ startSeconds: 0, endSeconds: 70 }],
+    [18],
+    [19],
+    [22, 43, 200],
+  );
+  assert.deepEqual(chunks, [
+    { startSeconds: 0, endSeconds: 22.25 },
+    { startSeconds: 21.75, endSeconds: 43.25 },
+    { startSeconds: 42.75, endSeconds: 63.25 },
+    { startSeconds: 62.75, endSeconds: 70 },
+  ]);
+  assert.deepEqual(splitSpeechPassages([{ startSeconds: 0, endSeconds: 25 }], [], [], [10, 20]), [
+    { startSeconds: 0, endSeconds: 25 },
+  ]);
+});
+
+test('long coverage cuts at nearby speech starts instead of leaving a quiet lead-in', () => {
+  const chunks = splitSpeechPassages(
+    [{ startSeconds: 544.418, endSeconds: 581.581 }],
+    [563.928],
+    [555.07, 567.23, 579.91],
+  );
+  assert.deepEqual(chunks, [
+    { startSeconds: 544.418, endSeconds: 567.48 },
+    { startSeconds: 566.98, endSeconds: 581.581 },
+  ]);
+});
+
+test('short audible passages stay intact even with several detected speech starts', () => {
+  assert.deepEqual(
+    splitSpeechPassages(
+      [{ startSeconds: 876.897, endSeconds: 897.812 }],
+      [],
+      [876.9, 881.15, 893.95, 897.99],
+    ),
+    [{ startSeconds: 876.897, endSeconds: 897.812 }],
+  );
+});
+
+test('speech anchors outside retained coverage cannot extend a chunk across a silent gap', () => {
+  const chunks = splitSpeechPassages(
+    [{ startSeconds: 100, endSeconds: 142 }],
+    [118],
+    [90, 142, 144],
+  );
+  assert.deepEqual(chunks, [
+    { startSeconds: 100, endSeconds: 118.25 },
+    { startSeconds: 117.75, endSeconds: 138.25 },
+    { startSeconds: 137.75, endSeconds: 142 },
+  ]);
+});
+
+test('long speech splits near a pause with context on both sides and no lost audio', () => {
+  assert.deepEqual(splitSpeechPassages([{ startSeconds: 100, endSeconds: 145 }], [105, 118, 137]), [
+    { startSeconds: 100, endSeconds: 118.25 },
+    { startSeconds: 117.75, endSeconds: 137.25 },
+    { startSeconds: 136.75, endSeconds: 145 },
+  ]);
+});
+
+test('uninterrupted speech retains overlapping context without crossing omitted gaps', () => {
+  const chunks = splitSpeechPassages([
+    { startSeconds: 0, endSeconds: 60 },
+    { startSeconds: 100, endSeconds: 100.15 },
+  ]);
+  assert.deepEqual(chunks, [
+    { startSeconds: 0, endSeconds: 20.25 },
+    { startSeconds: 19.75, endSeconds: 40.25 },
+    { startSeconds: 39.75, endSeconds: 60 },
+    { startSeconds: 100, endSeconds: 100.15 },
+  ]);
+});
+
+test('speech fitting one Whisper window stays intact instead of cutting a sentence at 20 seconds', () => {
+  const passage = { startSeconds: 251.71, endSeconds: 275.01 };
+  assert.deepEqual(splitSpeechPassages([passage], [271.327]), [passage]);
+});
+
+test('chunk stitching ignores punctuation differences without merging separate repetitions', () => {
+  const cues = [{ startTime: 19.7, endTime: 21.2, text: 'ありがとう' }];
+  appendSpeechChunkCues(cues, [
+    { startTime: 19.8, endTime: 21.3, text: 'ありがとう。' },
+    { startTime: 22, endTime: 23, text: 'ありがとう！' },
+  ]);
+  assert.deepEqual(cues, [
+    { startTime: 19.7, endTime: 21.3, text: 'ありがとう' },
+    { startTime: 22, endTime: 23, text: 'ありがとう！' },
+  ]);
+});
+
+test('chunk stitching removes matching overlap cues but retains repeated dialogue', () => {
+  const cues = [{ startTime: 19.7, endTime: 20.2, text: 'はい' }];
+  appendSpeechChunkCues(cues, [
+    { startTime: 19.8, endTime: 20.3, text: 'はい' },
+    { startTime: 21, endTime: 21.5, text: 'はい' },
+    { startTime: 21.4, endTime: 22, text: 'はい' },
+  ]);
+  assert.deepEqual(cues, [
+    { startTime: 19.7, endTime: 20.3, text: 'はい' },
+    { startTime: 21, endTime: 21.5, text: 'はい' },
+    { startTime: 21.4, endTime: 22, text: 'はい' },
+  ]);
+});
+
+test('chunk stitching matches repeated text to the greatest overlap without leaving a duplicate', () => {
+  const cues = [
+    { startTime: 10, endTime: 14, text: 'はい' },
+    { startTime: 13, endTime: 20, text: 'はい' },
+  ];
+  appendSpeechChunkCues(cues, [
+    { startTime: 12, endTime: 21, text: 'はい' },
+    { startTime: 22, endTime: 23, text: 'はい' },
+  ]);
+  assert.deepEqual(cues, [
+    { startTime: 10, endTime: 14, text: 'はい' },
+    { startTime: 12, endTime: 21, text: 'はい' },
+    { startTime: 22, endTime: 23, text: 'はい' },
+  ]);
+});
diff --git a/src/core/services/subtitle-generation-chunks.ts b/src/core/services/subtitle-generation-chunks.ts
new file mode 100644
index 00000000..170ac9c9
--- /dev/null
+++ b/src/core/services/subtitle-generation-chunks.ts
@@ -0,0 +1,90 @@
+import type { SubtitleCue } from './subtitle-cue-parser';
+import { SPEECH_PASSAGE_SECONDS, type SpeechPassage } from './subtitle-generation-speech';
+
+const CHUNK_CONTEXT_SECONDS = 0.25;
+const WHISPER_WINDOW_SECONDS = 30;
+const PAUSE_SEARCH_SECONDS = 5;
+
+// Prefer subtitle timing hints, then detected speech starts and quiet pauses.
+export function splitSpeechPassages(
+  passages: readonly SpeechPassage[],
+  pauses: readonly number[] = [],
+  speechStarts: readonly number[] = [],
+  referenceStarts: readonly number[] = [],
+): SpeechPassage[] {
+  return passages.flatMap((passage) => {
+    if (passage.endSeconds - passage.startSeconds <= WHISPER_WINDOW_SECONDS)
+      return [{ ...passage }];
+    const chunks: SpeechPassage[] = [];
+    let boundary = passage.startSeconds;
+    while (boundary < passage.endSeconds) {
+      const target = boundary + SPEECH_PASSAGE_SECONDS;
+      let end = Math.min(target, passage.endSeconds);
+      if (target < passage.endSeconds) {
+        // Starting in a long quiet lead-in can make Whisper place the next line
+        // several seconds early. A nearby VAD start gives the next chunk an anchor.
+        const nearestStart = (starts: readonly number[]): number | undefined => {
+          let nearest: number | undefined;
+          for (const time of starts) {
+            if (
+              time >= target - PAUSE_SEARCH_SECONDS &&
+              time <= target + PAUSE_SEARCH_SECONDS &&
+              time < passage.endSeconds &&
+              (nearest === undefined || Math.abs(time - target) < Math.abs(nearest - target))
+            )
+              nearest = time;
+          }
+          return nearest;
+        };
+        let latestPause: number | undefined;
+        for (const time of pauses) {
+          if (
+            time >= target - PAUSE_SEARCH_SECONDS &&
+            time <= target &&
+            (latestPause === undefined || time > latestPause)
+          )
+            latestPause = time;
+        }
+        end = nearestStart(referenceStarts) ?? nearestStart(speechStarts) ?? latestPause ?? end;
+      }
+      chunks.push({
+        startSeconds: Math.max(passage.startSeconds, boundary - CHUNK_CONTEXT_SECONDS),
+        endSeconds: Math.min(passage.endSeconds, end + CHUNK_CONTEXT_SECONDS),
+      });
+      boundary = end;
+    }
+    return chunks;
+  });
+}
+
+// Deduplicate only matching text substantially overlapping cues from earlier chunks.
+// Repeated words within the current chunk or at separate times remain separate.
+export function appendSpeechChunkCues(cues: SubtitleCue[], incoming: readonly SubtitleCue[]): void {
+  const previousCount = cues.length;
+  const matched = new Set<SubtitleCue>();
+  for (const cue of incoming) {
+    const text = cue.text.replace(/[\s\p{P}]+/gu, '');
+    let duplicate: SubtitleCue | undefined;
+    let greatestOverlap = 0;
+    for (const [index, previous] of cues.entries()) {
+      if (index >= previousCount) break;
+      if (!text || matched.has(previous) || previous.text.replace(/[\s\p{P}]+/gu, '') !== text)
+        continue;
+      const overlap =
+        Math.min(previous.endTime, cue.endTime) - Math.max(previous.startTime, cue.startTime);
+      const shorterDuration = Math.min(
+        previous.endTime - previous.startTime,
+        cue.endTime - cue.startTime,
+      );
+      if (overlap > greatestOverlap && overlap >= shorterDuration / 2) {
+        duplicate = previous;
+        greatestOverlap = overlap;
+      }
+    }
+    if (duplicate) {
+      duplicate.startTime = Math.min(duplicate.startTime, cue.startTime);
+      duplicate.endTime = Math.max(duplicate.endTime, cue.endTime);
+      matched.add(duplicate);
+    } else cues.push({ ...cue });
+  }
+}
diff --git a/src/core/services/subtitle-generation-coverage.test.ts b/src/core/services/subtitle-generation-coverage.test.ts
new file mode 100644
index 00000000..db95f265
--- /dev/null
+++ b/src/core/services/subtitle-generation-coverage.test.ts
@@ -0,0 +1,73 @@
+import assert from 'node:assert/strict';
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import test from 'node:test';
+import { findAudiblePassages, mergeSpeechPassages } from './subtitle-generation-coverage';
+
+async function analyze(lines: string[], progress = 'out_time_us=20000000\n') {
+  const directory = await mkdtemp(path.join(tmpdir(), 'subtitle-coverage-test-'));
+  try {
+    const ffmpegPath = path.join(directory, 'ffmpeg');
+    await writeFile(
+      ffmpegPath,
+      `#!${process.execPath}
+process.stderr.write(${JSON.stringify(lines.join('\n') + '\n')});
+process.stdout.write(${JSON.stringify(progress)});
+`,
+      { mode: 0o755 },
+    );
+    return await findAudiblePassages({ ffmpegPath, wavPath: 'audio.wav' });
+  } finally {
+    await rm(directory, { recursive: true, force: true });
+  }
+}
+
+test('audible coverage retains the full timeline when there is no confident silence', async () => {
+  assert.deepEqual(await analyze([]), [{ startSeconds: 0, endSeconds: 20 }]);
+});
+
+test('audible coverage omits silence while padding nearby audio without exceeding the timeline', async () => {
+  assert.deepEqual(
+    await analyze([
+      '[silencedetect] silence_start: 0',
+      '[silencedetect] silence_end: 2 | silence_duration: 2',
+      '[silencedetect] silence_start: 8',
+      '[silencedetect] silence_end: 12 | silence_duration: 4',
+      '[silencedetect] silence_start: 18',
+    ]),
+    [
+      { startSeconds: 1.65, endSeconds: 8.35 },
+      { startSeconds: 11.65, endSeconds: 18.35 },
+    ],
+  );
+  assert.deepEqual(await analyze(['[silencedetect] silence_end: 10.5 | silence_duration: 0.5']), [
+    { startSeconds: 0, endSeconds: 20 },
+  ]);
+});
+
+test('entirely silent audio has no audible passages', async () => {
+  assert.deepEqual(await analyze(['[silencedetect] silence_start: 0']), []);
+  assert.deepEqual(await analyze(['[silencedetect] silence_end: 20 | silence_duration: 20']), []);
+});
+
+test('missing analysis duration fails instead of silently dropping audio', async () => {
+  await assert.rejects(analyze([], ''), /valid duration/);
+});
+
+test('merging coverage preserves quiet VAD speech and does not mutate detector results', () => {
+  const speech = [{ startSeconds: 10, endSeconds: 11 }];
+  assert.deepEqual(
+    mergeSpeechPassages([
+      ...speech,
+      { startSeconds: 0, endSeconds: 5 },
+      { startSeconds: 4, endSeconds: 8 },
+      { startSeconds: 11, endSeconds: 12 },
+    ]),
+    [
+      { startSeconds: 0, endSeconds: 8 },
+      { startSeconds: 10, endSeconds: 12 },
+    ],
+  );
+  assert.deepEqual(speech, [{ startSeconds: 10, endSeconds: 11 }]);
+});
diff --git a/src/core/services/subtitle-generation-coverage.ts b/src/core/services/subtitle-generation-coverage.ts
new file mode 100644
index 00000000..92e2cf26
--- /dev/null
+++ b/src/core/services/subtitle-generation-coverage.ts
@@ -0,0 +1,78 @@
+import { runSubtitleGenerationProcess } from './subtitle-generation-process';
+import type { SpeechPassage } from './subtitle-generation-speech';
+
+const AUDIO_PADDING_SECONDS = 0.35;
+
+export function mergeSpeechPassages(passages: readonly SpeechPassage[]): SpeechPassage[] {
+  const merged: SpeechPassage[] = [];
+  for (const passage of [...passages].sort((a, b) => a.startSeconds - b.startSeconds)) {
+    const previous = merged.at(-1);
+    if (previous && passage.startSeconds <= previous.endSeconds)
+      previous.endSeconds = Math.max(previous.endSeconds, passage.endSeconds);
+    else merged.push({ ...passage });
+  }
+  return merged;
+}
+
+// VAD rejection is not proof of silence. Preserve audible gaps for Whisper to evaluate.
+export async function findAudiblePassages(input: {
+  ffmpegPath: string;
+  wavPath: string;
+  signal?: AbortSignal;
+}): Promise<SpeechPassage[]> {
+  const silences: SpeechPassage[] = [];
+  let duration = 0;
+  let trailingSilence: number | undefined;
+  await runSubtitleGenerationProcess({
+    command: input.ffmpegPath,
+    args: [
+      '-nostdin',
+      '-hide_banner',
+      '-nostats',
+      '-i',
+      input.wavPath,
+      '-af',
+      'silencedetect=noise=-50dB:d=0.5',
+      '-progress',
+      'pipe:1',
+      '-f',
+      'null',
+      '-',
+    ],
+    signal: input.signal,
+    onLine: (line) => {
+      const progress = /^out_time_us=(\d+)$/.exec(line);
+      if (progress) duration = Math.max(duration, Number(progress[1]) / 1_000_000);
+      const start = /silence_start: (\S+)/.exec(line);
+      if (start && Number.isFinite(Number(start[1]))) trailingSilence = Number(start[1]);
+      const end = /silence_end: (\S+) \| silence_duration: (\S+)/.exec(line);
+      if (!end) return;
+      const endSeconds = Number(end[1]);
+      const length = Number(end[2]);
+      if (Number.isFinite(endSeconds) && Number.isFinite(length) && length > 0) {
+        silences.push({ startSeconds: Math.max(0, endSeconds - length), endSeconds });
+        trailingSilence = undefined;
+      }
+    },
+  });
+  if (!Number.isFinite(duration) || duration <= 0)
+    throw new Error('Audio analysis did not report a valid duration.');
+  if (trailingSilence !== undefined)
+    silences.push({ startSeconds: trailingSilence, endSeconds: duration });
+
+  const audible: SpeechPassage[] = [];
+  let cursor = 0;
+  for (const silence of mergeSpeechPassages(silences)) {
+    if (cursor >= duration) break;
+    if (silence.startSeconds > cursor)
+      audible.push({ startSeconds: cursor, endSeconds: Math.min(duration, silence.startSeconds) });
+    cursor = Math.max(cursor, silence.endSeconds);
+  }
+  if (cursor < duration) audible.push({ startSeconds: cursor, endSeconds: duration });
+  return mergeSpeechPassages(
+    audible.map((passage) => ({
+      startSeconds: Math.max(0, passage.startSeconds - AUDIO_PADDING_SECONDS),
+      endSeconds: Math.min(duration, passage.endSeconds + AUDIO_PADDING_SECONDS),
+    })),
+  );
+}
diff --git a/src/core/services/subtitle-generation-dialogue.ts b/src/core/services/subtitle-generation-dialogue.ts
new file mode 100644
index 00000000..d6782516
--- /dev/null
+++ b/src/core/services/subtitle-generation-dialogue.ts
@@ -0,0 +1,157 @@
+import { access, readFile, rm } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import path from 'node:path';
+import type {
+  SubtitleGenerationConfig,
+  SubtitleGenerationProgress,
+} from '../../shared/subtitle-generation';
+import { expandSubtitleGenerationPath } from './subtitle-generation-files';
+import { runSubtitleGenerationProcess } from './subtitle-generation-process';
+import type { SubtitleGenerationToolPaths } from './subtitle-generation-tools';
+import { formatTimestamp } from './subtitle-generation-srt';
+import {
+  parseSpeechPassages,
+  speechPassageCues,
+  SPEECH_PASSAGE_SECONDS,
+  type SpeechPassage,
+} from './subtitle-generation-speech';
+import type { SubtitleCue } from './subtitle-cue-parser';
+import { appendSpeechChunkCues, splitSpeechPassages } from './subtitle-generation-chunks';
+import { findSpeechPauses } from './subtitle-generation-pauses';
+import { findAudiblePassages, mergeSpeechPassages } from './subtitle-generation-coverage';
+
+export async function transcribeSubtitleDialogue(input: {
+  config: SubtitleGenerationConfig;
+  tools: SubtitleGenerationToolPaths;
+  referenceStarts?: readonly number[];
+  modelPath: string;
+  wavPath: string;
+  directory: string;
+  onProgress?: (progress: SubtitleGenerationProgress) => void;
+  signal?: AbortSignal;
+}): Promise<string> {
+  let speech: SpeechPassage[] = [];
+  if (input.tools.vad !== null) {
+    const vadModelPath = expandSubtitleGenerationPath(input.config.vadModelPath);
+    await access(vadModelPath, constants.R_OK);
+    input.onProgress?.({ stage: 'transcribe', percent: 0, message: 'Finding spoken dialogue...' });
+    const segmentLines: string[] = [];
+    await runSubtitleGenerationProcess({
+      command: input.tools.vad,
+      args: [
+        '-f',
+        input.wavPath,
+        '-vm',
+        vadModelPath,
+        '-t',
+        String(input.config.threads),
+        '-vt',
+        '0.3',
+        '--vad-min-speech-duration-ms',
+        '100',
+        '--vad-min-silence-duration-ms',
+        '500',
+        '-vp',
+        '350',
+        '-vmsd',
+        String(SPEECH_PASSAGE_SECONDS),
+        '-np',
+      ],
+      signal: input.signal,
+      // Capture structured result lines separately from the bounded process log.
+      onLine: (line) => {
+        if (line.startsWith('Detected ') || line.startsWith('Speech segment '))
+          segmentLines.push(line);
+      },
+    });
+    speech = parseSpeechPassages(segmentLines.join('\n'));
+  }
+  input.onProgress?.({ stage: 'transcribe', percent: 0, message: 'Checking audio coverage...' });
+  const audible = await findAudiblePassages({
+    ffmpegPath: input.tools.ffmpeg,
+    wavPath: input.wavPath,
+    signal: input.signal,
+  });
+  const detected = mergeSpeechPassages([...speech, ...audible]);
+  if (detected.length === 0) throw new Error('No spoken dialogue detected.');
+  const pauses = detected.some(
+    (passage) => passage.endSeconds - passage.startSeconds > SPEECH_PASSAGE_SECONDS,
+  )
+    ? await findSpeechPauses({
+        ffmpegPath: input.tools.ffmpeg,
+        wavPath: input.wavPath,
+        signal: input.signal,
+      })
+    : [];
+  const passages = splitSpeechPassages(
+    detected,
+    pauses,
+    speech.map((passage) => passage.startSeconds),
+    input.referenceStarts,
+  );
+  const cues: SubtitleCue[] = [];
+  for (const [index, passage] of passages.entries()) {
+    const base = path.join(input.directory, `speech-${index}`);
+    input.onProgress?.({
+      stage: 'transcribe',
+      percent: Math.floor((index / passages.length) * 100),
+      message: `Transcribing dialogue passage ${index + 1} of ${passages.length}...`,
+    });
+    await runSubtitleGenerationProcess({
+      command: input.tools.ffmpeg,
+      args: [
+        '-nostdin',
+        '-hide_banner',
+        '-loglevel',
+        'error',
+        '-ss',
+        String(passage.startSeconds),
+        '-i',
+        input.wavPath,
+        '-t',
+        String(passage.endSeconds - passage.startSeconds),
+        '-ac',
+        '1',
+        '-ar',
+        '16000',
+        '-c:a',
+        'pcm_s16le',
+        `${base}.wav`,
+      ],
+      signal: input.signal,
+    });
+    // -mc 0 limits text context, but does not isolate decoder state across input files.
+    // A fresh process prevents earlier passages from corrupting later transcriptions.
+    await runSubtitleGenerationProcess({
+      command: input.tools.whisper,
+      args: [
+        '-m',
+        input.modelPath,
+        '-l',
+        'ja',
+        '-t',
+        String(input.config.threads),
+        '-mc',
+        '0',
+        '-sns',
+        '-osrt',
+        '-f',
+        `${base}.wav`,
+        '-of',
+        base,
+      ],
+      signal: input.signal,
+    });
+    input.signal?.throwIfAborted();
+    appendSpeechChunkCues(cues, speechPassageCues(await readFile(`${base}.srt`, 'utf8'), passage));
+    await rm(`${base}.wav`);
+  }
+  if (cues.length === 0) throw new Error('Whisper recognized no dialogue in the detected speech.');
+  return cues
+    .sort((a, b) => a.startTime - b.startTime || a.endTime - b.endTime)
+    .map(
+      (cue, index) =>
+        `${index + 1}\n${formatTimestamp(cue.startTime * 1000)} --> ${formatTimestamp(cue.endTime * 1000)}\n${cue.text}\n`,
+    )
+    .join('\n');
+}
diff --git a/src/core/services/subtitle-generation-download.test.ts b/src/core/services/subtitle-generation-download.test.ts
new file mode 100644
index 00000000..f8c9498b
--- /dev/null
+++ b/src/core/services/subtitle-generation-download.test.ts
@@ -0,0 +1,75 @@
+import assert from 'node:assert/strict';
+import { createHash } from 'node:crypto';
+import { mkdtemp, readFile, readdir, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import test from 'node:test';
+import { downloadSubtitleGenerationArtifact } from './subtitle-generation-download';
+import {
+  downloadSubtitleGenerationVadModel,
+  resolveSubtitleGenerationVadModel,
+} from './subtitle-generation-vad-model';
+import { DEFAULT_SUBTITLE_GENERATION_CONFIG } from '../../shared/subtitle-generation';
+
+test('verified model publication preserves existing files and cleans up failed or cancelled downloads', async () => {
+  const directory = await mkdtemp(path.join(tmpdir(), 'subtitle-model-download-'));
+  const originalFetch = globalThis.fetch;
+  const bytes = new TextEncoder().encode('fixture model');
+  const input = {
+    url: 'https://example.test/model',
+    size: bytes.length,
+    sha256: createHash('sha256').update(bytes).digest('hex'),
+    destination: path.join(directory, 'model.bin'),
+    label: 'test model',
+  };
+  try {
+    globalThis.fetch = Object.assign(async () => new Response(bytes), originalFetch);
+    await downloadSubtitleGenerationArtifact(input);
+    assert.equal(await readFile(input.destination, 'utf8'), 'fixture model');
+    await assert.rejects(downloadSubtitleGenerationArtifact(input), /EEXIST/);
+    await assert.rejects(
+      downloadSubtitleGenerationArtifact({
+        ...input,
+        destination: path.join(directory, 'bad.bin'),
+        sha256: 'wrong',
+      }),
+      /integrity/,
+    );
+    const controller = new AbortController();
+    await assert.rejects(
+      downloadSubtitleGenerationArtifact({
+        ...input,
+        destination: path.join(directory, 'cancelled.bin'),
+        signal: controller.signal,
+        onProgress: ({ percent }) => {
+          if (percent === 99) controller.abort();
+        },
+      }),
+    );
+    assert.deepEqual(await readdir(directory), ['model.bin']);
+  } finally {
+    globalThis.fetch = originalFetch;
+    await rm(directory, { recursive: true, force: true });
+  }
+});
+
+test('VAD setup recognizes existing paths and never replaces an invalid external model', async () => {
+  const directory = await mkdtemp(path.join(tmpdir(), 'subtitle-vad-model-'));
+  try {
+    const config = { ...DEFAULT_SUBTITLE_GENERATION_CONFIG };
+    assert.equal((await resolveSubtitleGenerationVadModel(config, directory)).kind, 'missing');
+    config.vadModelPath = path.join(directory, 'external.bin');
+    await assert.rejects(
+      downloadSubtitleGenerationVadModel({ config, modelDirectory: directory }),
+      /Cannot read/,
+    );
+    await writeFile(config.vadModelPath, 'external model');
+    assert.equal((await resolveSubtitleGenerationVadModel(config, directory)).kind, 'external');
+    assert.equal(
+      await downloadSubtitleGenerationVadModel({ config, modelDirectory: directory }),
+      config.vadModelPath,
+    );
+  } finally {
+    await rm(directory, { recursive: true, force: true });
+  }
+});
diff --git a/src/core/services/subtitle-generation-download.ts b/src/core/services/subtitle-generation-download.ts
new file mode 100644
index 00000000..a3e041fa
--- /dev/null
+++ b/src/core/services/subtitle-generation-download.ts
@@ -0,0 +1,67 @@
+import { createHash } from 'node:crypto';
+import { mkdir, mkdtemp, open, rm } from 'node:fs/promises';
+import path from 'node:path';
+import { publishSubtitleGenerationFile } from './subtitle-generation-files';
+import type { SubtitleGenerationProgress } from '../../shared/subtitle-generation';
+
+export async function downloadSubtitleGenerationArtifact(input: {
+  url: string;
+  size: number;
+  sha256: string;
+  destination: string;
+  label: string;
+  onProgress?: (progress: SubtitleGenerationProgress) => void;
+  signal?: AbortSignal;
+}): Promise<string> {
+  input.signal?.throwIfAborted();
+  await mkdir(path.dirname(input.destination), { recursive: true });
+  const temporaryDirectory = await mkdtemp(
+    path.join(path.dirname(input.destination), '.download-'),
+  );
+  const temporaryPath = path.join(temporaryDirectory, 'model.bin');
+  input.onProgress?.({ stage: 'download', percent: 0, message: `Downloading ${input.label}...` });
+  try {
+    const response = await fetch(input.url, { signal: input.signal });
+    if (!response.ok || !response.body) {
+      throw new Error(`Model download failed: HTTP ${response.status}`);
+    }
+    const file = await open(temporaryPath, 'wx');
+    const reader = response.body.getReader();
+    const digest = createHash('sha256');
+    let received = 0;
+    let previousPercent = -1;
+    try {
+      while (true) {
+        input.signal?.throwIfAborted();
+        const { done, value } = await reader.read();
+        if (done) break;
+        received += value.byteLength;
+        if (received > input.size) throw new Error('Downloaded model exceeds expected size.');
+        digest.update(value);
+        await file.writeFile(value);
+        const percent = Math.min(99, Math.floor((received / input.size) * 100));
+        if (percent !== previousPercent) {
+          previousPercent = percent;
+          input.onProgress?.({
+            stage: 'download',
+            percent,
+            message: `Downloading ${input.label}...`,
+          });
+        }
+      }
+      if (received !== input.size || digest.digest('hex') !== input.sha256) {
+        throw new Error('Downloaded model failed integrity verification. Try downloading again.');
+      }
+      await file.sync();
+    } finally {
+      await reader.cancel().catch(() => undefined);
+      await file.close();
+    }
+    input.signal?.throwIfAborted();
+    await publishSubtitleGenerationFile(temporaryPath, input.destination);
+    input.onProgress?.({ stage: 'download', percent: 100, message: `${input.label} is ready.` });
+    return input.destination;
+  } finally {
+    await rm(temporaryDirectory, { recursive: true, force: true });
+  }
+}
diff --git a/src/core/services/subtitle-generation-files.ts b/src/core/services/subtitle-generation-files.ts
new file mode 100644
index 00000000..0073742c
--- /dev/null
+++ b/src/core/services/subtitle-generation-files.ts
@@ -0,0 +1,32 @@
+import { constants } from 'node:fs';
+import { copyFile, link } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import path from 'node:path';
+
+export function expandSubtitleGenerationPath(value: string): string {
+  if (value === '~') return homedir();
+  if (value.startsWith('~/') || value.startsWith('~\\'))
+    return path.join(homedir(), value.slice(2));
+  return value;
+}
+
+// Prefer atomic publication. Filesystems without hard links still get exclusive creation.
+export async function publishSubtitleGenerationFile(
+  source: string,
+  destination: string,
+): Promise<void> {
+  try {
+    await link(source, destination);
+  } catch (error) {
+    if (
+      !(error instanceof Error) ||
+      !('code' in error) ||
+      (error.code !== 'ENOTSUP' &&
+        error.code !== 'EOPNOTSUPP' &&
+        error.code !== 'EPERM' &&
+        error.code !== 'EXDEV')
+    )
+      throw error;
+    await copyFile(source, destination, constants.COPYFILE_EXCL);
+  }
+}
diff --git a/src/core/services/subtitle-generation-models.ts b/src/core/services/subtitle-generation-models.ts
new file mode 100644
index 00000000..9cc10b5e
--- /dev/null
+++ b/src/core/services/subtitle-generation-models.ts
@@ -0,0 +1,90 @@
+import { access, open, stat } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import path from 'node:path';
+import { getSubtitleGenerationModel } from '../../shared/subtitle-generation-model-catalog';
+import { expandSubtitleGenerationPath } from './subtitle-generation-files';
+import { downloadSubtitleGenerationArtifact } from './subtitle-generation-download';
+import type {
+  SubtitleGenerationConfig,
+  SubtitleGenerationModelStatus,
+  SubtitleGenerationProgress,
+} from '../../shared/subtitle-generation';
+
+export function isMissingFile(error: unknown): boolean {
+  return error instanceof Error && 'code' in error && error.code === 'ENOENT';
+}
+
+async function modelCompatibilityError(modelPath: string): Promise<string | undefined> {
+  const file = await open(modelPath, 'r');
+  try {
+    // whisper_model_load reads GGML magic, then n_vocab. is_multilingual uses n_vocab >= 51865.
+    const header = Buffer.alloc(8);
+    const { bytesRead } = await file.read(header, 0, header.length, 0);
+    if (
+      bytesRead !== header.length ||
+      header.readUInt32LE(0) !== 0x67676d6c ||
+      header.readInt32LE(4) <= 0
+    ) {
+      return 'Unsupported model format. Choose a whisper.cpp GGML .bin model.';
+    }
+    if (header.readInt32LE(4) < 51865) {
+      return 'This Whisper model is English-only. Japanese subtitle generation requires a multilingual model.';
+    }
+    return undefined;
+  } finally {
+    await file.close();
+  }
+}
+
+export async function resolveSubtitleGenerationModel(
+  config: SubtitleGenerationConfig,
+  modelDirectory: string,
+): Promise<SubtitleGenerationModelStatus> {
+  const external = config.modelPath.trim();
+  const modelPath = external
+    ? path.resolve(expandSubtitleGenerationPath(external))
+    : path.resolve(modelDirectory, `ggml-${config.managedModel}.bin`);
+  try {
+    const info = await stat(modelPath);
+    if (!info.isFile() || info.size === 0) {
+      return { kind: 'invalid', path: modelPath, message: 'Model must be a nonempty file.' };
+    }
+    await access(modelPath, constants.R_OK);
+    if (!external && info.size !== getSubtitleGenerationModel(config.managedModel).size) {
+      return { kind: 'invalid', path: modelPath, message: 'Managed model has an unexpected size.' };
+    }
+    const compatibilityError = await modelCompatibilityError(modelPath);
+    if (compatibilityError)
+      return { kind: 'invalid', path: modelPath, message: compatibilityError };
+    return { kind: external ? 'external' : 'managed', path: modelPath };
+  } catch (error) {
+    if (!external && isMissingFile(error)) return { kind: 'missing', path: modelPath };
+    return {
+      kind: 'invalid',
+      path: modelPath,
+      message: `Cannot read model: ${error instanceof Error ? error.message : String(error)}`,
+    };
+  }
+}
+
+export async function downloadSubtitleGenerationModel(input: {
+  config: SubtitleGenerationConfig;
+  modelDirectory: string;
+  onProgress?: (progress: SubtitleGenerationProgress) => void;
+  signal?: AbortSignal;
+}): Promise<string> {
+  input.signal?.throwIfAborted();
+  const current = await resolveSubtitleGenerationModel(input.config, input.modelDirectory);
+  if (current.kind === 'external' || current.kind === 'managed') return current.path;
+  if (current.kind === 'invalid') throw new Error(current.message);
+  const model = getSubtitleGenerationModel(input.config.managedModel);
+  return downloadSubtitleGenerationArtifact({
+    url: `https://huggingface.co/ggerganov/whisper.cpp/resolve/5359861c739e955e79d9a303bcbc70fb988958b1/ggml-${input.config.managedModel}.bin`,
+    size: model.size,
+    sha256: model.sha256,
+    destination: current.path,
+    label: 'Whisper model',
+    onProgress: input.onProgress,
+    signal: input.signal,
+  });
+}
diff --git a/src/core/services/subtitle-generation-pauses.ts b/src/core/services/subtitle-generation-pauses.ts
new file mode 100644
index 00000000..f0fdbda1
--- /dev/null
+++ b/src/core/services/subtitle-generation-pauses.ts
@@ -0,0 +1,35 @@
+import { runSubtitleGenerationProcess } from './subtitle-generation-process';
+
+// Each completed silencedetect line contains both the end and duration of a quiet interval.
+export async function findSpeechPauses(input: {
+  ffmpegPath: string;
+  wavPath: string;
+  signal?: AbortSignal;
+}): Promise<number[]> {
+  const pauses: number[] = [];
+  await runSubtitleGenerationProcess({
+    command: input.ffmpegPath,
+    args: [
+      '-nostdin',
+      '-hide_banner',
+      '-nostats',
+      '-i',
+      input.wavPath,
+      '-af',
+      'silencedetect=noise=-35dB:d=0.12',
+      '-f',
+      'null',
+      '-',
+    ],
+    signal: input.signal,
+    onLine: (line) => {
+      const match = /silence_end: (\S+) \| silence_duration: (\S+)/.exec(line);
+      if (!match) return;
+      const end = Number(match[1]);
+      const duration = Number(match[2]);
+      if (Number.isFinite(end) && Number.isFinite(duration) && duration > 0 && end >= duration)
+        pauses.push(end - duration / 2);
+    },
+  });
+  return pauses.sort((a, b) => a - b);
+}
diff --git a/src/core/services/subtitle-generation-process.ts b/src/core/services/subtitle-generation-process.ts
new file mode 100644
index 00000000..3905f7c7
--- /dev/null
+++ b/src/core/services/subtitle-generation-process.ts
@@ -0,0 +1,67 @@
+import { spawn } from 'node:child_process';
+import { expandSubtitleGenerationPath } from './subtitle-generation-files';
+
+const OUTPUT_LIMIT = 64 * 1024;
+
+// Keep partial lines between chunks: ffmpeg and whisper both report progress on stderr.
+export function runSubtitleGenerationProcess(input: {
+  command: string;
+  args: string[];
+  signal?: AbortSignal;
+  onLine?: (line: string) => void;
+}): Promise<string> {
+  input.signal?.throwIfAborted();
+  return new Promise((resolve, reject) => {
+    const child = spawn(expandSubtitleGenerationPath(input.command), input.args, {
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    let stdout = '';
+    let stderr = '';
+    let killTimer: ReturnType<typeof setTimeout> | undefined;
+    const abort = () => {
+      child.kill('SIGTERM');
+      killTimer = setTimeout(() => child.kill('SIGKILL'), 2000);
+      killTimer.unref();
+    };
+    input.signal?.addEventListener('abort', abort, { once: true });
+    if (input.signal?.aborted) abort();
+    const cleanup = () => {
+      input.signal?.removeEventListener('abort', abort);
+      clearTimeout(killTimer);
+    };
+    for (const [stream, isStdout] of [
+      [child.stdout, true],
+      [child.stderr, false],
+    ] as const) {
+      let pending = '';
+      stream.setEncoding('utf8');
+      stream.on('data', (chunk: string) => {
+        if (isStdout) stdout = (stdout + chunk).slice(-OUTPUT_LIMIT);
+        else stderr = (stderr + chunk).slice(-OUTPUT_LIMIT);
+        const lines = (pending + chunk).split(/[\r\n]/);
+        pending = (lines.pop() ?? '').slice(-OUTPUT_LIMIT);
+        for (const line of lines) input.onLine?.(line);
+      });
+      stream.on('end', () => {
+        if (pending) input.onLine?.(pending);
+      });
+    }
+    child.once('error', (error) => {
+      cleanup();
+      reject(
+        new Error(
+          'code' in error && error.code === 'ENOENT'
+            ? `${input.command} was not found. Install it or set its path under subtitleGeneration in Settings.`
+            : `Could not run ${input.command}: ${error.message}`,
+        ),
+      );
+    });
+    child.once('close', (code) => {
+      cleanup();
+      if (input.signal?.aborted) reject(new Error('Subtitle generation cancelled.'));
+      else if (code !== 0) {
+        reject(new Error(`${input.command} exited with status ${code}: ${stderr.trim()}`));
+      } else resolve(stdout);
+    });
+  });
+}
diff --git a/src/core/services/subtitle-generation-reference.test.ts b/src/core/services/subtitle-generation-reference.test.ts
new file mode 100644
index 00000000..6ab02e38
--- /dev/null
+++ b/src/core/services/subtitle-generation-reference.test.ts
@@ -0,0 +1,137 @@
+import assert from 'node:assert/strict';
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import test from 'node:test';
+import {
+  loadSubtitleGenerationReference,
+  readSubtitleGenerationReferences,
+  subtitleGenerationReferences,
+} from './subtitle-generation-reference';
+
+const embedded = { type: 'sub', codec: 'ass', 'ff-index': 2, lang: 'eng' };
+
+test('references exclude signs, songs, forced, bitmap and generated tracks even when selected', () => {
+  const excluded = [
+    'Signs & Songs',
+    'SignsSongs',
+    'Signs/Songs',
+    'S&S',
+    'S+S',
+    'Forced',
+    'Karaoke',
+    'OP',
+    'ED',
+    'English lyrics',
+    'Generated Japanese',
+  ];
+  assert.deepEqual(
+    subtitleGenerationReferences([
+      ...excluded.map((title) => ({ ...embedded, title, selected: true })),
+      { ...embedded, forced: true },
+      { ...embedded, codec: 'hdmv_pgs_subtitle' },
+      {
+        ...embedded,
+        title: 'English',
+        external: true,
+        'external-filename': '/subs/show.en.signs.ass',
+      },
+      { ...embedded, title: 'English Full' },
+    ]).map((reference) => reference.label),
+    ['English Full'],
+  );
+});
+
+test('references rank English dialogue first and resolve loaded external files against mpv cwd', () => {
+  const refs = subtitleGenerationReferences(
+    [
+      { ...embedded, title: 'French Full', lang: 'fra', selected: true },
+      { ...embedded, title: 'English' },
+      { type: 'sub', external: true, 'external-filename': 'subs/show.en.full.srt' },
+      { type: 'sub', external: true, 'external-filename': 'https://example.com/en.srt' },
+      { type: 'sub', 'ff-index': -1 },
+      null,
+    ],
+    '/mpv',
+  );
+  assert.deepEqual(
+    refs.map((ref) => ref.label),
+    ['show.en.full.srt', 'English', 'French Full'],
+  );
+  assert.deepEqual(refs[0]?.source, { kind: 'external', path: '/mpv/subs/show.en.full.srt' });
+  assert.deepEqual(
+    subtitleGenerationReferences([
+      { type: 'sub', external: true, 'external-filename': 'relative.en.srt' },
+    ]),
+    [],
+  );
+});
+
+test('reference discovery captures primary and secondary subtitle delays', async () => {
+  const properties: Record<string, unknown> = {
+    'working-directory': '/mpv',
+    sid: 1,
+    'secondary-sid': 2,
+    'sub-delay': 1.5,
+    'secondary-sub-delay': -2,
+  };
+  const refs = await readSubtitleGenerationReferences(
+    [
+      { ...embedded, id: 1 },
+      { ...embedded, id: 2 },
+      { ...embedded, id: 3 },
+    ],
+    async (name) => properties[name],
+  );
+  assert.deepEqual(
+    refs.map((ref) => ref.delaySeconds),
+    [1.5, -2, 0],
+  );
+});
+
+test('reference extraction retries unreadable tracks, restores audio offset and ignores marked lyrics', async () => {
+  const directory = await mkdtemp(path.join(tmpdir(), 'generation-reference-'));
+  try {
+    const ffmpegPath = path.join(directory, 'ffmpeg');
+    await writeFile(
+      ffmpegPath,
+      `#!${process.execPath}
+const args = process.argv.slice(2);
+if (args[args.indexOf('-map') + 1] === '0:2') process.exit(1);
+require('node:fs').writeFileSync(args.at(-1), '1\\n00:00:10,000 --> 00:00:12,000\\nHello\\n\\n2\\n00:00:20,000 --> 00:00:22,000\\n♪ Song ♪\\n\\n3\\n00:00:30,000 --> 00:00:32,000\\nWorld\\n');
+`,
+      { mode: 0o755 },
+    );
+    const refs = subtitleGenerationReferences([{ ...embedded }, { ...embedded, 'ff-index': 3 }]);
+    const hints = await loadSubtitleGenerationReference({
+      references: refs,
+      mediaPath: '/video.mkv',
+      ffmpegPath,
+      directory,
+      audioOffset: 2.5,
+    });
+    assert.deepEqual(hints, [7.5, 27.5]);
+    assert.deepEqual(
+      await loadSubtitleGenerationReference({
+        references: refs.slice(0, 1),
+        mediaPath: '/video.mkv',
+        ffmpegPath,
+        directory,
+        audioOffset: 0,
+      }),
+      [],
+    );
+    await assert.rejects(
+      loadSubtitleGenerationReference({
+        references: refs,
+        mediaPath: '/video.mkv',
+        ffmpegPath,
+        directory,
+        audioOffset: 0,
+        signal: AbortSignal.abort(),
+      }),
+    );
+  } finally {
+    await rm(directory, { recursive: true, force: true });
+  }
+});
diff --git a/src/core/services/subtitle-generation-reference.ts b/src/core/services/subtitle-generation-reference.ts
new file mode 100644
index 00000000..29842d3b
--- /dev/null
+++ b/src/core/services/subtitle-generation-reference.ts
@@ -0,0 +1,169 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import type { SubtitleGenerationProgress } from '../../shared/subtitle-generation';
+import { parseSrtCues } from './subtitle-cue-parser';
+import { runSubtitleGenerationProcess } from './subtitle-generation-process';
+
+export type SubtitleGenerationReference = {
+  label: string;
+  delaySeconds: number;
+  source: { kind: 'embedded'; streamIndex: number } | { kind: 'external'; path: string };
+};
+
+// Check both titles and filenames: releases often tag only one of them.
+const EXCLUDED =
+  /(?:^|[^\p{L}\p{N}])(?:signs?(?:songs?)?|songs?|lyrics?|karaoke|forced|s[\s&+_-]*s|op|ed|opening|ending|generated)(?=$|[^\p{L}\p{N}])|看板|歌詞/iu;
+const TEXT_CODECS = new Set(['ass', 'ssa', 'subrip', 'srt', 'webvtt', 'mov_text', 'text']);
+
+/** Rank loaded dialogue tracks, preferring English, then explicitly full tracks. */
+export function subtitleGenerationReferences(
+  value: unknown,
+  workingDirectory?: string,
+  delays: ReadonlyMap<number, number> = new Map(),
+): SubtitleGenerationReference[] {
+  if (!Array.isArray(value)) return [];
+  const tracks: unknown[] = value;
+  return tracks
+    .flatMap((track) => {
+      if (typeof track !== 'object' || track === null || !('type' in track) || track.type !== 'sub')
+        return [];
+      const title = 'title' in track && typeof track.title === 'string' ? track.title : '';
+      const filename =
+        'external-filename' in track && typeof track['external-filename'] === 'string'
+          ? track['external-filename']
+          : '';
+      const name = `${title} ${path.basename(filename)}`;
+      if (('forced' in track && track.forced === true) || EXCLUDED.test(name)) return [];
+      if ('codec' in track && typeof track.codec === 'string' && !TEXT_CODECS.has(track.codec))
+        return [];
+      let source: SubtitleGenerationReference['source'];
+      if ('external' in track && track.external === true) {
+        let local = filename;
+        if (local.startsWith('file://')) {
+          try {
+            local = fileURLToPath(local);
+          } catch {
+            return [];
+          }
+        } else if (/^[a-z][a-z\d+.-]*:\/\//i.test(local)) return [];
+        if (!local || (!path.isAbsolute(local) && !workingDirectory)) return [];
+        if (!/\.(?:srt|ass|ssa|vtt)$/i.test(local)) return [];
+        source = { kind: 'external', path: path.resolve(workingDirectory ?? '.', local) };
+      } else {
+        if (
+          !('ff-index' in track) ||
+          typeof track['ff-index'] !== 'number' ||
+          !Number.isSafeInteger(track['ff-index']) ||
+          track['ff-index'] < 0
+        )
+          return [];
+        source = { kind: 'embedded', streamIndex: track['ff-index'] };
+      }
+      const language = 'lang' in track && typeof track.lang === 'string' ? track.lang : '';
+      const english =
+        /^(?:en|eng|english)(?:[-_]|$)/i.test(language) ||
+        /(?:^|[\s.\[(_-])(?:en|eng|english)(?=$|[\s.\])_-])/i.test(name);
+      const full = /\b(?:full|dialogue|dialog)\b/i.test(name);
+      const selected = 'selected' in track && track.selected === true;
+      const preferred = 'default' in track && track.default === true;
+      return [
+        {
+          reference: {
+            label:
+              title ||
+              path.basename(filename) ||
+              `${language || 'Subtitle'} stream ${source.kind === 'embedded' ? source.streamIndex : ''}`,
+            source,
+            delaySeconds:
+              'id' in track && typeof track.id === 'number' ? (delays.get(track.id) ?? 0) : 0,
+          },
+          score:
+            Number(english) * 100 + Number(full) * 20 + Number(selected) * 2 + Number(preferred),
+        },
+      ];
+    })
+    .sort((a, b) => b.score - a.score)
+    .map(({ reference }) => reference);
+}
+
+/** Read mpv's path base and active subtitle delays while capturing timing references. */
+export async function readSubtitleGenerationReferences(
+  tracks: unknown,
+  requestProperty: (name: string) => Promise<unknown>,
+): Promise<SubtitleGenerationReference[]> {
+  const [directory, primary, secondary, primaryDelay, secondaryDelay] = await Promise.all(
+    ['working-directory', 'sid', 'secondary-sid', 'sub-delay', 'secondary-sub-delay'].map((name) =>
+      requestProperty(name).catch(() => null),
+    ),
+  );
+  const delays = new Map<number, number>();
+  for (const [id, delay] of [
+    [primary, primaryDelay],
+    [secondary, secondaryDelay],
+  ]) {
+    if (typeof id === 'number' && typeof delay === 'number' && Number.isFinite(delay))
+      delays.set(id, delay);
+  }
+  return subtitleGenerationReferences(
+    tracks,
+    typeof directory === 'string' ? directory : undefined,
+    delays,
+  );
+}
+
+/** Reference timestamps are hints on the extracted audio timeline, never a coverage mask. */
+export async function loadSubtitleGenerationReference(input: {
+  references: readonly SubtitleGenerationReference[];
+  mediaPath: string;
+  ffmpegPath: string;
+  directory: string;
+  audioOffset: number;
+  onProgress?: (progress: SubtitleGenerationProgress) => void;
+  signal?: AbortSignal;
+}): Promise<number[]> {
+  for (const [index, reference] of input.references.entries()) {
+    input.signal?.throwIfAborted();
+    try {
+      const output = path.join(input.directory, `reference-${index}.srt`);
+      const embedded = reference.source.kind === 'embedded';
+      await runSubtitleGenerationProcess({
+        command: input.ffmpegPath,
+        args: [
+          '-nostdin',
+          '-hide_banner',
+          '-loglevel',
+          'error',
+          ...(embedded ? ['-copyts', '-start_at_zero'] : []),
+          '-i',
+          reference.source.kind === 'external' ? reference.source.path : input.mediaPath,
+          '-map',
+          reference.source.kind === 'embedded' ? `0:${reference.source.streamIndex}` : '0:s:0',
+          '-c:s',
+          'srt',
+          output,
+        ],
+        signal: input.signal,
+      });
+      const starts = parseSrtCues(await readFile(output, 'utf8'))
+        .filter((cue) => cue.text.trim() && !/[♪♫]/u.test(cue.text) && cue.endTime > cue.startTime)
+        .map((cue) => cue.startTime + reference.delaySeconds - input.audioOffset)
+        .filter((time) => Number.isFinite(time) && time >= 0);
+      if (starts.length === 0) continue;
+      input.onProgress?.({
+        stage: 'extract',
+        message: `Using subtitle timing reference: ${reference.label}`,
+      });
+      return [...new Set(starts)].sort((a, b) => a - b);
+    } catch {
+      input.signal?.throwIfAborted();
+      // An optional reference must not prevent transcription. Try the next loaded track.
+    }
+  }
+  if (input.references.length)
+    input.onProgress?.({
+      stage: 'extract',
+      message: 'No readable subtitle timing reference. Using audio timing.',
+    });
+  return [];
+}
diff --git a/src/core/services/subtitle-generation-speech.test.ts b/src/core/services/subtitle-generation-speech.test.ts
new file mode 100644
index 00000000..c1f3c351
--- /dev/null
+++ b/src/core/services/subtitle-generation-speech.test.ts
@@ -0,0 +1,78 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { parseSpeechPassages, speechPassageCues } from './subtitle-generation-speech';
+
+test('speech passages convert centiseconds, group nearby speech, and retain long gaps', () => {
+  assert.deepEqual(
+    parseSpeechPassages(
+      [
+        'Detected 4 speech segments:',
+        'Speech segment 0: start = 0.00, end = 300.00',
+        'Speech segment 1: start = 350.00, end = 900.00',
+        'Speech segment 2: start = 10000.00, end = 11900.00',
+        'Speech segment 3: start = 11950.00, end = 12500.00',
+      ].join('\n'),
+    ),
+    [
+      { startSeconds: 0, endSeconds: 9 },
+      { startSeconds: 100, endSeconds: 119 },
+      { startSeconds: 119.5, endSeconds: 125 },
+    ],
+  );
+});
+
+test('speech passages retain long merged detector segments for pause-aware splitting', () => {
+  assert.deepEqual(
+    parseSpeechPassages(
+      [
+        'Detected 3 speech segments:',
+        'Speech segment 0: start = 33714.00, end = 36756.00',
+        'Speech segment 1: start = 40000.00, end = 46000.00',
+        'Speech segment 2: start = 50000.00, end = 50100.00',
+      ].join('\n'),
+    ),
+    [
+      { startSeconds: 337.14, endSeconds: 367.56 },
+      { startSeconds: 400, endSeconds: 460 },
+      { startSeconds: 500, endSeconds: 501 },
+    ],
+  );
+});
+
+test('speech detector distinguishes no speech from missing, malformed, or truncated output', () => {
+  assert.deepEqual(parseSpeechPassages('Detected 0 speech segments:'), []);
+  assert.deepEqual(
+    parseSpeechPassages(
+      'Detected 1 speech segments:\nSpeech segment 0: start = 79896.00, end = 82218.00',
+    ),
+    [{ startSeconds: 798.96, endSeconds: 822.18 }],
+  );
+  for (const output of [
+    '',
+    'Detected 1 speech segments:',
+    'Detected 1 speech segments:\nSpeech segment 1: start = 100.00, end = 200.00',
+    'Detected 1 speech segments:\nSpeech segment 0: start = 200.00, end = 100.00',
+    'Detected 1 speech segments:\nSpeech segment 0: start = NaN, end = 100.00',
+    'Detected 2 speech segments:\nSpeech segment 0: start = 0.00, end = 200.00\nSpeech segment 1: start = 100.00, end = 300.00',
+  ])
+    assert.throws(() => parseSpeechPassages(output), /Speech detector/);
+});
+
+test('passage cue times cannot extend into omitted audio or accumulate offsets', () => {
+  const srt =
+    '1\n00:00:00,000 --> 00:00:01,000\nはい\n\n2\n00:00:01,000 --> 00:01:40,000\nはい\n\n3\n00:01:41,000 --> 00:01:42,000\n幻覚\n';
+  assert.deepEqual(
+    speechPassageCues(srt, { startSeconds: 1200.25, endSeconds: 1203.75 }).map(
+      ({ startTime, endTime, text }) => ({ startTime, endTime, text }),
+    ),
+    [
+      { startTime: 1200.25, endTime: 1201.25, text: 'はい' },
+      { startTime: 1201.25, endTime: 1203.75, text: 'はい' },
+    ],
+  );
+  assert.deepEqual(speechPassageCues('', { startSeconds: 0, endSeconds: 1 }), []);
+  assert.throws(
+    () => speechPassageCues('broken SRT', { startSeconds: 0, endSeconds: 1 }),
+    /malformed/,
+  );
+});
diff --git a/src/core/services/subtitle-generation-speech.ts b/src/core/services/subtitle-generation-speech.ts
new file mode 100644
index 00000000..5e4a65c1
--- /dev/null
+++ b/src/core/services/subtitle-generation-speech.ts
@@ -0,0 +1,66 @@
+import { parseSrtCues, type SubtitleCue } from './subtitle-cue-parser';
+
+export interface SpeechPassage {
+  startSeconds: number;
+  endSeconds: number;
+}
+
+export const SPEECH_PASSAGE_SECONDS = 20;
+
+// The standalone whisper.cpp detector reports centiseconds, unlike its diagnostic logs.
+export function parseSpeechPassages(output: string): SpeechPassage[] {
+  const count = /^Detected (\d+) speech segments:$/m.exec(output);
+  if (!count) throw new Error('Speech detector did not report its segment count.');
+  const passages: SpeechPassage[] = [];
+  for (const line of output.split(/\r?\n/)) {
+    if (!line.startsWith('Speech segment ')) continue;
+    const match = /^Speech segment (\d+): start = (\d+(?:\.\d+)?), end = (\d+(?:\.\d+)?)$/.exec(
+      line,
+    );
+    if (!match) throw new Error('Speech detector returned a malformed segment.');
+    const index = Number(match[1]);
+    const startSeconds = Number(match[2]) / 100;
+    const endSeconds = Number(match[3]) / 100;
+    if (
+      index !== passages.length ||
+      !Number.isFinite(startSeconds) ||
+      !Number.isFinite(endSeconds) ||
+      endSeconds <= startSeconds ||
+      startSeconds < (passages.at(-1)?.endSeconds ?? 0)
+    ) {
+      throw new Error('Speech detector returned unordered or invalid segment timing.');
+    }
+    passages.push({ startSeconds, endSeconds });
+  }
+  if (passages.length !== Number(count[1]))
+    throw new Error('Speech detector output is incomplete.');
+
+  const grouped: SpeechPassage[] = [];
+  for (const passage of passages) {
+    const previous = grouped.at(-1);
+    if (
+      previous &&
+      passage.startSeconds - previous.endSeconds <= 1 &&
+      passage.endSeconds - previous.startSeconds <= SPEECH_PASSAGE_SECONDS
+    ) {
+      previous.endSeconds = passage.endSeconds;
+    } else grouped.push({ ...passage });
+  }
+  return grouped;
+}
+
+// Clamp to the audio actually supplied to Whisper. A cue cannot cross an omitted gap.
+export function speechPassageCues(srt: string, passage: SpeechPassage): SubtitleCue[] {
+  const duration = passage.endSeconds - passage.startSeconds;
+  const cues = parseSrtCues(srt);
+  if (srt.trim() && cues.length === 0)
+    throw new Error('Whisper returned malformed subtitles for a speech passage.');
+  return cues.flatMap((cue) => {
+    const start = Math.max(0, cue.startTime);
+    const end = Math.min(duration, cue.endTime);
+    if (!Number.isFinite(start) || !Number.isFinite(end) || end <= start) return [];
+    return [
+      { ...cue, startTime: passage.startSeconds + start, endTime: passage.startSeconds + end },
+    ];
+  });
+}
diff --git a/src/core/services/subtitle-generation-srt.ts b/src/core/services/subtitle-generation-srt.ts
new file mode 100644
index 00000000..fec683a5
--- /dev/null
+++ b/src/core/services/subtitle-generation-srt.ts
@@ -0,0 +1,7 @@
+export function formatTimestamp(milliseconds: number): string {
+  const rounded = Math.max(0, Math.round(milliseconds));
+  const hours = Math.floor(rounded / 3600000);
+  const minutes = Math.floor((rounded % 3600000) / 60000);
+  const seconds = Math.floor((rounded % 60000) / 1000);
+  return `${String(hours).padStart(2, '0')}:${String(minutes).padStart(2, '0')}:${String(seconds).padStart(2, '0')},${String(rounded % 1000).padStart(3, '0')}`;
+}
diff --git a/src/core/services/subtitle-generation-tools.test.ts b/src/core/services/subtitle-generation-tools.test.ts
new file mode 100644
index 00000000..7b057735
--- /dev/null
+++ b/src/core/services/subtitle-generation-tools.test.ts
@@ -0,0 +1,85 @@
+import assert from 'node:assert/strict';
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import test from 'node:test';
+import { DEFAULT_SUBTITLE_GENERATION_CONFIG } from '../../shared/subtitle-generation';
+import {
+  requireSubtitleGenerationTools,
+  resolveSubtitleGenerationTools,
+} from './subtitle-generation-tools';
+
+async function fixture(run: (directory: string) => Promise<void>) {
+  const directory = await mkdtemp(path.join(tmpdir(), 'subtitle-generation-tools-'));
+  try {
+    await run(directory);
+  } finally {
+    await rm(directory, { recursive: true, force: true });
+  }
+}
+
+async function executable(directory: string, name: string): Promise<string> {
+  const file = path.join(directory, name);
+  await writeFile(file, '#!/bin/sh\n', { mode: 0o755 });
+  return file;
+}
+
+test('tools resolve from PATH, honor overrides, and only require the detector in dialogue mode', () =>
+  fixture(async (directory) => {
+    const bin = path.join(directory, 'bin');
+    await mkdir(bin);
+    for (const name of ['ffmpeg', 'ffprobe', 'whisper-cli']) await executable(bin, name);
+    const detector = await executable(bin, 'vad-speech-segments');
+    const customWhisper = await executable(directory, 'my-whisper');
+    await writeFile(path.join(directory, 'not-executable'), '', { mode: 0o644 });
+    const env = { PATH: bin };
+
+    const found = await resolveSubtitleGenerationTools(DEFAULT_SUBTITLE_GENERATION_CONFIG, env);
+    assert.deepEqual(found, {
+      ffmpeg: { kind: 'found', path: path.join(bin, 'ffmpeg') },
+      ffprobe: { kind: 'found', path: path.join(bin, 'ffprobe') },
+      whisper: { kind: 'found', path: path.join(bin, 'whisper-cli') },
+      vad: null,
+    });
+    assert.equal(requireSubtitleGenerationTools(found).vad, null);
+
+    const dialogue = await resolveSubtitleGenerationTools(
+      { ...DEFAULT_SUBTITLE_GENERATION_CONFIG, vadModelPath: '/models/vad.bin' },
+      env,
+    );
+    assert.deepEqual(dialogue.vad, { kind: 'found', path: detector });
+
+    const overridden = await resolveSubtitleGenerationTools(
+      {
+        ...DEFAULT_SUBTITLE_GENERATION_CONFIG,
+        whisperPath: customWhisper,
+        ffmpegPath: path.join(directory, 'not-executable'),
+      },
+      env,
+    );
+    assert.deepEqual(overridden.whisper, { kind: 'found', path: customWhisper });
+    assert.equal(overridden.ffmpeg.kind, 'missing');
+    assert.throws(
+      () => requireSubtitleGenerationTools(overridden),
+      /not-executable \(subtitleGeneration\.ffmpegPath\) is not an executable file/,
+    );
+  }));
+
+test('missing tools name the executable, the installer, and the setting', () =>
+  fixture(async (directory) => {
+    const tools = await resolveSubtitleGenerationTools(
+      { ...DEFAULT_SUBTITLE_GENERATION_CONFIG, vadModelPath: '/models/vad.bin' },
+      { PATH: directory },
+    );
+    assert.deepEqual(tools.whisper, {
+      kind: 'missing',
+      message:
+        'whisper-cli was not found on PATH. Install whisper.cpp or set subtitleGeneration.whisperPath in Settings.',
+    });
+    assert.deepEqual(tools.vad, {
+      kind: 'missing',
+      message:
+        "whisper-vad-speech-segments was not found on PATH. Install whisper.cpp's speech segment detector or set subtitleGeneration.vadPath in Settings.",
+    });
+    assert.throws(() => requireSubtitleGenerationTools(tools), /ffmpeg was not found on PATH/);
+  }));
diff --git a/src/core/services/subtitle-generation-tools.ts b/src/core/services/subtitle-generation-tools.ts
new file mode 100644
index 00000000..0477bb1b
--- /dev/null
+++ b/src/core/services/subtitle-generation-tools.ts
@@ -0,0 +1,125 @@
+import { access, stat } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import path from 'node:path';
+import type {
+  SubtitleGenerationConfig,
+  SubtitleGenerationToolStatus,
+  SubtitleGenerationTools,
+} from '../../shared/subtitle-generation';
+import { expandSubtitleGenerationPath } from './subtitle-generation-files';
+
+/** Executable paths ready to spawn. `vad` is null when dialogue mode is off. */
+export interface SubtitleGenerationToolPaths {
+  ffmpeg: string;
+  ffprobe: string;
+  whisper: string;
+  vad: string | null;
+}
+
+const TOOL_LOOKUPS = {
+  ffmpeg: { setting: 'ffmpegPath', names: ['ffmpeg'], install: 'Install FFmpeg' },
+  ffprobe: { setting: 'ffprobePath', names: ['ffprobe'], install: 'Install FFmpeg' },
+  whisper: { setting: 'whisperPath', names: ['whisper-cli'], install: 'Install whisper.cpp' },
+  vad: {
+    setting: 'vadPath',
+    names: ['whisper-vad-speech-segments', 'vad-speech-segments'],
+    install: "Install whisper.cpp's speech segment detector",
+  },
+} as const;
+
+async function isExecutableFile(filePath: string): Promise<boolean> {
+  try {
+    if (!(await stat(filePath)).isFile()) return false;
+    await access(filePath, constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function executableNames(name: string, env: NodeJS.ProcessEnv): string[] {
+  if (process.platform !== 'win32' || path.extname(name)) return [name];
+  const extensions = (env.PATHEXT ?? '.EXE;.CMD;.BAT')
+    .split(';')
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+  return [name, ...extensions.map((extension) => `${name}${extension}`)];
+}
+
+async function findOnPath(names: readonly string[], env: NodeJS.ProcessEnv): Promise<string> {
+  const directories = (env.PATH ?? '')
+    .split(path.delimiter)
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+  for (const directory of directories) {
+    for (const name of names) {
+      for (const candidate of executableNames(name, env)) {
+        const filePath = path.join(directory, candidate);
+        if (await isExecutableFile(filePath)) return filePath;
+      }
+    }
+  }
+  return '';
+}
+
+async function resolveTool(
+  tool: keyof typeof TOOL_LOOKUPS,
+  config: SubtitleGenerationConfig,
+  env: NodeJS.ProcessEnv,
+): Promise<SubtitleGenerationToolStatus> {
+  const lookup = TOOL_LOOKUPS[tool];
+  const override = config[lookup.setting].trim();
+  if (override) {
+    const expanded = expandSubtitleGenerationPath(override);
+    const found =
+      path.dirname(expanded) === '.'
+        ? await findOnPath([expanded], env)
+        : (await isExecutableFile(expanded))
+          ? path.resolve(expanded)
+          : '';
+    return found
+      ? { kind: 'found', path: found }
+      : {
+          kind: 'missing',
+          message: `${override} (subtitleGeneration.${lookup.setting}) is not an executable file.`,
+        };
+  }
+  const found = await findOnPath(lookup.names, env);
+  return found
+    ? { kind: 'found', path: found }
+    : {
+        kind: 'missing',
+        message: `${lookup.names[0]} was not found on PATH. ${lookup.install} or set subtitleGeneration.${lookup.setting} in Settings.`,
+      };
+}
+
+/** Locate every executable a generation run needs, before any model download or audio work. */
+export async function resolveSubtitleGenerationTools(
+  config: SubtitleGenerationConfig,
+  env: NodeJS.ProcessEnv = process.env,
+): Promise<SubtitleGenerationTools> {
+  const [ffmpeg, ffprobe, whisper, vad] = await Promise.all([
+    resolveTool('ffmpeg', config, env),
+    resolveTool('ffprobe', config, env),
+    resolveTool('whisper', config, env),
+    config.vadModelPath.trim() ? resolveTool('vad', config, env) : null,
+  ]);
+  return { ffmpeg, ffprobe, whisper, vad };
+}
+
+function foundPath(tool: SubtitleGenerationToolStatus): string {
+  if (tool.kind === 'missing') throw new Error(tool.message);
+  return tool.path;
+}
+
+/** Throw the first missing tool's message, otherwise narrow to spawnable paths. */
+export function requireSubtitleGenerationTools(
+  tools: SubtitleGenerationTools,
+): SubtitleGenerationToolPaths {
+  return {
+    ffmpeg: foundPath(tools.ffmpeg),
+    ffprobe: foundPath(tools.ffprobe),
+    whisper: foundPath(tools.whisper),
+    vad: tools.vad ? foundPath(tools.vad) : null,
+  };
+}
diff --git a/src/core/services/subtitle-generation-vad-model.ts b/src/core/services/subtitle-generation-vad-model.ts
new file mode 100644
index 00000000..7a17d9ec
--- /dev/null
+++ b/src/core/services/subtitle-generation-vad-model.ts
@@ -0,0 +1,63 @@
+import { access, stat } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import path from 'node:path';
+import type {
+  SubtitleGenerationConfig,
+  SubtitleGenerationModelStatus,
+  SubtitleGenerationProgress,
+} from '../../shared/subtitle-generation';
+import { SUBTITLE_GENERATION_VAD_MODEL } from '../../shared/subtitle-generation-vad-model';
+import { expandSubtitleGenerationPath } from './subtitle-generation-files';
+import { isMissingFile } from './subtitle-generation-models';
+import { downloadSubtitleGenerationArtifact } from './subtitle-generation-download';
+
+export async function resolveSubtitleGenerationVadModel(
+  config: SubtitleGenerationConfig,
+  modelDirectory: string,
+): Promise<SubtitleGenerationModelStatus> {
+  const external = config.vadModelPath.trim();
+  const modelPath = external
+    ? path.resolve(expandSubtitleGenerationPath(external))
+    : path.resolve(modelDirectory, SUBTITLE_GENERATION_VAD_MODEL.filename);
+  try {
+    const info = await stat(modelPath);
+    if (
+      !info.isFile() ||
+      info.size === 0 ||
+      (!external && info.size !== SUBTITLE_GENERATION_VAD_MODEL.size)
+    )
+      return {
+        kind: 'invalid',
+        path: modelPath,
+        message: 'Speech detection model has an invalid size.',
+      };
+    await access(modelPath, constants.R_OK);
+    return { kind: external ? 'external' : 'managed', path: modelPath };
+  } catch (error) {
+    if (!external && isMissingFile(error)) return { kind: 'missing', path: modelPath };
+    return {
+      kind: 'invalid',
+      path: modelPath,
+      message: `Cannot read speech detection model: ${error instanceof Error ? error.message : String(error)}`,
+    };
+  }
+}
+
+export async function downloadSubtitleGenerationVadModel(input: {
+  config: SubtitleGenerationConfig;
+  modelDirectory: string;
+  onProgress?: (progress: SubtitleGenerationProgress) => void;
+  signal?: AbortSignal;
+}): Promise<string> {
+  input.signal?.throwIfAborted();
+  const current = await resolveSubtitleGenerationVadModel(input.config, input.modelDirectory);
+  if (current.kind === 'invalid') throw new Error(current.message);
+  if (current.kind !== 'missing') return current.path;
+  return downloadSubtitleGenerationArtifact({
+    ...SUBTITLE_GENERATION_VAD_MODEL,
+    destination: current.path,
+    label: 'Silero speech detection model',
+    onProgress: input.onProgress,
+    signal: input.signal,
+  });
+}
diff --git a/src/core/services/subtitle-generation.test.ts b/src/core/services/subtitle-generation.test.ts
new file mode 100644
index 00000000..a3c40a45
--- /dev/null
+++ b/src/core/services/subtitle-generation.test.ts
@@ -0,0 +1,500 @@
+import assert from 'node:assert/strict';
+import { constants } from 'node:fs';
+import { access, chmod, mkdir, mkdtemp, readFile, readdir, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import test from 'node:test';
+import {
+  DEFAULT_SUBTITLE_GENERATION_CONFIG,
+  resolveSubtitleGenerationConfig,
+  type SubtitleGenerationProgress,
+} from '../../shared/subtitle-generation';
+import {
+  downloadSubtitleGenerationModel,
+  ensureWritableDirectory,
+  generateJapaneseSubtitles,
+  resolveSubtitleGenerationModel,
+} from './subtitle-generation';
+import { runSubtitleGenerationProcess } from './subtitle-generation-process';
+
+async function fixture(run: (directory: string) => Promise<void>) {
+  const directory = await mkdtemp(path.join(tmpdir(), 'subtitle-generation-test-'));
+  try {
+    await run(directory);
+  } finally {
+    await rm(directory, { recursive: true, force: true });
+  }
+}
+
+async function executable(directory: string, name: string, body: string) {
+  const file = path.join(directory, name);
+  await writeFile(file, `#!${process.execPath}\n${body}`, { mode: 0o755 });
+  return file;
+}
+
+function modelHeader(vocabularySize = 51865): Buffer {
+  const header = Buffer.alloc(8);
+  header.writeUInt32LE(0x67676d6c, 0);
+  header.writeInt32LE(vocabularySize, 4);
+  return header;
+}
+
+async function generationFixture(directory: string) {
+  const modelPath = path.join(directory, 'external.bin');
+  const mediaPath = path.join(directory, 'episode.mkv');
+  const callsPath = path.join(directory, 'calls.jsonl');
+  await writeFile(modelPath, modelHeader());
+  await writeFile(mediaPath, 'local media');
+  const record = `require('node:fs').appendFileSync(${JSON.stringify(callsPath)}, JSON.stringify(process.argv.slice(2)) + '\\n');`;
+  const ffprobePath = await executable(
+    directory,
+    'ffprobe',
+    `${record}\nprocess.stdout.write(JSON.stringify({streams: [{index:1,codec_type:'audio',start_time:'10',tags:{language:'eng'}},{index:3,codec_type:'audio',start_time:'12.5',duration:'20',tags:{language:'jpn'}}],format:{start_time:'10',duration:'25'}}));`,
+  );
+  const ffmpegPath = await executable(
+    directory,
+    'ffmpeg',
+    `${record}
+if (process.argv.at(-1) === '-') {
+  process.stderr.write('[silencedetect] silence_end: 25 | silence_duration: 25\\n');
+  process.stdout.write('out_time_us=25000000\\nprogress=end\\n');
+} else {
+  require('node:fs').writeFileSync(process.argv.at(-1), 'wav');
+  process.stdout.write('out_time_');
+  setTimeout(() => process.stdout.write('us=10000000\\nprogress=end\\n'), 10);
+}`,
+  );
+  const whisperPath = await executable(
+    directory,
+    'whisper-cli',
+    `${record}\nconst args=process.argv.slice(2); require('node:fs').writeFileSync(args[args.indexOf('-of')+1]+'.srt', '1\\n00:00:01,000 --> 00:00:02,000\\nこんにちは\\n'); process.stderr.write('whisper_print_progress_callback: progress = '); setTimeout(() => process.stderr.write('55%\\n'), 10);`,
+  );
+  return {
+    config: {
+      ...DEFAULT_SUBTITLE_GENERATION_CONFIG,
+      modelPath,
+      ffprobePath,
+      ffmpegPath,
+      whisperPath,
+    },
+    mediaPath,
+    modelDirectory: path.join(directory, 'models'),
+    callsPath,
+  };
+}
+
+test('config parser accepts supported models and rejects unsafe threads and wrong field types', () => {
+  const warnings: string[] = [];
+  const result = resolveSubtitleGenerationConfig(
+    { modelPath: '/tmp/whisper.bin', threads: 0, whisperPath: 42, managedModel: 'large-v3-turbo' },
+    (key) => warnings.push(key),
+  );
+  assert.equal(result.modelPath, '/tmp/whisper.bin');
+  assert.equal(result.managedModel, 'large-v3-turbo');
+  assert.equal(result.threads, DEFAULT_SUBTITLE_GENERATION_CONFIG.threads);
+  assert.deepEqual(warnings, ['whisperPath', 'threads']);
+});
+
+test('generation uses reference cuts with and without VAD while preserving media offsets', () =>
+  fixture(async (directory) => {
+    const input = await generationFixture(directory);
+    const ffmpegPath = await executable(
+      directory,
+      'reference-ffmpeg',
+      `
+const fs = require('node:fs');
+const args = process.argv.slice(2);
+fs.appendFileSync(${JSON.stringify(input.callsPath)}, JSON.stringify(args) + '\\n');
+if (args.includes('-c:s')) {
+  fs.writeFileSync(args.at(-1), '1\\n00:00:24,500 --> 00:00:26,500\\nHello\\n\\n2\\n00:00:45,500 --> 00:00:47,500\\nWorld\\n');
+} else if (args.at(-1) === '-') {
+  process.stdout.write('out_time_us=70000000\\nprogress=end\\n');
+} else fs.writeFileSync(args.at(-1), 'wav');
+`,
+    );
+    const vadPath = await executable(
+      directory,
+      'reference-vad',
+      "process.stdout.write('Detected 1 speech segments:\\nSpeech segment 0: start = 0.000, end = 7000.000\\n');",
+    );
+    const vadModelPath = path.join(directory, 'vad.bin');
+    await writeFile(vadModelPath, 'model');
+    for (const vad of [false, true]) {
+      await writeFile(input.callsPath, '');
+      const output = await generateJapaneseSubtitles({
+        ...input,
+        config: { ...input.config, ffmpegPath, vadPath, vadModelPath: vad ? vadModelPath : '' },
+        references: [
+          { label: 'English Full', delaySeconds: 0, source: { kind: 'embedded', streamIndex: 5 } },
+        ],
+      });
+      const calls: string[][] = (await readFile(input.callsPath, 'utf8'))
+        .trim()
+        .split('\n')
+        .map((line) => JSON.parse(line));
+      const clips = calls.filter((args) => args.includes('-ss'));
+      assert.equal(clips[0]?.[clips[0].indexOf('-t') + 1], '22.25');
+      assert.equal(clips[1]?.[clips[1].indexOf('-ss') + 1], '21.75');
+      const srt = await readFile(output, 'utf8');
+      assert.match(srt, /00:00:03,500 --> 00:00:04,500/);
+      assert.match(srt, /00:00:25,250 --> 00:00:26,250/);
+    }
+  }));
+
+test('external model path wins and invalid external models never fall back to download', () =>
+  fixture(async (directory) => {
+    const input = await generationFixture(directory);
+    assert.deepEqual(await resolveSubtitleGenerationModel(input.config, input.modelDirectory), {
+      kind: 'external',
+      path: input.config.modelPath,
+    });
+    const invalid = { ...input.config, modelPath: path.join(directory, 'missing.bin') };
+    assert.equal(
+      (await resolveSubtitleGenerationModel(invalid, input.modelDirectory)).kind,
+      'invalid',
+    );
+    await assert.rejects(
+      downloadSubtitleGenerationModel({ ...input, config: invalid }),
+      /Cannot read model/,
+    );
+    assert.equal(
+      (
+        await resolveSubtitleGenerationModel(
+          { ...input.config, modelPath: '' },
+          input.modelDirectory,
+        )
+      ).kind,
+      'missing',
+    );
+  }));
+
+test('English-only and incompatible external models are rejected before transcription', () =>
+  fixture(async (directory) => {
+    const input = await generationFixture(directory);
+    await writeFile(input.config.modelPath, modelHeader(51864));
+    const englishOnly = await resolveSubtitleGenerationModel(input.config, input.modelDirectory);
+    assert.equal(englishOnly.kind, 'invalid');
+    assert.ok('message' in englishOnly);
+    assert.match(englishOnly.message, /English-only/);
+    await assert.rejects(generateJapaneseSubtitles(input), /requires a multilingual model/);
+    await writeFile(input.config.modelPath, 'not a GGML model');
+    await assert.rejects(generateJapaneseSubtitles(input), /Unsupported model format/);
+    await writeFile(input.config.modelPath, modelHeader().subarray(0, 4));
+    await assert.rejects(generateJapaneseSubtitles(input), /Unsupported model format/);
+    await assert.rejects(readFile(input.callsPath), /ENOENT/);
+  }));
+
+test('generation picks Japanese audio, restores timeline offsets, reports split progress, and preserves existing output', () =>
+  fixture(async (directory) => {
+    const input = await generationFixture(directory);
+    const existing = path.join(directory, 'episode.ja.generated.srt');
+    await writeFile(existing, 'user subtitles');
+    const progress: SubtitleGenerationProgress[] = [];
+    const result = await generateJapaneseSubtitles({
+      ...input,
+      onProgress: (event) => progress.push(event),
+    });
+    assert.equal(result, path.join(directory, 'episode.ja.generated.1.srt'));
+    assert.equal(await readFile(existing, 'utf8'), 'user subtitles');
+    assert.match(await readFile(result, 'utf8'), /00:00:03,500 --> 00:00:04,500\nこんにちは/);
+    const calls = (await readFile(input.callsPath, 'utf8'))
+      .trim()
+      .split('\n')
+      .map((line): unknown => JSON.parse(line));
+    assert.ok(Array.isArray(calls[1]));
+    assert.ok(calls[1].includes('0:3'));
+    assert.ok(Array.isArray(calls[2]));
+    assert.ok(calls[2].includes('ja'));
+    assert.ok(calls[2].includes('-osrt'));
+    assert.ok(progress.some((event) => event.stage === 'extract' && event.percent === 50));
+    assert.ok(progress.some((event) => event.stage === 'transcribe' && event.percent === 55));
+    assert.deepEqual(
+      (await readdir(directory)).filter((file) => file.startsWith('.subminer-')),
+      [],
+    );
+  }));
+
+test('explicit audio stream and output path are respected without overwriting existing files', () =>
+  fixture(async (directory) => {
+    const input = await generationFixture(directory);
+    const outputPath = path.join(directory, 'chosen.srt');
+    const result = await generateJapaneseSubtitles({ ...input, audioStreamIndex: 1, outputPath });
+    assert.equal(result, outputPath);
+    assert.match(await readFile(result, 'utf8'), /00:00:01,000 --> 00:00:02,000/);
+    await assert.rejects(generateJapaneseSubtitles({ ...input, outputPath }), /already exists/);
+    await assert.rejects(
+      generateJapaneseSubtitles({ ...input, audioStreamIndex: 99 }),
+      /stream 99 was not found/,
+    );
+  }));
+
+test('dialogue generation isolates Whisper state between passages and preserves media timing', () =>
+  fixture(async (directory) => {
+    const input = await generationFixture(directory);
+    const vadModelPath = path.join(directory, 'vad.bin');
+    await writeFile(vadModelPath, 'speech detector model');
+    const vadPath = await executable(
+      directory,
+      'vad',
+      "process.stdout.write('Detected 2 speech segments:\\nSpeech segment 0: start = 1000.00, end = 1100.00\\nSpeech segment 1: start = 10000.00, end = 10100.00\\n');",
+    );
+    const whisperPath = await executable(
+      directory,
+      'dialogue-whisper',
+      `const args = process.argv.slice(2);
+let files = 0;
+for (let i = 0; i < args.length; i++) if (args[i] === '-of') {
+  // Reproduce a decoder that degenerates when reused for another audio file.
+  const text = files++ === 0 ? 'はい' : 'お' + 'ぉ'.repeat(40) + 'ぇ'.repeat(178);
+  require('node:fs').writeFileSync(args[i + 1] + '.srt', '1\\n00:00:00,000 --> 00:01:39,000\\n' + text + '\\n');
+}`,
+    );
+    const output = await generateJapaneseSubtitles({
+      ...input,
+      config: { ...input.config, vadModelPath, vadPath, whisperPath },
+    });
+    assert.equal(
+      await readFile(output, 'utf8'),
+      '1\n00:00:12,500 --> 00:00:13,500\nはい\n\n2\n00:01:42,500 --> 00:01:43,500\nはい\n',
+    );
+  }));
+
+test('dialogue generation uses quiet pauses and stitches overlapping chunks on the media timeline', () =>
+  fixture(async (directory) => {
+    const input = await generationFixture(directory);
+    const vadModelPath = path.join(directory, 'vad.bin');
+    await writeFile(vadModelPath, 'speech detector model');
+    const vadPath = await executable(
+      directory,
+      'vad',
+      `const assert = require('node:assert/strict');
+const args = process.argv.slice(2);
+assert.equal(args[args.indexOf('--vad-min-speech-duration-ms') + 1], '100');
+assert.equal(args[args.indexOf('-vp') + 1], '350');
+process.stdout.write('Detected 1 speech segments:\\nSpeech segment 0: start = 1000.00, end = 4500.00\\n');`,
+    );
+    const ffmpegPath = await executable(
+      directory,
+      'pause-ffmpeg',
+      `const args = process.argv.slice(2);
+if (args.includes('silencedetect=noise=-50dB:d=0.5')) {
+  process.stderr.write('[silencedetect] silence_end: 45 | silence_duration: 45\\n');
+  process.stdout.write('out_time_us=45000000\\n');
+} else if (args.includes('-af')) {
+  process.stderr.write('[silencedetect] silence_end: 28.1 | silence_duration: 0.2\\n');
+} else {
+  require('node:fs').writeFileSync(args.at(-1), 'wav');
+}`,
+    );
+    const whisperPath = await executable(
+      directory,
+      'overlap-whisper',
+      `const args = process.argv.slice(2);
+for (let i = 0; i < args.length; i++) if (args[i] === '-of') {
+  const time = args[i + 1].endsWith('speech-0')
+    ? '00:00:17,800 --> 00:00:18,250'
+    : '00:00:00,100 --> 00:00:00,650';
+  require('node:fs').writeFileSync(args[i + 1] + '.srt', '1\\n' + time + '\\nはい\\n');
+}`,
+    );
+    const output = await generateJapaneseSubtitles({
+      ...input,
+      config: { ...input.config, vadModelPath, vadPath, ffmpegPath, whisperPath },
+    });
+    assert.equal(await readFile(output, 'utf8'), '1\n00:00:30,300 --> 00:00:30,900\nはい\n');
+  }));
+
+test('silent audio with no detected speech stops generation without transcription', () =>
+  fixture(async (directory) => {
+    const input = await generationFixture(directory);
+    const vadModelPath = path.join(directory, 'vad.bin');
+    await writeFile(vadModelPath, 'speech detector model');
+    const vadPath = await executable(
+      directory,
+      'vad',
+      "process.stdout.write('Detected 0 speech segments:\\n');",
+    );
+    await assert.rejects(
+      generateJapaneseSubtitles({ ...input, config: { ...input.config, vadModelPath, vadPath } }),
+      /No spoken dialogue detected/,
+    );
+    assert.equal((await readFile(input.callsPath, 'utf8')).trim().split('\n').length, 3);
+    assert.deepEqual(
+      (await readdir(directory)).filter((file) => file.endsWith('.srt')),
+      [],
+    );
+  }));
+
+test('dialogue generation retains audible audio rejected by VAD', () =>
+  fixture(async (directory) => {
+    const input = await generationFixture(directory);
+    const vadModelPath = path.join(directory, 'vad.bin');
+    await writeFile(vadModelPath, 'speech detector model');
+    const vadPath = await executable(
+      directory,
+      'vad',
+      "process.stdout.write('Detected 0 speech segments:\\n');",
+    );
+    const ffmpegPath = await executable(
+      directory,
+      'audible-ffmpeg',
+      `
+const args = process.argv.slice(2);
+if (args.at(-1) === '-') {
+  process.stdout.write('out_time_us=19000000\\nprogress=end\\n');
+} else {
+  require('node:fs').writeFileSync(args.at(-1), 'wav');
+}`,
+    );
+    const output = await generateJapaneseSubtitles({
+      ...input,
+      config: { ...input.config, vadModelPath, vadPath, ffmpegPath },
+    });
+    assert.match(await readFile(output, 'utf8'), /00:00:03,500 --> 00:00:04,500\nこんにちは/);
+  }));
+
+test('empty executable paths find tools on PATH and explicit overrides take precedence', () =>
+  fixture(async (directory) => {
+    const input = await generationFixture(directory);
+    const previousPath = process.env.PATH;
+    process.env.PATH = directory;
+    try {
+      const config = {
+        ...DEFAULT_SUBTITLE_GENERATION_CONFIG,
+        modelPath: input.config.modelPath,
+      };
+      const result = await generateJapaneseSubtitles({ ...input, config });
+      assert.match(await readFile(result, 'utf8'), /こんにちは/);
+      await assert.rejects(
+        generateJapaneseSubtitles({
+          ...input,
+          config: { ...config, ffprobePath: path.join(directory, 'missing-override') },
+        }),
+        /missing-override \(subtitleGeneration\.ffprobePath\) is not an executable file/,
+      );
+    } finally {
+      if (previousPath === undefined) delete process.env.PATH;
+      else process.env.PATH = previousPath;
+    }
+  }));
+
+test('generation rejects remote media, missing models, and missing tools before starting a subprocess', () =>
+  fixture(async (directory) => {
+    const input = await generationFixture(directory);
+    await assert.rejects(
+      generateJapaneseSubtitles({ ...input, mediaPath: 'https://example.com/movie.mkv' }),
+      /local media file/,
+    );
+    await assert.rejects(
+      generateJapaneseSubtitles({ ...input, config: { ...input.config, modelPath: '' } }),
+      /No Whisper model found/,
+    );
+    await assert.rejects(
+      generateJapaneseSubtitles({
+        ...input,
+        config: {
+          ...input.config,
+          vadModelPath: path.join(directory, 'vad.bin'),
+          vadPath: path.join(directory, 'missing-detector'),
+        },
+      }),
+      /missing-detector \(subtitleGeneration\.vadPath\) is not an executable file/,
+    );
+    await assert.rejects(readFile(input.callsPath), /ENOENT/);
+  }));
+
+test(
+  'directory permission preflight rejects a write-only destination',
+  {
+    skip: process.platform === 'win32' || process.getuid?.() === 0,
+  },
+  () =>
+    fixture(async (directory) => {
+      const writeOnly = path.join(directory, 'write-only');
+      await mkdir(writeOnly);
+      try {
+        await chmod(writeOnly, 0o200);
+        await access(writeOnly, constants.W_OK);
+        await assert.rejects(ensureWritableDirectory(writeOnly), /write-only is not writable/);
+      } finally {
+        await chmod(writeOnly, 0o755);
+      }
+    }),
+);
+
+test(
+  'generation rejects an unwritable destination before extracting audio',
+  {
+    skip: process.platform === 'win32' || process.getuid?.() === 0,
+  },
+  () =>
+    fixture(async (directory) => {
+      const input = await generationFixture(directory);
+      const readOnly = path.join(directory, 'read-only');
+      await mkdir(readOnly, { mode: 0o555 });
+      try {
+        await assert.rejects(
+          generateJapaneseSubtitles({ ...input, outputPath: path.join(readOnly, 'out.srt') }),
+          /read-only is not writable/,
+        );
+        await assert.rejects(readFile(input.callsPath), /ENOENT/);
+      } finally {
+        await chmod(readOnly, 0o755);
+      }
+    }),
+);
+
+test('process cancellation terminates work and bounds diagnostic output', () =>
+  fixture(async (directory) => {
+    const slow = await executable(
+      directory,
+      'slow',
+      "process.stdout.write('ready\\n');setInterval(()=>{},1000);",
+    );
+    const controller = new AbortController();
+    await assert.rejects(
+      runSubtitleGenerationProcess({
+        command: slow,
+        args: [],
+        signal: controller.signal,
+        onLine: () => controller.abort(),
+      }),
+      /cancelled/,
+    );
+    const failed = await executable(
+      directory,
+      'failed',
+      "process.stderr.write('x'.repeat(100000));process.exitCode=7;",
+    );
+    await assert.rejects(
+      runSubtitleGenerationProcess({ command: failed, args: [] }),
+      (error: unknown) =>
+        error instanceof Error &&
+        error.message.length < 66000 &&
+        error.message.includes('status 7'),
+    );
+  }));
+
+test('download uses the pinned model revision and removes files that fail integrity', () =>
+  fixture(async (directory) => {
+    const originalFetch = globalThis.fetch;
+    globalThis.fetch = Object.assign(async (request: string | URL | Request) => {
+      assert.equal(
+        request,
+        'https://huggingface.co/ggerganov/whisper.cpp/resolve/5359861c739e955e79d9a303bcbc70fb988958b1/ggml-small.bin',
+      );
+      return new Response('not a model');
+    }, originalFetch);
+    try {
+      await assert.rejects(
+        downloadSubtitleGenerationModel({
+          config: DEFAULT_SUBTITLE_GENERATION_CONFIG,
+          modelDirectory: directory,
+        }),
+        /integrity verification/,
+      );
+      assert.deepEqual(await readdir(directory), []);
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  }));
diff --git a/src/core/services/subtitle-generation.ts b/src/core/services/subtitle-generation.ts
new file mode 100644
index 00000000..00ca08c5
--- /dev/null
+++ b/src/core/services/subtitle-generation.ts
@@ -0,0 +1,330 @@
+import { access, mkdtemp, readFile, rm, stat, writeFile } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import type {
+  SubtitleGenerationConfig,
+  SubtitleGenerationProgress,
+} from '../../shared/subtitle-generation';
+import { isMissingFile, resolveSubtitleGenerationModel } from './subtitle-generation-models';
+import { runSubtitleGenerationProcess } from './subtitle-generation-process';
+import { publishSubtitleGenerationFile } from './subtitle-generation-files';
+import { formatTimestamp } from './subtitle-generation-srt';
+import { transcribeSubtitleDialogue } from './subtitle-generation-dialogue';
+import {
+  loadSubtitleGenerationReference,
+  type SubtitleGenerationReference,
+} from './subtitle-generation-reference';
+import {
+  requireSubtitleGenerationTools,
+  resolveSubtitleGenerationTools,
+} from './subtitle-generation-tools';
+
+export {
+  downloadSubtitleGenerationModel,
+  resolveSubtitleGenerationModel,
+} from './subtitle-generation-models';
+export { resolveSubtitleGenerationTools } from './subtitle-generation-tools';
+
+function numericTime(value: unknown): number | undefined {
+  if (typeof value !== 'number' && typeof value !== 'string') return undefined;
+  const number = Number(value);
+  return Number.isFinite(number) ? number : undefined;
+}
+
+function parseAudioProbe(raw: string, selectedIndex: number | undefined) {
+  const value: unknown = JSON.parse(raw);
+  if (
+    typeof value !== 'object' ||
+    value === null ||
+    !('streams' in value) ||
+    !Array.isArray(value.streams)
+  ) {
+    throw new Error('ffprobe did not return media streams.');
+  }
+  const streams = value.streams.flatMap((stream: unknown) => {
+    if (
+      typeof stream !== 'object' ||
+      stream === null ||
+      !('codec_type' in stream) ||
+      stream.codec_type !== 'audio' ||
+      !('index' in stream) ||
+      typeof stream.index !== 'number' ||
+      !Number.isInteger(stream.index) ||
+      stream.index < 0
+    )
+      return [];
+    const tags = 'tags' in stream ? stream.tags : undefined;
+    const language =
+      typeof tags === 'object' && tags !== null && 'language' in tags ? tags.language : undefined;
+    return [
+      {
+        index: stream.index,
+        start: 'start_time' in stream ? numericTime(stream.start_time) : undefined,
+        duration: 'duration' in stream ? numericTime(stream.duration) : undefined,
+        japanese: language === 'ja' || language === 'jpn',
+      },
+    ];
+  });
+  const selected =
+    selectedIndex === undefined
+      ? (streams.find((stream) => stream.japanese) ?? streams[0])
+      : streams.find((stream) => stream.index === selectedIndex);
+  if (!selected)
+    throw new Error(
+      selectedIndex === undefined
+        ? 'No audio track found.'
+        : `Audio stream ${selectedIndex} was not found.`,
+    );
+  const format = 'format' in value ? value.format : undefined;
+  const formatStart =
+    typeof format === 'object' && format !== null && 'start_time' in format
+      ? (numericTime(format.start_time) ?? 0)
+      : 0;
+  const duration =
+    selected.duration ??
+    (typeof format === 'object' && format !== null && 'duration' in format
+      ? numericTime(format.duration)
+      : undefined);
+  // mpv rebases media timestamps to the container start. Extraction rebases the selected audio.
+  return { index: selected.index, offset: (selected.start ?? formatStart) - formatStart, duration };
+}
+
+function shiftSubtitleTimestamps(srt: string, offsetSeconds: number): string {
+  let cueCount = 0;
+  const result = srt.replace(
+    /(\d{2,}):(\d{2}):(\d{2}),(\d{3}) --> (\d{2,}):(\d{2}):(\d{2}),(\d{3})/g,
+    (
+      _match,
+      sh: string,
+      sm: string,
+      ss: string,
+      sms: string,
+      eh: string,
+      em: string,
+      es: string,
+      ems: string,
+    ) => {
+      cueCount += 1;
+      const start = Number(sh) * 3600000 + Number(sm) * 60000 + Number(ss) * 1000 + Number(sms);
+      const end = Number(eh) * 3600000 + Number(em) * 60000 + Number(es) * 1000 + Number(ems);
+      return `${formatTimestamp(start + offsetSeconds * 1000)} --> ${formatTimestamp(end + offsetSeconds * 1000)}`;
+    },
+  );
+  if (cueCount === 0)
+    throw new Error(
+      'Whisper produced no subtitle cues. The audio may contain no recognized speech.',
+    );
+  return result;
+}
+
+async function ensureAvailableOutput(outputPath: string): Promise<void> {
+  try {
+    await stat(outputPath);
+  } catch (error) {
+    if (isMissingFile(error)) return;
+    throw error;
+  }
+  throw new Error(`Subtitle output already exists: ${outputPath}`);
+}
+
+// Fail before extraction and transcription when the destination cannot take the file.
+export async function ensureWritableDirectory(directory: string): Promise<void> {
+  try {
+    await access(directory, constants.W_OK | constants.X_OK);
+  } catch {
+    throw new Error(`Cannot save subtitles: ${directory} is not writable.`);
+  }
+}
+
+async function writeSubtitles(input: {
+  mediaPath: string;
+  outputPath?: string;
+  contents: string;
+  signal?: AbortSignal;
+}): Promise<string> {
+  const parsed = path.parse(input.mediaPath);
+  const directory = input.outputPath ? path.dirname(path.resolve(input.outputPath)) : parsed.dir;
+  const temporaryDirectory = await mkdtemp(path.join(directory, '.subminer-subtitles-'));
+  try {
+    const staged = path.join(temporaryDirectory, 'subtitles.srt');
+    await writeFile(staged, input.contents, { flag: 'wx' });
+    for (let suffix = 0; ; suffix += 1) {
+      input.signal?.throwIfAborted();
+      const destination = input.outputPath
+        ? path.resolve(input.outputPath)
+        : path.join(directory, `${parsed.name}.ja.generated${suffix ? `.${suffix}` : ''}.srt`);
+      try {
+        await publishSubtitleGenerationFile(staged, destination);
+        return destination;
+      } catch (error) {
+        if (
+          !input.outputPath &&
+          error instanceof Error &&
+          'code' in error &&
+          error.code === 'EEXIST'
+        )
+          continue;
+        throw error;
+      }
+    }
+  } finally {
+    await rm(temporaryDirectory, { recursive: true, force: true });
+  }
+}
+
+export async function generateJapaneseSubtitles(input: {
+  config: SubtitleGenerationConfig;
+  modelDirectory: string;
+  mediaPath: string;
+  audioStreamIndex?: number;
+  references?: readonly SubtitleGenerationReference[];
+  outputPath?: string;
+  onProgress?: (progress: SubtitleGenerationProgress) => void;
+  signal?: AbortSignal;
+}): Promise<string> {
+  input.signal?.throwIfAborted();
+  if (/^[a-z][a-z\d+.-]*:\/\//i.test(input.mediaPath))
+    throw new Error('Subtitle generation requires a local media file.');
+  const mediaPath = path.resolve(input.mediaPath);
+  if (!(await stat(mediaPath)).isFile())
+    throw new Error('Subtitle generation requires a local media file.');
+  if (input.outputPath) await ensureAvailableOutput(path.resolve(input.outputPath));
+  await ensureWritableDirectory(
+    input.outputPath ? path.dirname(path.resolve(input.outputPath)) : path.dirname(mediaPath),
+  );
+  const model = await resolveSubtitleGenerationModel(input.config, input.modelDirectory);
+  if (model.kind === 'missing')
+    throw new Error(
+      'No Whisper model found. Download a model or configure an existing model path.',
+    );
+  if (model.kind === 'invalid') throw new Error(model.message);
+  const tools = requireSubtitleGenerationTools(await resolveSubtitleGenerationTools(input.config));
+  input.onProgress?.({ stage: 'extract', message: 'Inspecting audio tracks...' });
+  const probe = await runSubtitleGenerationProcess({
+    command: tools.ffprobe,
+    args: [
+      '-v',
+      'error',
+      '-show_entries',
+      'stream=index,codec_type,start_time,duration:stream_tags=language:format=start_time,duration',
+      '-of',
+      'json',
+      mediaPath,
+    ],
+    signal: input.signal,
+  });
+  const audio = parseAudioProbe(probe, input.audioStreamIndex);
+  const temporaryDirectory = await mkdtemp(path.join(tmpdir(), 'subminer-whisper-'));
+  try {
+    const wavPath = path.join(temporaryDirectory, 'audio.wav');
+    const subtitleBase = path.join(temporaryDirectory, 'subtitles');
+    input.onProgress?.({ stage: 'extract', percent: 0, message: 'Extracting audio...' });
+    await runSubtitleGenerationProcess({
+      command: tools.ffmpeg,
+      args: [
+        '-nostdin',
+        '-hide_banner',
+        '-loglevel',
+        'error',
+        '-i',
+        mediaPath,
+        '-map',
+        `0:${audio.index}`,
+        '-vn',
+        '-af',
+        'asetpts=PTS-STARTPTS',
+        '-ac',
+        '1',
+        '-ar',
+        '16000',
+        '-c:a',
+        'pcm_s16le',
+        '-progress',
+        'pipe:1',
+        '-nostats',
+        wavPath,
+      ],
+      signal: input.signal,
+      onLine: (line) => {
+        const match = /^out_time_us=(\d+)$/.exec(line);
+        if (match && audio.duration && audio.duration > 0) {
+          input.onProgress?.({
+            stage: 'extract',
+            percent: Math.min(100, Math.floor(Number(match[1]) / 10000 / audio.duration)),
+            message: 'Extracting audio...',
+          });
+        }
+      },
+    });
+    input.onProgress?.({
+      stage: 'transcribe',
+      percent: 0,
+      message: 'Generating Japanese subtitles...',
+    });
+    const referenceStarts = await loadSubtitleGenerationReference({
+      references: input.references ?? [],
+      mediaPath,
+      ffmpegPath: tools.ffmpeg,
+      directory: temporaryDirectory,
+      audioOffset: audio.offset,
+      onProgress: input.onProgress,
+      signal: input.signal,
+    });
+    let srt: string;
+    if (tools.vad !== null || referenceStarts.length > 0) {
+      srt = await transcribeSubtitleDialogue({
+        config: input.config,
+        tools,
+        referenceStarts,
+        modelPath: model.path,
+        wavPath,
+        directory: temporaryDirectory,
+        signal: input.signal,
+        onProgress: input.onProgress,
+      });
+    } else {
+      await runSubtitleGenerationProcess({
+        command: tools.whisper,
+        args: [
+          '-m',
+          model.path,
+          '-f',
+          wavPath,
+          '-l',
+          'ja',
+          '-t',
+          String(input.config.threads),
+          '-osrt',
+          '-of',
+          subtitleBase,
+          '-pp',
+        ],
+        signal: input.signal,
+        onLine: (line) => {
+          const match = /progress\s*=\s*(\d+(?:\.\d+)?)%/.exec(line);
+          if (match)
+            input.onProgress?.({
+              stage: 'transcribe',
+              percent: Math.min(100, Number(match[1])),
+              message: 'Generating Japanese subtitles...',
+            });
+        },
+      });
+      srt = await readFile(`${subtitleBase}.srt`, 'utf8');
+    }
+    input.signal?.throwIfAborted();
+    input.onProgress?.({ stage: 'write', message: 'Saving Japanese subtitles...' });
+    const contents = shiftSubtitleTimestamps(srt, audio.offset);
+    const outputPath = await writeSubtitles({
+      mediaPath,
+      outputPath: input.outputPath,
+      contents,
+      signal: input.signal,
+    });
+    input.onProgress?.({ stage: 'write', percent: 100, message: 'Japanese subtitles are ready.' });
+    return outputPath;
+  } finally {
+    await rm(temporaryDirectory, { recursive: true, force: true });
+  }
+}
diff --git a/src/core/services/subtitle-processing-controller.ts b/src/core/services/subtitle-processing-controller.ts
index 3097e1e2..d03d8c88 100644
--- a/src/core/services/subtitle-processing-controller.ts
+++ b/src/core/services/subtitle-processing-controller.ts
@@ -134,7 +134,7 @@ export function createSubtitleProcessingController(
         try {
           const cachedTokenized = getCachedTokenization(text);
           if (cachedTokenized) {
-            output = cachedTokenized;
+            output = { ...cachedTokenized, text };
           } else {
             // Cache miss: show the plain line on time; the tokenized payload
             // upgrades it once ready. Skipped on refreshes of an already
@@ -266,7 +266,7 @@ export function createSubtitleProcessingController(
       lastEmittedText = text;
       lastEmittedGeneration = cacheGeneration;
       lastPlainEmittedText = null;
-      return cached;
+      return { ...cached, text };
     },
     hasCachedSubtitle: (text: string) => {
       const cacheKey = normalizeSubtitleCacheKey(text);
diff --git a/src/core/services/subtitle-timing-offset.test.ts b/src/core/services/subtitle-timing-offset.test.ts
deleted file mode 100644
index 15cad6e6..00000000
--- a/src/core/services/subtitle-timing-offset.test.ts
+++ /dev/null
@@ -1,73 +0,0 @@
-import assert from 'node:assert/strict';
-import test from 'node:test';
-import { estimateSubtitleTimingOffset } from './subtitle-timing-offset';
-
-function cue(startTime: number) {
-  return { startTime, endTime: startTime + 1, text: `cue ${startTime}` };
-}
-
-test('estimate subtitle timing offset detects a late Jellyfin subtitle timeline', () => {
-  const primary = [
-    34.935, 36.937, 41.441, 45.279, 48.115, 52.286, 54.955, 59.793, 63.63, 67.634, 76.643, 80.814,
-    87.988, 90.991, 94.094, 97.097,
-  ].map(cue);
-  const reference = [
-    3.46, 9.48, 13.61, 21.4, 28.16, 32.06, 35.93, 45.1, 56.57, 59.68, 62.44, 65.56,
-  ].map(cue);
-
-  const result = estimateSubtitleTimingOffset(primary, reference);
-
-  assert.ok(result);
-  assert.ok(result.offsetSeconds > -32);
-  assert.ok(result.offsetSeconds < -31);
-  assert.ok(result.matchCount >= 8);
-  assert.ok(result.meanErrorSeconds <= 0.75);
-});
-
-test('estimate subtitle timing offset favors the early episode timeline', () => {
-  const primary = [
-    34.935, 36.937, 41.441, 45.279, 48.115, 52.286, 54.955, 59.793, 63.63, 67.634, 76.643, 80.814,
-    87.988, 90.991, 94.094, 97.097, 207.974, 212.579, 222.422, 228.095, 232.432, 238.271, 244.778,
-    246.78, 249.282, 251.284, 253.62, 256.289, 259.626, 262.129, 264.965, 267.634, 270.303, 274.407,
-    277.077, 280.08, 284.084, 288.421, 291.925, 295.262, 298.431, 301.101, 306.773, 308.942,
-    312.946, 316.283, 321.621, 326.626, 331.131, 336.069, 340.407, 343.41, 351.418, 355.422,
-    357.924, 362.429, 365.432, 370.604, 373.273, 377.944, 381.114, 384.618, 387.621, 390.957,
-    396.73, 399.232, 401.568, 403.57, 405.572, 407.574, 409.743, 412.746, 418.752, 425.258, 427.26,
-    435.602, 440.44, 442.942, 445.445, 449.783,
-  ].map(cue);
-  const reference = [
-    3.46, 9.48, 13.61, 21.4, 28.16, 32.06, 35.93, 45.1, 56.57, 59.68, 62.44, 65.56, 165.77, 172.81,
-    176.1, 177.27, 186.33, 191.33, 195.78, 201.83, 212.9, 214.09, 216.73, 220.2, 222.91, 225.65,
-    232.8, 237.92, 242.23, 243.28, 247.53, 252.04, 255.9, 258.86, 262.09, 264.43, 276.07, 278.01,
-    280.98, 285.67, 289.89, 294.57, 300, 303.56, 308.58, 316.37, 318.38, 319.86, 325.38, 328.82,
-    333.68, 335.26, 336.82, 340.11, 342.11, 344.36, 346.39, 347.53, 350.92, 370.18, 372.88, 376.43,
-    388.2, 390.57, 403.96, 406.36, 409.72, 413.78, 425.55, 432.76, 435.03, 438.06, 443.73, 448.31,
-    450.57, 457.62, 463.41, 465.85, 473.79, 480.59,
-  ].map(cue);
-
-  const result = estimateSubtitleTimingOffset(primary, reference);
-
-  assert.ok(result);
-  assert.ok(result.offsetSeconds > -32);
-  assert.ok(result.offsetSeconds < -31);
-});
-
-test('estimate subtitle timing offset ignores subtitle timelines that are already aligned', () => {
-  const starts = [1, 5, 9, 14, 20, 25, 31, 38];
-
-  const result = estimateSubtitleTimingOffset(
-    starts.map(cue),
-    starts.map((start) => cue(start + 0.04)),
-  );
-
-  assert.equal(result, null);
-});
-
-test('estimate subtitle timing offset rejects weak timeline matches', () => {
-  const primary = [10, 20, 30, 40, 50, 60, 70, 80].map(cue);
-  const reference = [1, 2, 3, 4, 5, 6, 7, 8].map(cue);
-
-  const result = estimateSubtitleTimingOffset(primary, reference);
-
-  assert.equal(result, null);
-});
diff --git a/src/core/services/subtitle-timing-offset.ts b/src/core/services/subtitle-timing-offset.ts
deleted file mode 100644
index e52ec79d..00000000
--- a/src/core/services/subtitle-timing-offset.ts
+++ /dev/null
@@ -1,153 +0,0 @@
-import type { SubtitleCue } from './subtitle-cue-parser';
-
-export type SubtitleTimingOffsetResult = {
-  offsetSeconds: number;
-  matchCount: number;
-  meanErrorSeconds: number;
-  maxErrorSeconds: number;
-};
-
-export type SubtitleTimingOffsetOptions = {
-  maxCueCount?: number;
-  maxOffsetSeconds?: number;
-  matchThresholdSeconds?: number;
-  maxMeanErrorSeconds?: number;
-  minMatchCount?: number;
-  minMatchRatio?: number;
-  minUsefulOffsetSeconds?: number;
-};
-
-type OffsetScore = SubtitleTimingOffsetResult;
-
-const DEFAULT_MAX_CUE_COUNT = 60;
-const DEFAULT_MAX_OFFSET_SECONDS = 180;
-const DEFAULT_MATCH_THRESHOLD_SECONDS = 1;
-const DEFAULT_MAX_MEAN_ERROR_SECONDS = 0.75;
-const DEFAULT_MIN_MATCH_COUNT = 8;
-const DEFAULT_MIN_MATCH_RATIO = 0.25;
-const DEFAULT_MIN_USEFUL_OFFSET_SECONDS = 0.25;
-
-function normalizeCueStarts(cues: SubtitleCue[], maxCueCount: number): number[] {
-  const starts = cues
-    .map((cue) => cue.startTime)
-    .filter((start) => Number.isFinite(start) && start >= 0)
-    .sort((a, b) => a - b);
-  const deduped: number[] = [];
-  for (const start of starts) {
-    const previous = deduped[deduped.length - 1];
-    if (previous === undefined || Math.abs(start - previous) > 0.05) {
-      deduped.push(start);
-    }
-    if (deduped.length >= maxCueCount) {
-      break;
-    }
-  }
-  return deduped;
-}
-
-function roundToMillis(value: number): number {
-  return Math.round(value * 1000) / 1000;
-}
-
-function scoreOffset(
-  primaryStarts: number[],
-  referenceStarts: number[],
-  offsetSeconds: number,
-  matchThresholdSeconds: number,
-): OffsetScore {
-  let primaryIndex = 0;
-  let referenceIndex = 0;
-  let matchCount = 0;
-  let totalErrorSeconds = 0;
-  let maxErrorSeconds = 0;
-
-  while (primaryIndex < primaryStarts.length && referenceIndex < referenceStarts.length) {
-    const shiftedPrimary = primaryStarts[primaryIndex]! + offsetSeconds;
-    const reference = referenceStarts[referenceIndex]!;
-    const errorSeconds = Math.abs(shiftedPrimary - reference);
-    if (errorSeconds <= matchThresholdSeconds) {
-      matchCount += 1;
-      totalErrorSeconds += errorSeconds;
-      maxErrorSeconds = Math.max(maxErrorSeconds, errorSeconds);
-      primaryIndex += 1;
-      referenceIndex += 1;
-      continue;
-    }
-
-    if (shiftedPrimary < reference) {
-      primaryIndex += 1;
-    } else {
-      referenceIndex += 1;
-    }
-  }
-
-  return {
-    offsetSeconds,
-    matchCount,
-    meanErrorSeconds: matchCount > 0 ? totalErrorSeconds / matchCount : Number.POSITIVE_INFINITY,
-    maxErrorSeconds,
-  };
-}
-
-function isBetterScore(next: OffsetScore, current: OffsetScore | null): boolean {
-  if (current === null) return true;
-  if (next.matchCount !== current.matchCount) return next.matchCount > current.matchCount;
-  if (next.meanErrorSeconds !== current.meanErrorSeconds) {
-    return next.meanErrorSeconds < current.meanErrorSeconds;
-  }
-  return Math.abs(next.offsetSeconds) < Math.abs(current.offsetSeconds);
-}
-
-export function estimateSubtitleTimingOffset(
-  primaryCues: SubtitleCue[],
-  referenceCues: SubtitleCue[],
-  options: SubtitleTimingOffsetOptions = {},
-): SubtitleTimingOffsetResult | null {
-  const maxCueCount = options.maxCueCount ?? DEFAULT_MAX_CUE_COUNT;
-  const maxOffsetSeconds = options.maxOffsetSeconds ?? DEFAULT_MAX_OFFSET_SECONDS;
-  const matchThresholdSeconds = options.matchThresholdSeconds ?? DEFAULT_MATCH_THRESHOLD_SECONDS;
-  const maxMeanErrorSeconds = options.maxMeanErrorSeconds ?? DEFAULT_MAX_MEAN_ERROR_SECONDS;
-  const minMatchCount = options.minMatchCount ?? DEFAULT_MIN_MATCH_COUNT;
-  const minMatchRatio = options.minMatchRatio ?? DEFAULT_MIN_MATCH_RATIO;
-  const minUsefulOffsetSeconds =
-    options.minUsefulOffsetSeconds ?? DEFAULT_MIN_USEFUL_OFFSET_SECONDS;
-
-  const primaryStarts = normalizeCueStarts(primaryCues, maxCueCount);
-  const referenceStarts = normalizeCueStarts(referenceCues, maxCueCount);
-  const comparableCueCount = Math.min(primaryStarts.length, referenceStarts.length);
-  if (comparableCueCount < minMatchCount) {
-    return null;
-  }
-
-  const candidates = new Set<number>();
-  for (const primaryStart of primaryStarts) {
-    for (const referenceStart of referenceStarts) {
-      const offsetSeconds = roundToMillis(referenceStart - primaryStart);
-      if (Math.abs(offsetSeconds) <= maxOffsetSeconds) {
-        candidates.add(offsetSeconds);
-      }
-    }
-  }
-
-  let best: OffsetScore | null = null;
-  for (const offsetSeconds of candidates) {
-    if (Math.abs(offsetSeconds) < minUsefulOffsetSeconds) {
-      continue;
-    }
-    const score = scoreOffset(primaryStarts, referenceStarts, offsetSeconds, matchThresholdSeconds);
-    if (score.matchCount < minMatchCount) {
-      continue;
-    }
-    if (score.matchCount / comparableCueCount < minMatchRatio) {
-      continue;
-    }
-    if (score.meanErrorSeconds > maxMeanErrorSeconds) {
-      continue;
-    }
-    if (isBetterScore(score, best)) {
-      best = score;
-    }
-  }
-
-  return best;
-}
diff --git a/src/core/services/tmdb/bundled-api-key.test.ts b/src/core/services/tmdb/bundled-api-key.test.ts
new file mode 100644
index 00000000..04ce08dd
--- /dev/null
+++ b/src/core/services/tmdb/bundled-api-key.test.ts
@@ -0,0 +1,22 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import test from 'node:test';
+import { BUNDLED_INTEGRATION_KEYS_FILENAME, readBundledTmdbApiKey } from './bundled-api-key.js';
+
+test('readBundledTmdbApiKey reads the staged key and tolerates a missing or malformed file', () => {
+  const distDir = fs.mkdtempSync(path.join(os.tmpdir(), 'subminer-bundled-key-'));
+  const filePath = path.join(distDir, BUNDLED_INTEGRATION_KEYS_FILENAME);
+  try {
+    assert.equal(readBundledTmdbApiKey(distDir), null);
+    fs.writeFileSync(filePath, '{"tmdbApiKey":" abc "}');
+    assert.equal(readBundledTmdbApiKey(distDir), 'abc');
+    fs.writeFileSync(filePath, '{"tmdbApiKey":""}');
+    assert.equal(readBundledTmdbApiKey(distDir), null);
+    fs.writeFileSync(filePath, 'not json');
+    assert.equal(readBundledTmdbApiKey(distDir), null);
+  } finally {
+    fs.rmSync(distDir, { recursive: true, force: true });
+  }
+});
diff --git a/src/core/services/tmdb/bundled-api-key.ts b/src/core/services/tmdb/bundled-api-key.ts
new file mode 100644
index 00000000..4b454183
--- /dev/null
+++ b/src/core/services/tmdb/bundled-api-key.ts
@@ -0,0 +1,20 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Release builds stage a project-owned TMDB key into dist/ (see
+ * scripts/bundled-integration-keys.mjs). Source checkouts and CI builds have no
+ * such file, and TMDB lookups then depend on the user's own `tmdb.apiKey`.
+ */
+export const BUNDLED_INTEGRATION_KEYS_FILENAME = 'bundled-integration-keys.json';
+
+export function readBundledTmdbApiKey(distDir: string): string | null {
+  try {
+    const raw = fs.readFileSync(path.join(distDir, BUNDLED_INTEGRATION_KEYS_FILENAME), 'utf8');
+    const parsed = JSON.parse(raw) as { tmdbApiKey?: unknown };
+    const key = typeof parsed.tmdbApiKey === 'string' ? parsed.tmdbApiKey.trim() : '';
+    return key.length > 0 ? key : null;
+  } catch {
+    return null;
+  }
+}
diff --git a/src/core/services/tmdb/live-action-resolver.test.ts b/src/core/services/tmdb/live-action-resolver.test.ts
new file mode 100644
index 00000000..e92ee484
--- /dev/null
+++ b/src/core/services/tmdb/live-action-resolver.test.ts
@@ -0,0 +1,108 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { createLiveActionMetadataResolver, titlesMatch } from './live-action-resolver.js';
+import {
+  TmdbApiKeyMissingError,
+  type TmdbClient,
+  type TmdbSearchResult,
+  type TmdbTitleDetails,
+} from './tmdb-client.js';
+
+const silentLogger = { info: () => {}, warn: () => {} };
+
+function searchResult(over: Partial<TmdbSearchResult> & { tmdbId: number }): TmdbSearchResult {
+  return {
+    tmdbType: 'tv',
+    title: 'Title',
+    originalTitle: 'Title',
+    originalLanguage: 'ja',
+    overview: null,
+    posterUrl: null,
+    year: null,
+    isAnimation: false,
+    ...over,
+  };
+}
+
+function details(over: Partial<TmdbTitleDetails> & { tmdbId: number }): TmdbTitleDetails {
+  return {
+    tmdbType: 'tv',
+    titleEnglish: null,
+    titleNative: null,
+    description: null,
+    posterUrl: null,
+    episodesTotal: null,
+    year: null,
+    originalLanguage: 'ja',
+    isAnimation: false,
+    allTitles: [],
+    ...over,
+  };
+}
+
+test('titlesMatch ignores case, width, and punctuation but not extra words', () => {
+  assert.equal(titlesMatch('Hanzawa Naoki', ['HANZAWA　NAOKI!']), true);
+  assert.equal(titlesMatch('半沢直樹', ['半沢直樹']), true);
+  assert.equal(titlesMatch('Hanzawa Naoki', ['Hanzawa Naoki Season 2']), false);
+  assert.equal(titlesMatch('', ['']), false);
+});
+
+test('resolveByTitle only accepts a Japanese non-animated result whose known titles match exactly', async () => {
+  const detailCalls: number[] = [];
+  const client: TmdbClient = {
+    async search() {
+      return [
+        searchResult({ tmdbId: 1, title: 'Hanzawa Naoki', originalLanguage: 'ko' }),
+        searchResult({ tmdbId: 2, title: 'Hanzawa Naoki', isAnimation: true }),
+        searchResult({ tmdbId: 3, title: 'Hanzawa Naoki: The Movie' }),
+        searchResult({ tmdbId: 4, title: 'Hanzawa Naoki' }),
+      ];
+    },
+    async getDetails(_type, tmdbId) {
+      detailCalls.push(tmdbId);
+      if (tmdbId === 3) return details({ tmdbId: 3, allTitles: ['Hanzawa Naoki: The Movie'] });
+      if (tmdbId === 4) return details({ tmdbId: 4, allTitles: ['Hanzawa Naoki', '半沢直樹'] });
+      return null;
+    },
+  };
+  const resolver = createLiveActionMetadataResolver(client, silentLogger);
+
+  const resolved = await resolver.resolveByTitle('hanzawa naoki');
+
+  assert.equal(resolved?.tmdbId, 4);
+  assert.deepEqual(detailCalls, [3, 4]);
+});
+
+test('resolveByTitle returns null when nothing matches or the key is missing', async () => {
+  const noMatch: TmdbClient = {
+    async search() {
+      return [searchResult({ tmdbId: 1, title: 'Something Else' })];
+    },
+    async getDetails() {
+      return details({ tmdbId: 1, allTitles: ['Something Else'] });
+    },
+  };
+  assert.equal(
+    await createLiveActionMetadataResolver(noMatch, silentLogger).resolveByTitle('Hanzawa Naoki'),
+    null,
+  );
+
+  let infoCount = 0;
+  const noKey: TmdbClient = {
+    async search() {
+      throw new TmdbApiKeyMissingError();
+    },
+    async getDetails() {
+      throw new TmdbApiKeyMissingError();
+    },
+  };
+  const resolver = createLiveActionMetadataResolver(noKey, {
+    info: () => {
+      infoCount += 1;
+    },
+    warn: () => {},
+  });
+  assert.equal(await resolver.resolveByTitle('Hanzawa Naoki'), null);
+  assert.equal(await resolver.resolveById('tv', 1), null);
+  assert.equal(infoCount, 1);
+});
diff --git a/src/core/services/tmdb/live-action-resolver.ts b/src/core/services/tmdb/live-action-resolver.ts
new file mode 100644
index 00000000..257399b8
--- /dev/null
+++ b/src/core/services/tmdb/live-action-resolver.ts
@@ -0,0 +1,75 @@
+import { normalizeTitleIdentity } from '../../utils/title-normalization';
+import type { TmdbMediaType } from '../../../shared/media-kind';
+import { TmdbApiKeyMissingError, type TmdbClient, type TmdbTitleDetails } from './tmdb-client';
+
+const MAX_DETAIL_LOOKUPS = 3;
+
+/**
+ * Resolves live-action titles for the automatic cover-art path. Anime is
+ * AniList's job, so only non-animated Japanese-language results qualify, and
+ * a candidate must match the parsed title exactly under one of the names TMDB
+ * knows for it. Fuzzy search hits are never trusted on their own: a stray
+ * filename would otherwise pin the wrong show to a library entry.
+ */
+export interface LiveActionMetadataResolver {
+  resolveByTitle(title: string): Promise<TmdbTitleDetails | null>;
+  resolveById(tmdbType: TmdbMediaType, tmdbId: number): Promise<TmdbTitleDetails | null>;
+}
+
+interface Logger {
+  info(msg: string, ...args: unknown[]): void;
+  warn(msg: string, ...args: unknown[]): void;
+}
+
+export function titlesMatch(candidate: string, knownTitles: Iterable<string>): boolean {
+  const key = normalizeTitleIdentity(candidate);
+  if (!key) return false;
+  for (const known of knownTitles) {
+    if (normalizeTitleIdentity(known) === key) return true;
+  }
+  return false;
+}
+
+export function createLiveActionMetadataResolver(
+  client: TmdbClient,
+  logger: Logger,
+): LiveActionMetadataResolver {
+  let warnedMissingKey = false;
+
+  const guard = async <T>(work: () => Promise<T>): Promise<T | null> => {
+    try {
+      return await work();
+    } catch (err) {
+      if (err instanceof TmdbApiKeyMissingError) {
+        if (!warnedMissingKey) {
+          warnedMissingKey = true;
+          logger.info('tmdb: no API key configured, skipping live-action metadata lookups');
+        }
+        return null;
+      }
+      logger.warn('tmdb: lookup failed: %s', err instanceof Error ? err.message : String(err));
+      return null;
+    }
+  };
+
+  return {
+    resolveByTitle(title) {
+      return guard(async () => {
+        const results = await client.search(title);
+        const candidates = results
+          .filter((result) => result.originalLanguage === 'ja' && !result.isAnimation)
+          .slice(0, MAX_DETAIL_LOOKUPS);
+        for (const candidate of candidates) {
+          const details = await client.getDetails(candidate.tmdbType, candidate.tmdbId);
+          if (details && !details.isAnimation && titlesMatch(title, details.allTitles)) {
+            return details;
+          }
+        }
+        return null;
+      });
+    },
+    resolveById(tmdbType, tmdbId) {
+      return guard(() => client.getDetails(tmdbType, tmdbId));
+    },
+  };
+}
diff --git a/src/core/services/tmdb/tmdb-client.test.ts b/src/core/services/tmdb/tmdb-client.test.ts
new file mode 100644
index 00000000..22c5a123
--- /dev/null
+++ b/src/core/services/tmdb/tmdb-client.test.ts
@@ -0,0 +1,335 @@
+import assert from 'node:assert/strict';
+import test, { type TestContext } from 'node:test';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import type { TmdbConfig } from '../../../types/integrations';
+import {
+  TmdbApiKeyMissingError,
+  createTmdbClient,
+  createTmdbApiKeyResolver,
+  resolveTmdbApiKey,
+} from './tmdb-client.js';
+
+function commandFixture(t: TestContext) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'subminer tmdb command-'));
+  t.after(() => fs.rmSync(dir, { recursive: true, force: true }));
+  let nextId = 0;
+  const quotePath = (value: string) =>
+    `"${process.platform === 'win32' ? value : value.replace(/["\\$`]/g, '\\$&')}"`;
+  return {
+    dir,
+    command(source: string): string {
+      const script = path.join(dir, `credential-${nextId++}.cjs`);
+      fs.writeFileSync(script, source);
+      return `${quotePath(process.execPath)} ${quotePath(script)}`;
+    },
+  };
+}
+
+function jsonResponse(payload: unknown, status = 200): Response {
+  return new Response(JSON.stringify(payload), {
+    status,
+    headers: { 'content-type': 'application/json' },
+  });
+}
+
+function captureFetch(handler: (url: URL, init?: RequestInit) => Response) {
+  const calls: Array<{ url: URL; init?: RequestInit }> = [];
+  const fetchImpl = (async (input: RequestInfo | URL, init?: RequestInit) => {
+    const url = new URL(String(input));
+    calls.push({ url, init });
+    return handler(url, init);
+  }) as typeof fetch;
+  return { calls, fetchImpl };
+}
+
+test('resolveTmdbApiKey prefers the literal key and trims it', async (t) => {
+  const { command } = commandFixture(t);
+  assert.equal(
+    await resolveTmdbApiKey({ apiKey: '  abc  ', apiKeyCommand: command('process.exit(3)') }),
+    'abc',
+  );
+  assert.equal(await resolveTmdbApiKey({ apiKey: '', apiKeyCommand: '' }), null);
+  assert.equal(await resolveTmdbApiKey(undefined), null);
+});
+
+test('resolveTmdbApiKey runs apiKeyCommand when no literal key is set', async (t) => {
+  const { command } = commandFixture(t);
+  assert.equal(
+    await resolveTmdbApiKey({ apiKeyCommand: command('process.stdout.write(" from-cmd ")') }),
+    'from-cmd',
+  );
+  assert.equal(await resolveTmdbApiKey({ apiKeyCommand: command('process.exit(3)') }), null);
+});
+
+test('resolveTmdbApiKey falls back to the bundled key only when the user set nothing usable', async (t) => {
+  const { command } = commandFixture(t);
+  assert.equal(await resolveTmdbApiKey({}, 'bundled'), 'bundled');
+  assert.equal(await resolveTmdbApiKey({ apiKey: 'mine' }, 'bundled'), 'mine');
+  assert.equal(
+    await resolveTmdbApiKey({ apiKeyCommand: command('process.stdout.write("mine")') }, 'bundled'),
+    'mine',
+  );
+  assert.equal(
+    await resolveTmdbApiKey({ apiKeyCommand: command('process.exit(3)') }, 'bundled'),
+    'bundled',
+  );
+});
+
+test('search rejects without a key and never touches the network', async () => {
+  const { calls, fetchImpl } = captureFetch(() => jsonResponse({ results: [] }));
+  const client = createTmdbClient({ resolveApiKey: async () => null, fetch: fetchImpl });
+  await assert.rejects(client.search('半沢直樹'), TmdbApiKeyMissingError);
+  assert.equal(calls.length, 0);
+});
+
+test('search sends a v3 key as a query parameter and drops people from multi results', async () => {
+  const { calls, fetchImpl } = captureFetch(() =>
+    jsonResponse({
+      results: [
+        { media_type: 'person', id: 1, name: 'Sakai Masato' },
+        {
+          media_type: 'tv',
+          id: 61222,
+          name: 'Hanzawa Naoki',
+          original_name: '半沢直樹',
+          original_language: 'ja',
+          overview: 'A banker fights back.',
+          poster_path: '/hanzawa.jpg',
+          first_air_date: '2013-07-07',
+          genre_ids: [18],
+        },
+        {
+          media_type: 'movie',
+          id: 9,
+          title: 'Anime Film',
+          original_title: 'アニメ映画',
+          original_language: 'ja',
+          release_date: '2020-01-01',
+          genre_ids: [16],
+        },
+      ],
+    }),
+  );
+  const client = createTmdbClient({ resolveApiKey: async () => 'v3key', fetch: fetchImpl });
+
+  const results = await client.search(' 半沢直樹 ');
+
+  assert.equal(calls.length, 1);
+  const url = calls[0]!.url;
+  assert.equal(url.pathname, '/3/search/multi');
+  assert.equal(url.searchParams.get('query'), '半沢直樹');
+  assert.equal(url.searchParams.get('api_key'), 'v3key');
+  assert.equal((calls[0]!.init?.headers as Record<string, string>).Authorization, undefined);
+  assert.deepEqual(results, [
+    {
+      tmdbId: 61222,
+      tmdbType: 'tv',
+      title: 'Hanzawa Naoki',
+      originalTitle: '半沢直樹',
+      originalLanguage: 'ja',
+      overview: 'A banker fights back.',
+      posterUrl: 'https://image.tmdb.org/t/p/w500/hanzawa.jpg',
+      year: 2013,
+      isAnimation: false,
+    },
+    {
+      tmdbId: 9,
+      tmdbType: 'movie',
+      title: 'Anime Film',
+      originalTitle: 'アニメ映画',
+      originalLanguage: 'ja',
+      overview: null,
+      posterUrl: null,
+      year: 2020,
+      isAnimation: true,
+    },
+  ]);
+});
+
+test('a v4 read token travels as a bearer header instead of api_key', async () => {
+  const v4Token = ['eyJ', 'test-header', '.payload', '.sig'].join('');
+  const { calls, fetchImpl } = captureFetch(() => jsonResponse({ results: [] }));
+  const client = createTmdbClient({
+    resolveApiKey: async () => v4Token,
+    fetch: fetchImpl,
+  });
+  await client.search('x');
+  assert.equal(calls[0]!.url.searchParams.has('api_key'), false);
+  assert.equal(
+    (calls[0]!.init?.headers as Record<string, string>).Authorization,
+    `Bearer ${v4Token}`,
+  );
+});
+
+test('getDetails folds translations and alternative titles into the normalized shape', async () => {
+  const { calls, fetchImpl } = captureFetch(() =>
+    jsonResponse({
+      id: 61222,
+      name: 'Hanzawa Naoki',
+      original_name: '半沢直樹',
+      original_language: 'ja',
+      overview: 'A banker fights back.',
+      poster_path: '/hanzawa.jpg',
+      first_air_date: '2013-07-07',
+      number_of_episodes: 10,
+      genres: [{ id: 18, name: 'Drama' }],
+      alternative_titles: { results: [{ iso_3166_1: 'JP', title: 'Hanzawa Naoki Season 1' }] },
+      translations: {
+        translations: [
+          { iso_639_1: 'en', data: { name: 'Hanzawa Naoki', overview: 'A banker fights back.' } },
+          { iso_639_1: 'ja', data: { name: '半沢直樹', overview: '銀行員の物語' } },
+        ],
+      },
+    }),
+  );
+  const client = createTmdbClient({ resolveApiKey: async () => 'k', fetch: fetchImpl });
+
+  const details = await client.getDetails('tv', 61222);
+
+  assert.equal(calls[0]!.url.pathname, '/3/tv/61222');
+  assert.equal(
+    calls[0]!.url.searchParams.get('append_to_response'),
+    'alternative_titles,translations',
+  );
+  assert.deepEqual(details, {
+    tmdbId: 61222,
+    tmdbType: 'tv',
+    titleEnglish: 'Hanzawa Naoki',
+    titleNative: '半沢直樹',
+    description: 'A banker fights back.',
+    posterUrl: 'https://image.tmdb.org/t/p/w500/hanzawa.jpg',
+    episodesTotal: 10,
+    year: 2013,
+    originalLanguage: 'ja',
+    isAnimation: false,
+    allTitles: ['Hanzawa Naoki', '半沢直樹', 'Hanzawa Naoki Season 1'],
+  });
+});
+
+test('getDetails falls back to the Japanese overview and counts a movie as one episode', async () => {
+  const { fetchImpl } = captureFetch(() =>
+    jsonResponse({
+      id: 5,
+      title: '半沢直樹',
+      original_title: '半沢直樹',
+      original_language: 'ja',
+      overview: '',
+      release_date: '2019-03-01',
+      translations: {
+        translations: [{ iso_639_1: 'ja', data: { title: '半沢直樹', overview: 'あらすじ' } }],
+      },
+    }),
+  );
+  const client = createTmdbClient({ resolveApiKey: async () => 'k', fetch: fetchImpl });
+  const details = await client.getDetails('movie', 5);
+  assert.equal(details?.titleEnglish, null);
+  assert.equal(details?.titleNative, '半沢直樹');
+  assert.equal(details?.description, 'あらすじ');
+  assert.equal(details?.episodesTotal, 1);
+});
+
+test('getDetails returns null for an unknown id', async () => {
+  const { fetchImpl } = captureFetch(() => jsonResponse({ status_message: 'nope' }, 404));
+  const client = createTmdbClient({ resolveApiKey: async () => 'k', fetch: fetchImpl });
+  assert.equal(await client.getDetails('tv', 1), null);
+});
+
+test('client reuses command output across requests and invalidates it when either setting changes', async (t) => {
+  const fixture = commandFixture(t);
+  const counter = path.join(fixture.dir, 'calls');
+  const createCommand = (key: string) =>
+    fixture.command(`
+    const fs = require('node:fs');
+    const path = require('node:path');
+    fs.appendFileSync(path.join(__dirname, 'calls'), 'x');
+    process.stdout.write(${JSON.stringify(key)});
+  `);
+  let config: TmdbConfig = { apiKeyCommand: createCommand('command-key') };
+  const { calls, fetchImpl } = captureFetch(() => jsonResponse({ results: [] }));
+  const client = createTmdbClient({
+    resolveApiKey: createTmdbApiKeyResolver(
+      () => config,
+      () => 'bundled',
+    ),
+    fetch: fetchImpl,
+  });
+  await Promise.all([client.search('a'), client.search('b')]);
+  await client.getDetails('tv', 1);
+  assert.equal(fs.readFileSync(counter, 'utf8'), 'x');
+  assert.ok(calls.every(({ url }) => url.searchParams.get('api_key') === 'command-key'));
+  config = { ...config, apiKey: 'literal' };
+  await client.search('c');
+  assert.equal(calls.at(-1)?.url.searchParams.get('api_key'), 'literal');
+  config = { ...config, apiKey: '' };
+  await client.search('d');
+  assert.equal(fs.readFileSync(counter, 'utf8'), 'xx');
+  config = { apiKeyCommand: createCommand('new-key') };
+  await client.search('e');
+  assert.equal(fs.readFileSync(counter, 'utf8'), 'xxx');
+  assert.equal(calls.at(-1)?.url.searchParams.get('api_key'), 'new-key');
+});
+
+for (const failure of ['error', 'empty'] as const) {
+  test(`${failure} command output uses a bounded cooldown before retrying`, async (t) => {
+    const fixture = commandFixture(t);
+    const counter = path.join(fixture.dir, 'calls');
+    const command = fixture.command(`
+      const fs = require('node:fs');
+      const path = require('node:path');
+      const counter = path.join(__dirname, 'calls');
+      fs.appendFileSync(counter, 'x');
+      if (fs.readFileSync(counter, 'utf8').length === 1) process.exit(${failure === 'error' ? 1 : 0});
+      process.stdout.write('recovered');
+    `);
+    let now = 1000;
+    const originalNow = Date.now;
+    Date.now = () => now;
+    t.after(() => {
+      Date.now = originalNow;
+    });
+    let bundledKey: string | null = 'bundled';
+    const resolve = createTmdbApiKeyResolver(
+      () => ({ apiKeyCommand: command }),
+      () => bundledKey,
+    );
+    assert.deepEqual(await Promise.all([resolve(), resolve()]), ['bundled', 'bundled']);
+    now += 29_999;
+    assert.equal(await resolve(), 'bundled');
+    bundledKey = null;
+    assert.equal(await resolve(), null);
+    assert.equal(fs.readFileSync(counter, 'utf8'), 'x');
+    now += 1;
+    assert.equal(await resolve(), 'recovered');
+    assert.equal(await resolve(), 'recovered');
+    assert.equal(fs.readFileSync(counter, 'utf8'), 'xx');
+  });
+}
+
+for (const setting of ['apiKey', 'apiKeyCommand'] as const) {
+  test(`changing ${setting} clears a failed command cooldown`, async (t) => {
+    const fixture = commandFixture(t);
+    const counter = path.join(fixture.dir, 'calls');
+    const source = `
+      const fs = require('node:fs');
+      const path = require('node:path');
+      fs.appendFileSync(path.join(__dirname, 'calls'), 'x');
+      process.exit(1);
+    `;
+    let config: TmdbConfig = { apiKeyCommand: fixture.command(source) };
+    const resolve = createTmdbApiKeyResolver(
+      () => config,
+      () => 'bundled',
+    );
+    assert.equal(await resolve(), 'bundled');
+    assert.equal(await resolve(), 'bundled');
+    assert.equal(fs.readFileSync(counter, 'utf8'), 'x');
+    config =
+      setting === 'apiKey'
+        ? { ...config, apiKey: ' ' }
+        : { apiKeyCommand: fixture.command(source) };
+    assert.equal(await resolve(), 'bundled');
+    assert.equal(fs.readFileSync(counter, 'utf8'), 'xx');
+  });
+}
diff --git a/src/core/services/tmdb/tmdb-client.ts b/src/core/services/tmdb/tmdb-client.ts
new file mode 100644
index 00000000..12fa4d43
--- /dev/null
+++ b/src/core/services/tmdb/tmdb-client.ts
@@ -0,0 +1,311 @@
+import * as childProcess from 'node:child_process';
+import type { TmdbMediaType } from '../../../shared/media-kind';
+import type { TmdbConfig } from '../../../types/integrations';
+import type { StatsTmdbSearchResult } from '../../../types/stats-http-contract';
+
+export const TMDB_API_BASE_URL = 'https://api.themoviedb.org/3';
+const TMDB_POSTER_BASE_URL = 'https://image.tmdb.org/t/p/w500';
+const REQUEST_TIMEOUT_MS = 8_000;
+const API_KEY_COMMAND_RETRY_MS = 30_000;
+const ANIMATION_GENRE_ID = 16;
+
+export type TmdbSearchResult = StatsTmdbSearchResult;
+
+export interface TmdbTitleDetails {
+  tmdbId: number;
+  tmdbType: TmdbMediaType;
+  titleEnglish: string | null;
+  titleNative: string | null;
+  /** English synopsis, falling back to the Japanese one. */
+  description: string | null;
+  posterUrl: string | null;
+  episodesTotal: number | null;
+  year: number | null;
+  originalLanguage: string;
+  isAnimation: boolean;
+  /** Every name TMDB knows for the title, used for exact-title matching. */
+  allTitles: string[];
+}
+
+export interface TmdbClient {
+  search(query: string): Promise<TmdbSearchResult[]>;
+  getDetails(tmdbType: TmdbMediaType, tmdbId: number): Promise<TmdbTitleDetails | null>;
+}
+
+export class TmdbApiKeyMissingError extends Error {
+  constructor() {
+    super('TMDB API key not configured. Set tmdb.apiKey or tmdb.apiKeyCommand.');
+    this.name = 'TmdbApiKeyMissingError';
+  }
+}
+
+export class TmdbRequestError extends Error {
+  constructor(
+    message: string,
+    readonly status: number,
+  ) {
+    super(message);
+    this.name = 'TmdbRequestError';
+  }
+}
+
+function execCommand(command: string): Promise<string> {
+  return new Promise((resolve, reject) => {
+    childProcess.exec(command, { timeout: 10_000 }, (err, stdout) => {
+      if (err) {
+        reject(err);
+        return;
+      }
+      resolve(stdout);
+    });
+  });
+}
+
+/**
+ * Resolves the key in priority order: the user's literal `apiKey`, then the
+ * output of `apiKeyCommand`, then the key bundled into release builds.
+ */
+export async function resolveTmdbApiKey(
+  config: TmdbConfig | undefined,
+  bundledKey: string | null = null,
+): Promise<string | null> {
+  const literal = config?.apiKey?.trim();
+  if (literal) return literal;
+  const command = config?.apiKeyCommand?.trim();
+  if (command) {
+    try {
+      const key = (await execCommand(command)).trim();
+      if (key.length > 0) return key;
+    } catch {
+      /* fall through to the bundled key */
+    }
+  }
+  return bundledKey;
+}
+
+/** Cache successful command output until either credential setting changes. */
+export function createTmdbApiKeyResolver(
+  getConfig: () => TmdbConfig | undefined,
+  getBundledKey: () => string | null = () => null,
+): () => Promise<string | null> {
+  let state:
+    | {
+        apiKey: string | undefined;
+        apiKeyCommand: string | undefined;
+        pending: Promise<string | null> | null;
+        retryAfterMs: number;
+      }
+    | undefined;
+
+  return async () => {
+    const config = getConfig();
+    if (
+      !state ||
+      state.apiKey !== config?.apiKey ||
+      state.apiKeyCommand !== config?.apiKeyCommand
+    ) {
+      state = {
+        apiKey: config?.apiKey,
+        apiKeyCommand: config?.apiKeyCommand,
+        pending: null,
+        retryAfterMs: 0,
+      };
+    }
+    const current = state;
+    const literal = current.apiKey?.trim();
+    if (literal) return literal;
+    if (!current.apiKeyCommand?.trim()) return getBundledKey();
+    if (Date.now() < current.retryAfterMs) return getBundledKey();
+    current.pending ??= resolveTmdbApiKey(current).then((key) => {
+      if (!key) {
+        current.retryAfterMs = Date.now() + API_KEY_COMMAND_RETRY_MS;
+        current.pending = null;
+      }
+      return key;
+    });
+    const key = await current.pending;
+    return key ?? getBundledKey();
+  };
+}
+
+interface RawSearchItem {
+  media_type?: string;
+  id?: number;
+  name?: string;
+  original_name?: string;
+  title?: string;
+  original_title?: string;
+  original_language?: string;
+  overview?: string;
+  poster_path?: string | null;
+  first_air_date?: string;
+  release_date?: string;
+  genre_ids?: number[];
+}
+
+interface RawTranslation {
+  iso_639_1?: string;
+  data?: { name?: string; title?: string; overview?: string };
+}
+
+interface RawDetails extends RawSearchItem {
+  number_of_episodes?: number;
+  genres?: Array<{ id?: number }>;
+  alternative_titles?: { results?: Array<{ title?: string }>; titles?: Array<{ title?: string }> };
+  translations?: { translations?: RawTranslation[] };
+}
+
+function nonEmpty(value: unknown): string | null {
+  return typeof value === 'string' && value.trim() ? value.trim() : null;
+}
+
+function yearOf(date: string | undefined): number | null {
+  const year = Number.parseInt(date?.slice(0, 4) ?? '', 10);
+  return Number.isFinite(year) && year > 0 ? year : null;
+}
+
+function posterUrlOf(path: string | null | undefined): string | null {
+  return path ? `${TMDB_POSTER_BASE_URL}${path}` : null;
+}
+
+function mediaTypeOf(value: unknown): TmdbMediaType | null {
+  return value === 'tv' || value === 'movie' ? value : null;
+}
+
+function normalizeSearchItem(item: RawSearchItem): TmdbSearchResult | null {
+  const tmdbType = mediaTypeOf(item.media_type);
+  if (!tmdbType || typeof item.id !== 'number') return null;
+  const title = nonEmpty(item.name) ?? nonEmpty(item.title);
+  const originalTitle = nonEmpty(item.original_name) ?? nonEmpty(item.original_title) ?? title;
+  if (!title || !originalTitle) return null;
+  return {
+    tmdbId: item.id,
+    tmdbType,
+    title,
+    originalTitle,
+    originalLanguage: item.original_language ?? '',
+    overview: nonEmpty(item.overview),
+    posterUrl: posterUrlOf(item.poster_path),
+    year: yearOf(item.first_air_date ?? item.release_date),
+    isAnimation: (item.genre_ids ?? []).includes(ANIMATION_GENRE_ID),
+  };
+}
+
+function normalizeDetails(tmdbType: TmdbMediaType, raw: RawDetails): TmdbTitleDetails | null {
+  if (typeof raw.id !== 'number') return null;
+  const localizedTitle = nonEmpty(raw.name) ?? nonEmpty(raw.title);
+  const originalTitle = nonEmpty(raw.original_name) ?? nonEmpty(raw.original_title);
+  const originalLanguage = raw.original_language ?? '';
+  const translations = raw.translations?.translations ?? [];
+  const translationFor = (language: string) =>
+    translations.find((entry) => entry.iso_639_1 === language)?.data;
+  const english = translationFor('en');
+  const japanese = translationFor('ja');
+  const englishTitle =
+    nonEmpty(english?.name) ??
+    nonEmpty(english?.title) ??
+    (localizedTitle && localizedTitle !== originalTitle ? localizedTitle : null);
+  const nativeTitle =
+    originalLanguage === 'ja'
+      ? originalTitle
+      : (nonEmpty(japanese?.name) ?? nonEmpty(japanese?.title));
+  const alternativeTitles = [
+    ...(raw.alternative_titles?.results ?? []),
+    ...(raw.alternative_titles?.titles ?? []),
+  ].map((entry) => nonEmpty(entry.title));
+  const translatedTitles = translations.map(
+    (entry) => nonEmpty(entry.data?.name) ?? nonEmpty(entry.data?.title),
+  );
+  const allTitles = [
+    ...new Set(
+      [
+        localizedTitle,
+        originalTitle,
+        englishTitle,
+        nativeTitle,
+        ...translatedTitles,
+        ...alternativeTitles,
+      ].filter((title): title is string => Boolean(title)),
+    ),
+  ];
+  return {
+    tmdbId: raw.id,
+    tmdbType,
+    titleEnglish: englishTitle,
+    titleNative: nativeTitle,
+    description:
+      nonEmpty(raw.overview) ?? nonEmpty(english?.overview) ?? nonEmpty(japanese?.overview),
+    posterUrl: posterUrlOf(raw.poster_path),
+    episodesTotal:
+      tmdbType === 'movie'
+        ? 1
+        : typeof raw.number_of_episodes === 'number' && raw.number_of_episodes > 0
+          ? raw.number_of_episodes
+          : null,
+    year: yearOf(raw.first_air_date ?? raw.release_date),
+    originalLanguage,
+    isAnimation: (raw.genres ?? []).some((genre) => genre.id === ANIMATION_GENRE_ID),
+    allTitles,
+  };
+}
+
+// TMDB issues two kinds of credential: a short v3 key that travels as a query
+// parameter and a long v4 read token (a JWT) that goes in the Authorization
+// header. Users paste whichever the settings page showed them.
+function isV4Token(apiKey: string): boolean {
+  return apiKey.startsWith('eyJ');
+}
+
+export function createTmdbClient(deps: {
+  resolveApiKey: () => Promise<string | null>;
+  fetch?: typeof fetch;
+  baseUrl?: string;
+}): TmdbClient {
+  const fetchImpl = deps.fetch ?? fetch;
+  const baseUrl = (deps.baseUrl ?? TMDB_API_BASE_URL).replace(/\/+$/, '');
+
+  async function request<T>(path: string, params: Record<string, string>): Promise<T | null> {
+    const apiKey = await deps.resolveApiKey();
+    if (!apiKey) throw new TmdbApiKeyMissingError();
+    const url = new URL(`${baseUrl}${path}`);
+    for (const [key, value] of Object.entries(params)) url.searchParams.set(key, value);
+    const headers: Record<string, string> = { Accept: 'application/json' };
+    if (isV4Token(apiKey)) {
+      headers.Authorization = `Bearer ${apiKey}`;
+    } else {
+      url.searchParams.set('api_key', apiKey);
+    }
+    const res = await fetchImpl(url, { headers, signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS) });
+    if (res.status === 404) return null;
+    if (!res.ok) {
+      throw new TmdbRequestError(
+        `TMDB request failed: ${res.status} ${res.statusText}`,
+        res.status,
+      );
+    }
+    return (await res.json()) as T;
+  }
+
+  return {
+    async search(query) {
+      const trimmed = query.trim();
+      if (!trimmed) return [];
+      const payload = await request<{ results?: RawSearchItem[] }>('/search/multi', {
+        query: trimmed,
+        include_adult: 'false',
+        language: 'en-US',
+        page: '1',
+      });
+      return (payload?.results ?? [])
+        .map(normalizeSearchItem)
+        .filter((item): item is TmdbSearchResult => item !== null);
+    },
+    async getDetails(tmdbType, tmdbId) {
+      const raw = await request<RawDetails>(`/${tmdbType}/${tmdbId}`, {
+        language: 'en-US',
+        append_to_response: 'alternative_titles,translations',
+      });
+      return raw ? normalizeDetails(tmdbType, raw) : null;
+    },
+  };
+}
diff --git a/src/core/services/tokenizer.test.ts b/src/core/services/tokenizer.test.ts
index 17b770e8..b8a7f0d2 100644
--- a/src/core/services/tokenizer.test.ts
+++ b/src/core/services/tokenizer.test.ts
@@ -84,6 +84,17 @@ function createDeferred<T>() {
   };
 }
 
+test('tokenizeSubtitle keeps the blank line separating simultaneous cues', async () => {
+  // The tokenized payload's text drives display; folding the cue boundary would merge
+  // two speakers back onto one line the moment tokenization upgrades the plain emit.
+  const result = await tokenizeSubtitle(
+    '\u4e00\u884c\u76ee\n\n\u4e8c\u884c\u76ee',
+    makeDeps({ getYomitanExt: () => null }),
+  );
+
+  assert.equal(result.text, '\u4e00\u884c\u76ee\n\n\u4e8c\u884c\u76ee');
+});
+
 test('tokenizeSubtitle splits same-line grammar endings before applying annotations', async () => {
   const result = await tokenizeSubtitle(
     '猫です',
@@ -1682,6 +1693,12 @@ test('tokenizeSubtitle normalizes newlines before Yomitan parse request', async
   assert.equal(result.tokens, null);
 });
 
+test('tokenizeSubtitle preserves CRLF boundaries between simultaneous cues', async () => {
+  const result = await tokenizeSubtitle('a\r\n\r\nb', makeDeps());
+
+  assert.deepEqual(result, { text: 'a\n\nb', tokens: null });
+});
+
 test('tokenizeSubtitle collapses zero-width separators before Yomitan parse request', async () => {
   let parseInput = '';
   const result = await tokenizeSubtitle(
diff --git a/src/core/services/tokenizer.ts b/src/core/services/tokenizer.ts
index e1bdbd88..d5cd5e12 100644
--- a/src/core/services/tokenizer.ts
+++ b/src/core/services/tokenizer.ts
@@ -887,7 +887,15 @@ export async function tokenizeSubtitle(
   text: string,
   deps: TokenizerServiceDeps,
 ): Promise<SubtitleData> {
-  const displayText = normalizePlainSubtitleText(text);
+  // Normalize per cue group: the blank line separating simultaneous cues is display
+  // structure the payload text must keep, or the tokenized upgrade re-merges lines the
+  // provisional plain emit already showed apart.
+  const displayText = text
+    .replace(/\r\n/g, '\n')
+    .split(/\n{2,}/)
+    .map((part) => normalizePlainSubtitleText(part))
+    .filter(Boolean)
+    .join('\n\n');
 
   // ASS decoding already happened upstream (cue parser for files, mpv for live text), so
   // all this drops is whitespace -- but a whitespace-only line still normalizes to empty.
diff --git a/src/core/services/tokenizer/golden-corpus-harness.ts b/src/core/services/tokenizer/golden-corpus-harness.ts
index ce17fa35..4a9b7d9e 100644
--- a/src/core/services/tokenizer/golden-corpus-harness.ts
+++ b/src/core/services/tokenizer/golden-corpus-harness.ts
@@ -396,7 +396,8 @@ function createInjectedScriptVm(store: ReplayMessageStore): (script: string) =>
     Set,
     String,
   });
-  return async (script: string) => await vm.runInContext(script, context);
+  // Clone results into the host realm, matching Electron's process boundary.
+  return async (script: string) => structuredClone(await vm.runInContext(script, context));
 }
 
 export function createReplayTokenizerDeps(fixture: GoldenFixture): TokenizerServiceDeps {
diff --git a/src/core/services/tokenizer/sentence-furigana.test.ts b/src/core/services/tokenizer/sentence-furigana.test.ts
new file mode 100644
index 00000000..4b75e514
--- /dev/null
+++ b/src/core/services/tokenizer/sentence-furigana.test.ts
@@ -0,0 +1,46 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { generateSentenceFurigana } from './sentence-furigana';
+import { createDeps, runInjectedYomitanScript } from './yomitan-scan-test-harness';
+
+test('generates sentence readings through the parser runtime bridge', async () => {
+  const requests: string[] = [];
+  const deps = createDeps((script) =>
+    runInjectedYomitanScript(script, (action, params) => {
+      requests.push(action);
+      if (action === 'optionsGetFull')
+        return { profileCurrent: 0, profiles: [{ options: { scanning: { length: 20 } } }] };
+      assert.equal(action, 'parseText');
+      assert.ok(typeof params === 'object' && params !== null && 'text' in params);
+      assert.equal(params.text, '猫がいる。');
+      return [
+        {
+          source: 'scanning-parser',
+          content: [[{ text: '猫', reading: 'ねこ' }], [{ text: 'がいる。', reading: '' }]],
+        },
+      ];
+    }),
+  );
+  assert.equal(
+    await generateSentenceFurigana('猫がいる。', '猫', deps, { error: assert.fail }),
+    '<b> 猫[ねこ]</b>がいる。',
+  );
+  assert.ok(requests.includes('parseText'));
+});
+
+test(
+  'a stalled parser cannot indefinitely block sentence and media updates',
+  { timeout: 15_000 },
+  async () => {
+    const warnings: string[] = [];
+    const deps = createDeps(() => new Promise<never>(() => {}));
+    assert.equal(
+      await generateSentenceFurigana('猫', undefined, deps, {
+        error: () => undefined,
+        warn: (message) => warnings.push(message),
+      }),
+      null,
+    );
+    assert.equal(warnings.length, 1);
+  },
+);
diff --git a/src/core/services/tokenizer/sentence-furigana.ts b/src/core/services/tokenizer/sentence-furigana.ts
new file mode 100644
index 00000000..9bcf9315
--- /dev/null
+++ b/src/core/services/tokenizer/sentence-furigana.ts
@@ -0,0 +1,28 @@
+import { formatSentenceFurigana } from '../../../anki-integration/sentence-furigana';
+import { requestYomitanParseResults } from './yomitan-parser-runtime';
+
+export async function generateSentenceFurigana(
+  text: string,
+  highlightedText: string | undefined,
+  deps: Parameters<typeof requestYomitanParseResults>[1],
+  logger: Parameters<typeof requestYomitanParseResults>[2],
+): Promise<string | null> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    const results = await Promise.race([
+      requestYomitanParseResults(text, deps, logger),
+      new Promise<never>((_, reject) => {
+        timer = setTimeout(
+          () => reject(new Error('Sentence furigana generation timed out')),
+          10_000,
+        );
+      }),
+    ]);
+    return formatSentenceFurigana(text, results, highlightedText);
+  } catch (error) {
+    logger.warn?.('Failed to generate sentence furigana:', error);
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
diff --git a/src/core/services/tokenizer/yomitan-scan-test-harness.ts b/src/core/services/tokenizer/yomitan-scan-test-harness.ts
index 01745a96..8c9efeaa 100644
--- a/src/core/services/tokenizer/yomitan-scan-test-harness.ts
+++ b/src/core/services/tokenizer/yomitan-scan-test-harness.ts
@@ -64,7 +64,8 @@ export async function runInjectedYomitanScript(
   script: string,
   handler: (action: string, params: unknown) => unknown,
 ): Promise<unknown> {
-  return await vm.runInNewContext(script, createYomitanScriptSandbox(handler));
+  // Clone results into the host realm, matching Electron's process boundary.
+  return structuredClone(await vm.runInNewContext(script, createYomitanScriptSandbox(handler)));
 }
 
 // Persistent page context shared across executeJavaScript calls, matching the
@@ -75,7 +76,8 @@ function createPersistentYomitanScriptRunner(
   handler: (action: string, params: unknown) => unknown,
 ): (script: string) => Promise<unknown> {
   const context = vm.createContext(createYomitanScriptSandbox(handler));
-  return async (script: string) => await vm.runInContext(script, context);
+  // Clone results into the host realm, matching Electron's process boundary.
+  return async (script: string) => structuredClone(await vm.runInContext(script, context));
 }
 
 // Deps whose parser window executes every injected script (profile metadata,
diff --git a/src/core/services/youtube/timedtext.test.ts b/src/core/services/youtube/timedtext.test.ts
index 1f543cd9..1320bdad 100644
--- a/src/core/services/youtube/timedtext.test.ts
+++ b/src/core/services/youtube/timedtext.test.ts
@@ -39,6 +39,118 @@ test('convertYoutubeTimedTextToVtt does not swallow text after zero-length overl
   );
 });
 
+test('convertYoutubeTimedTextToVtt extends rolling captions to the next window event', () => {
+  // Real-world shape of YouTube's sentence-level auto captions: window-append
+  // filler rows (a="1", sometimes without d) mark the display timeline, while
+  // long text rows carry a placeholder d="3000" far shorter than the speech.
+  const result = convertYoutubeTimedTextToVtt(
+    [
+      '<timedtext><body>',
+      '<p t="98550" d="3010" w="1" a="1">\n</p>',
+      '<p t="98560" d="3000" w="1"><s ac="0">ありがとうって言えないよね。こんなんじゃ。</s></p>',
+      '<p t="106950" w="1" a="1">\n</p>',
+      '<p t="106960" d="3799" w="1"><s ac="0">私だったら無理だよ。</s></p>',
+      '</body></timedtext>',
+    ].join('\n'),
+  );
+
+  assert.equal(
+    result,
+    [
+      'WEBVTT',
+      '',
+      '00:01:38.560 --> 00:01:46.950',
+      'ありがとうって言えないよね。こんなんじゃ。',
+      '',
+      '00:01:46.960 --> 00:01:50.759',
+      '私だったら無理だよ。',
+      '',
+    ].join('\n'),
+  );
+});
+
+test('convertYoutubeTimedTextToVtt pages oversized two-row rolling captions', () => {
+  const text =
+    'あの西に結構こう山田がスーパーアプローチしてるんだけど西気づかないからちょっとこっちも気づかない感じでこう接してあげようかなて思ってんだけどあの唇巻き込んじゃうしあの思ってることも全部縁に出ちゃって自分であちゃったって言っちゃうタイプなんで結構なんかこうドライなんだけどそこがおもろいよねみたいな';
+  const result = convertYoutubeTimedTextToVtt(
+    [
+      '<timedtext format="3">',
+      '<head>',
+      '<ws id="1" mh="2" ju="0" sd="3"/>',
+      '<wp id="1" ap="6" ah="20" av="100" rc="2" cc="40"/>',
+      '</head>',
+      '<body>',
+      '<w t="0" id="1" wp="1" ws="1"/>',
+      `<p t="60440" d="3000" w="1"><s ac="0">${text}</s></p>`,
+      '<p t="72695" w="1" a="1">\n</p>',
+      '</body>',
+      '</timedtext>',
+    ].join('\n'),
+  );
+
+  const cues = result
+    .trim()
+    .split(/\n\n/)
+    .filter((block) => block.includes('-->'));
+  const cueText = cues.map((cue) => cue.split('\n').slice(1).join('\n'));
+
+  assert.equal(cues.length, 2);
+  assert.deepEqual(
+    cues.map((cue) => cue.split('\n')[0]),
+    ['00:01:00.440 --> 00:01:07.064', '00:01:07.064 --> 00:01:12.695'],
+  );
+  assert.ok(cueText.every((page) => [...page].length <= 80));
+  assert.equal(cueText.join(''), text);
+});
+
+test('convertYoutubeTimedTextToVtt leaves pop-on captions intact', () => {
+  const result = convertYoutubeTimedTextToVtt(
+    [
+      '<timedtext format="3">',
+      '<head>',
+      '<ws id="1" mh="0"/>',
+      '<wp id="1" rc="2" cc="4"/>',
+      '</head>',
+      '<body>',
+      '<w t="0" id="1" wp="1" ws="1"/>',
+      '<p t="1000" d="3000" w="1">abcdefghijklmnopqrst</p>',
+      '</body>',
+      '</timedtext>',
+    ].join('\n'),
+  );
+
+  assert.equal(
+    result,
+    ['WEBVTT', '', '00:00:01.000 --> 00:00:04.000', 'abcdefghijklmnopqrst', ''].join('\n'),
+  );
+});
+
+test('convertYoutubeTimedTextToVtt keeps explicit 3000ms sound-cue durations in rolling documents', () => {
+  const result = convertYoutubeTimedTextToVtt(
+    [
+      '<timedtext><body>',
+      '<p t="20305" d="3000" w="1">[音楽]</p>',
+      '<p t="26269" w="1" a="1">\n</p>',
+      '<p t="26279" d="3000" w="1"><s ac="0">じゃあ、君からお願いします。</s></p>',
+      '</body></timedtext>',
+    ].join('\n'),
+  );
+
+  assert.equal(
+    result,
+    [
+      'WEBVTT',
+      '',
+      '00:00:20.305 --> 00:00:23.305',
+      '[音楽]',
+      '',
+      '00:00:26.279 --> 00:00:29.279',
+      'じゃあ、君からお願いします。',
+      '',
+    ].join('\n'),
+  );
+});
+
 test('normalizeYoutubeAutoVtt strips cumulative rolling-caption prefixes', () => {
   const result = normalizeYoutubeAutoVtt(
     [
diff --git a/src/core/services/youtube/timedtext.ts b/src/core/services/youtube/timedtext.ts
index fe3aaf47..c0a88020 100644
--- a/src/core/services/youtube/timedtext.ts
+++ b/src/core/services/youtube/timedtext.ts
@@ -2,9 +2,31 @@ interface YoutubeTimedTextRow {
   startMs: number;
   durationMs: number;
   text: string;
+  isGenerated: boolean;
+  rollingWindow: YoutubeRollingWindow | null;
+}
+
+interface YoutubeRollingWindow {
+  rowCount: number;
+  columnCount: number;
+}
+
+interface YoutubeTimedTextWindowDefinitions {
+  rollingStyleIds: Set<string>;
+  positions: Map<string, YoutubeRollingWindow>;
+  windows: Map<string, YoutubeRollingWindow>;
+}
+
+interface YoutubeTimedTextDocument {
+  rows: YoutubeTimedTextRow[];
+  // Start times of every <p> event, including empty window-append fillers.
+  // Rolling speech rows with a 3000ms placeholder display until the next event.
+  eventStartsMs: number[];
+  hasRollingWindowEvents: boolean;
 }
 
 const YOUTUBE_TIMEDTEXT_EXTENSIONS = new Set(['srv1', 'srv2', 'srv3', 'ytsrv3']);
+const YOUTUBE_ROLLING_PLACEHOLDER_DURATION_MS = 3_000;
 
 function decodeNumericEntity(match: string, codePoint: number): string {
   if (
@@ -39,27 +61,129 @@ function parseAttributeMap(raw: string): Map<string, string> {
   return attrs;
 }
 
-function extractYoutubeTimedTextRows(xml: string): YoutubeTimedTextRow[] {
+function parsePositiveInteger(value: string | undefined): number | null {
+  if (value === undefined) {
+    return null;
+  }
+  const parsed = Number(value);
+  return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : null;
+}
+
+function extractYoutubeTimedTextWindowDefinitions(xml: string): YoutubeTimedTextWindowDefinitions {
+  const rollingStyleIds = new Set<string>();
+  for (const match of xml.matchAll(/<ws\b([^>]*)\/?\s*>/g)) {
+    const attrs = parseAttributeMap(match[1] ?? '');
+    const id = attrs.get('id');
+    if (id !== undefined && attrs.get('mh') === '2') {
+      rollingStyleIds.add(id);
+    }
+  }
+
+  const positions = new Map<string, YoutubeRollingWindow>();
+  for (const match of xml.matchAll(/<wp\b([^>]*)\/?\s*>/g)) {
+    const attrs = parseAttributeMap(match[1] ?? '');
+    const id = attrs.get('id');
+    const rowCount = parsePositiveInteger(attrs.get('rc'));
+    const columnCount = parsePositiveInteger(attrs.get('cc'));
+    if (id !== undefined && rowCount !== null && columnCount !== null) {
+      positions.set(id, { rowCount, columnCount });
+    }
+  }
+
+  const windows = new Map<string, YoutubeRollingWindow>();
+  for (const match of xml.matchAll(/<w\b([^>]*)\/?\s*>/g)) {
+    const attrs = parseAttributeMap(match[1] ?? '');
+    const id = attrs.get('id');
+    const styleId = attrs.get('ws');
+    const positionId = attrs.get('wp');
+    const position = positionId === undefined ? undefined : positions.get(positionId);
+    if (
+      id !== undefined &&
+      styleId !== undefined &&
+      rollingStyleIds.has(styleId) &&
+      position !== undefined
+    ) {
+      windows.set(id, position);
+    }
+  }
+
+  return { rollingStyleIds, positions, windows };
+}
+
+function resolveRollingWindow(
+  attrs: Map<string, string>,
+  definitions: YoutubeTimedTextWindowDefinitions,
+): YoutubeRollingWindow | null {
+  const windowId = attrs.get('w');
+  if (windowId !== undefined) {
+    return definitions.windows.get(windowId) ?? null;
+  }
+
+  const styleId = attrs.get('ws');
+  const positionId = attrs.get('wp');
+  if (
+    styleId === undefined ||
+    positionId === undefined ||
+    !definitions.rollingStyleIds.has(styleId)
+  ) {
+    return null;
+  }
+  return definitions.positions.get(positionId) ?? null;
+}
+
+function extractYoutubeTimedTextDocument(xml: string): YoutubeTimedTextDocument {
   const rows: YoutubeTimedTextRow[] = [];
+  const eventStartsMs: number[] = [];
+  let hasRollingWindowEvents = false;
+  const windowDefinitions = extractYoutubeTimedTextWindowDefinitions(xml);
 
   for (const match of xml.matchAll(/<p\b([^>]*)>([\s\S]*?)<\/p>/g)) {
     const attrs = parseAttributeMap(match[1] ?? '');
     const startMs = Number(attrs.get('t'));
+    if (!Number.isFinite(startMs)) {
+      continue;
+    }
+    eventStartsMs.push(startMs);
+    if (attrs.get('a') === '1') {
+      hasRollingWindowEvents = true;
+    }
+
     const durationMs = Number(attrs.get('d'));
-    if (!Number.isFinite(startMs) || !Number.isFinite(durationMs)) {
+    if (!Number.isFinite(durationMs)) {
       continue;
     }
 
-    const inner = (match[2] ?? '').replace(/<br\s*\/?>/gi, '\n').replace(/<[^>]+>/g, '');
+    const rawInner = match[2] ?? '';
+    const inner = rawInner.replace(/<br\s*\/?>/gi, '\n').replace(/<[^>]+>/g, '');
     const text = decodeHtmlEntities(inner).trim();
     if (!text) {
       continue;
     }
 
-    rows.push({ startMs, durationMs, text });
+    rows.push({
+      startMs,
+      durationMs,
+      text,
+      isGenerated: /<s\b/.test(rawInner),
+      rollingWindow: resolveRollingWindow(attrs, windowDefinitions),
+    });
   }
 
-  return rows;
+  eventStartsMs.sort((a, b) => a - b);
+  return { rows, eventStartsMs, hasRollingWindowEvents };
+}
+
+function findNextEventStartMs(eventStartsMs: number[], afterMs: number): number | undefined {
+  for (const startMs of eventStartsMs) {
+    if (startMs > afterMs) {
+      return startMs;
+    }
+  }
+  return undefined;
+}
+
+function isGeneratedRollingCue(row: YoutubeTimedTextRow, hasRollingWindowEvents: boolean): boolean {
+  return row.isGenerated && (row.rollingWindow !== null || hasRollingWindowEvents);
 }
 
 function formatVttTimestamp(ms: number): string {
@@ -71,6 +195,79 @@ function formatVttTimestamp(ms: number): string {
   return `${String(hours).padStart(2, '0')}:${String(minutes).padStart(2, '0')}:${String(seconds).padStart(2, '0')}.${String(millis).padStart(3, '0')}`;
 }
 
+const ROLLING_PAGE_BREAK_PATTERN = /[\s、。！？!?]/u;
+
+// VTT cannot carry SRV3's row and column limits. Page only roll-up windows so
+// the overlay keeps their bounded presentation without changing authored cues.
+function splitRollingCaptionIntoPages(text: string, rollingWindow: YoutubeRollingWindow): string[] {
+  const pageCapacity = rollingWindow.rowCount * rollingWindow.columnCount;
+  const characters = [...text];
+  if (
+    !Number.isSafeInteger(pageCapacity) ||
+    pageCapacity <= 0 ||
+    characters.length <= pageCapacity
+  ) {
+    return [text];
+  }
+
+  const pages: string[] = [];
+  let pageStart = 0;
+  while (pageStart < characters.length) {
+    let pageEnd = Math.min(pageStart + pageCapacity, characters.length);
+    if (pageEnd < characters.length) {
+      const earliestNaturalBreak = pageStart + Math.ceil(pageCapacity * 0.6);
+      for (let index = pageEnd - 1; index >= earliestNaturalBreak; index -= 1) {
+        if (ROLLING_PAGE_BREAK_PATTERN.test(characters[index]!)) {
+          pageEnd = index + 1;
+          break;
+        }
+      }
+    }
+    pages.push(characters.slice(pageStart, pageEnd).join(''));
+    pageStart = pageEnd;
+  }
+  return pages;
+}
+
+interface TimedCaptionPage {
+  startMs: number;
+  endMs: number;
+  text: string;
+}
+
+function timeCaptionPages(input: {
+  text: string;
+  pages: string[];
+  startMs: number;
+  endMs: number;
+}): TimedCaptionPage[] {
+  const durationMs = input.endMs - input.startMs;
+  if (input.pages.length === 1 || durationMs < input.pages.length) {
+    return [{ startMs: input.startMs, endMs: input.endMs, text: input.text }];
+  }
+
+  const totalCharacters = [...input.text].length;
+  const timedPages: TimedCaptionPage[] = [];
+  let consumedCharacters = 0;
+  let pageStartMs = input.startMs;
+  // Automatic captions often omit span offsets, so distribute the known cue
+  // duration by page length while guaranteeing every page at least one ms.
+  for (let index = 0; index < input.pages.length; index += 1) {
+    const page = input.pages[index]!;
+    consumedCharacters += [...page].length;
+    const remainingPages = input.pages.length - index - 1;
+    const proportionalEndMs =
+      input.startMs + Math.round((durationMs * consumedCharacters) / totalCharacters);
+    const pageEndMs =
+      remainingPages === 0
+        ? input.endMs
+        : Math.min(Math.max(proportionalEndMs, pageStartMs + 1), input.endMs - remainingPages);
+    timedPages.push({ startMs: pageStartMs, endMs: pageEndMs, text: page });
+    pageStartMs = pageEndMs;
+  }
+  return timedPages;
+}
+
 export function isYoutubeTimedTextExtension(value: string | undefined): boolean {
   if (!value) {
     return false;
@@ -79,7 +276,7 @@ export function isYoutubeTimedTextExtension(value: string | undefined): boolean
 }
 
 export function convertYoutubeTimedTextToVtt(xml: string): string {
-  const rows = extractYoutubeTimedTextRows(xml);
+  const { rows, eventStartsMs, hasRollingWindowEvents } = extractYoutubeTimedTextDocument(xml);
   if (rows.length === 0) {
     return 'WEBVTT\n';
   }
@@ -90,10 +287,19 @@ export function convertYoutubeTimedTextToVtt(xml: string): string {
     const row = rows[index]!;
     const nextRow = rows[index + 1];
     const unclampedEnd = row.startMs + row.durationMs;
+    // YouTube uses exactly 3000ms as a placeholder for generated rolling speech.
+    // Plain-text cues can explicitly use the same duration and must keep it.
+    const nextEventStart =
+      isGeneratedRollingCue(row, hasRollingWindowEvents) &&
+      row.durationMs === YOUTUBE_ROLLING_PLACEHOLDER_DURATION_MS
+        ? findNextEventStartMs(eventStartsMs, row.startMs)
+        : undefined;
     const clampedEnd =
-      nextRow && unclampedEnd > nextRow.startMs
-        ? Math.max(row.startMs, nextRow.startMs - 1)
-        : unclampedEnd;
+      nextEventStart !== undefined
+        ? nextEventStart
+        : nextRow && unclampedEnd > nextRow.startMs
+          ? Math.max(row.startMs, nextRow.startMs - 1)
+          : unclampedEnd;
     if (clampedEnd <= row.startMs) {
       continue;
     }
@@ -106,9 +312,19 @@ export function convertYoutubeTimedTextToVtt(xml: string): string {
     if (!text) {
       continue;
     }
-    blocks.push(
-      `${formatVttTimestamp(row.startMs)} --> ${formatVttTimestamp(clampedEnd)}\n${text}`,
-    );
+    const pages = row.rollingWindow
+      ? splitRollingCaptionIntoPages(text, row.rollingWindow)
+      : [text];
+    for (const page of timeCaptionPages({
+      text,
+      pages,
+      startMs: row.startMs,
+      endMs: clampedEnd,
+    })) {
+      blocks.push(
+        `${formatVttTimestamp(page.startMs)} --> ${formatVttTimestamp(page.endMs)}\n${page.text}`,
+      );
+    }
   }
 
   return `WEBVTT\n\n${blocks.join('\n\n')}\n`;
diff --git a/src/core/utils/shortcut-config.ts b/src/core/utils/shortcut-config.ts
index b45deeb3..22217d9f 100644
--- a/src/core/utils/shortcut-config.ts
+++ b/src/core/utils/shortcut-config.ts
@@ -16,6 +16,8 @@ export interface ConfiguredShortcuts {
   openRuntimeOptions: string | null | undefined;
   openJimaku: string | null | undefined;
   openTsukihime: string | null | undefined;
+  openSubtitleSelection: string | null | undefined;
+  openSubtitleGeneration: string | null | undefined;
   openSessionHelp: string | null | undefined;
   openControllerSelect: string | null | undefined;
   openControllerDebug: string | null | undefined;
@@ -67,6 +69,11 @@ export function resolveConfiguredShortcuts(
     openRuntimeOptions: normalizeShortcut(shortcutValue('openRuntimeOptions')),
     openJimaku: normalizeShortcut(shortcutValue('openJimaku')),
     openTsukihime: normalizeShortcut(shortcutValue('openTsukihime')),
+    openSubtitleSelection:
+      config.subtitleSelection?.enabled === true
+        ? normalizeShortcut(shortcutValue('openSubtitleSelection'))
+        : null,
+    openSubtitleGeneration: normalizeShortcut(shortcutValue('openSubtitleGeneration')),
     openSessionHelp: normalizeShortcut(shortcutValue('openSessionHelp')),
     openControllerSelect: normalizeShortcut(shortcutValue('openControllerSelect')),
     openControllerDebug: normalizeShortcut(shortcutValue('openControllerDebug')),
diff --git a/src/main-entry-runtime.test.ts b/src/main-entry-runtime.test.ts
index 18bcd781..46d24cc4 100644
--- a/src/main-entry-runtime.test.ts
+++ b/src/main-entry-runtime.test.ts
@@ -585,26 +585,60 @@ test('shouldDetachBackgroundLaunch only for first background invocation', () =>
 
 test('configureEarlyAppPaths pins userData to canonical SubMiner config dir', () => {
   const calls: string[] = [];
-
-  const userDataPath = configureEarlyAppPaths(
-    {
-      setName: (name) => {
-        calls.push(`name:${name}`);
+  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'subminer-entry-paths-'));
+  const configDir = path.posix.join(tempDir, 'SubMiner');
+  try {
+    const userDataPath = configureEarlyAppPaths(
+      {
+        setName: (name) => {
+          calls.push(`name:${name}`);
+        },
+        setPath: (key, value) => {
+          calls.push(`path:${key}:${value}`);
+        },
       },
-      setPath: (key, value) => {
-        calls.push(`path:${key}:${value}`);
+      {
+        platform: 'linux',
+        homeDir: tempDir,
+        xdgConfigHome: tempDir,
+        existsSync: (candidate) =>
+          candidate === path.posix.join(tempDir, 'subminer', 'config.jsonc'),
       },
-    },
-    {
-      platform: 'linux',
-      homeDir: '/home/tester',
-      xdgConfigHome: '/tmp/xdg',
-      existsSync: (candidate) => candidate === '/tmp/xdg/subminer/config.jsonc',
-    },
-  );
+    );
 
-  assert.equal(userDataPath, '/tmp/xdg/SubMiner');
-  assert.deepEqual(calls, ['name:SubMiner', 'path:userData:/tmp/xdg/SubMiner']);
+    assert.equal(userDataPath, configDir);
+    assert.deepEqual(calls, ['name:SubMiner', `path:userData:${configDir}`]);
+  } finally {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  }
+});
+
+test('configureEarlyAppPaths creates a fresh macOS config directory before Electron uses it', () => {
+  const homeDir = fs.mkdtempSync(path.join(os.tmpdir(), 'subminer-entry-first-launch-'));
+  const configDir = path.posix.join(homeDir, '.config', 'SubMiner');
+  try {
+    const app = {
+      setName: () => {},
+      setPath: (_key: 'userData', value: string) => {
+        assert.equal(value, configDir);
+        assert.equal(fs.statSync(value).isDirectory(), true);
+      },
+    };
+    const options = { platform: 'darwin', homeDir, xdgConfigHome: '' } satisfies Parameters<
+      typeof configureEarlyAppPaths
+    >[1];
+
+    assert.equal(fs.existsSync(path.join(homeDir, '.config')), false);
+    configureEarlyAppPaths(app, options);
+
+    const configPath = path.join(configDir, 'config.jsonc');
+    const existingConfig = '{"logging":{"level":"debug"}}\n';
+    fs.writeFileSync(configPath, existingConfig);
+    configureEarlyAppPaths(app, options);
+    assert.equal(fs.readFileSync(configPath, 'utf8'), existingConfig);
+  } finally {
+    fs.rmSync(homeDir, { recursive: true, force: true });
+  }
 });
 
 test('configureEarlyAppPaths isolates development runs from the production profile', () => {
diff --git a/src/main-entry-runtime.ts b/src/main-entry-runtime.ts
index d1b5e9ac..29c9c166 100644
--- a/src/main-entry-runtime.ts
+++ b/src/main-entry-runtime.ts
@@ -277,6 +277,8 @@ export function configureEarlyAppPaths(app: EarlyAppLike, options?: EarlyAppPath
     ? platformPath.join(platformPath.dirname(configDir), DEVELOPMENT_APP_NAME)
     : configDir;
 
+  // The entry process requests its singleton lock before main-process config bootstrap.
+  fs.mkdirSync(userDataPath, { recursive: true });
   app.setName(APP_NAME);
   app.setPath('userData', userDataPath);
 
diff --git a/src/main.ts b/src/main.ts
index c8d04977..9a8ca7e7 100644
--- a/src/main.ts
+++ b/src/main.ts
@@ -15,6 +15,7 @@
   You should have received a copy of the GNU General Public License
   along with this program.  If not, see <https://www.gnu.org/licenses/>.
 */
+import { generateSentenceFurigana } from './core/services/tokenizer/sentence-furigana';
 import {
   app,
   BrowserWindow,
@@ -33,6 +34,7 @@ import {
 } from 'electron';
 import { applyControllerConfigUpdate } from './main/controller-config-update.js';
 import { openPlaylistBrowser as openPlaylistBrowserRuntime } from './main/runtime/playlist-browser-open';
+import { readMpvInputBindings } from './main/runtime/mpv-input-bindings';
 import { createAniSkipRuntime } from './main/runtime/aniskip-runtime';
 import { resolveAniSkipMetadataForFile } from './main/runtime/aniskip-metadata';
 import { createDiscordRpcClient } from './main/runtime/discord-rpc-client.js';
@@ -52,10 +54,7 @@ import {
   clearLinuxMpvFullscreenOverlayRefreshTimeouts,
   updateLinuxMpvFullscreenOverlayRefreshBurst,
 } from './main/runtime/linux-mpv-fullscreen-overlay-refresh';
-import {
-  resolveLinuxVisibleOverlayWindowModeAction,
-  type LinuxVisibleOverlayWindowMode,
-} from './main/runtime/linux-visible-overlay-window-mode';
+import { createLinuxOverlayModeRuntime } from './main/runtime/linux-overlay-mode-runtime';
 import { shouldRunLinuxOverlayZOrderKeepAlive } from './main/runtime/linux-overlay-zorder-keepalive';
 import { focusMacOSOverlayWindow } from './main/runtime/macos-overlay-window-focus';
 import { restoreMacOSMpvFocusAfterModalClose } from './main/runtime/macos-modal-focus-handoff';
@@ -81,7 +80,6 @@ protocol.registerSchemesAsPrivileged([
 ]);
 
 import * as fs from 'fs';
-import { spawn } from 'node:child_process';
 import * as os from 'os';
 import * as path from 'path';
 import { MecabTokenizer } from './mecab-tokenizer';
@@ -128,11 +126,6 @@ import {
 import { printHelp } from './cli/help';
 import { IPC_CHANNELS, type OverlayHostedModal } from './shared/ipc/contracts';
 import { buildMpvLoggingArgs } from './shared/mpv-logging-args';
-import {
-  MPV_X11_BACKEND_ARGS,
-  applyX11EnvOverrides,
-  shouldForceX11WaylandSession,
-} from './shared/mpv-x11-backend';
 import { AnkiConnectClient } from './anki-connect';
 import {
   getStartupModeFlags,
@@ -239,7 +232,10 @@ import {
   createCycleSecondarySubModeRuntimeHandler,
 } from './main/runtime/domains/mpv';
 import { buildSubtitleTrackDiagnostics } from './main/runtime/mpv-track-diagnostics';
-import { resolveCanonicalPrimarySubtitle } from './main/runtime/primary-subtitle-text';
+import {
+  resolveCanonicalPrimarySubtitle,
+  resolvePrimarySubtitle,
+} from './main/runtime/primary-subtitle-text';
 import {
   createBuildCopyCurrentSubtitleMainDepsHandler,
   createBuildHandleMineSentenceDigitMainDepsHandler,
@@ -306,7 +302,6 @@ import {
   listJellyfinItemsRuntime,
   listJellyfinLibrariesRuntime,
   listJellyfinSubtitleTracksRuntime,
-  loadJellyfinSubtitleDelay,
   loadSubtitlePosition as loadSubtitlePositionCore,
   loadYomitanExtension as loadYomitanExtensionCore,
   markLastCardAsAudioCard as markLastCardAsAudioCardCore,
@@ -316,9 +311,9 @@ import {
   promoteSettingsWindowAboveOverlay,
   registerGlobalShortcuts as registerGlobalShortcutsCore,
   replayCurrentSubtitleRuntime,
+  resolveSanitizedSubtitleSeekCommand,
   resolveJellyfinPlaybackPlanRuntime,
   runStartupBootstrapRuntime,
-  saveJellyfinSubtitleDelay,
   saveSubtitlePosition as saveSubtitlePositionCore,
   clearYomitanParserCachesForWindow,
   getYomitanCurrentAnkiDeckName as getYomitanCurrentAnkiDeckNameCore,
@@ -390,12 +385,14 @@ import {
   detectCommandLineLauncher,
   installBun as installCommandLineBun,
   installLauncher as installCommandLineLauncher,
+  refreshManagedCommandLineLauncher,
 } from './main/runtime/command-line-launcher';
 import {
   createWindowsMpvLaunchDeps,
   getConfiguredWindowsMpvPathStatus,
   launchWindowsMpv,
 } from './main/runtime/windows-mpv-launch';
+import { resolveMpvExecutablePath, spawnMpvProcess } from './main/runtime/mpv-process';
 import { createWaitForMpvConnectedHandler } from './main/runtime/jellyfin-remote-connection';
 import {
   DEFAULT_JELLYFIN_CLIENT_NAME,
@@ -421,6 +418,7 @@ import {
   writeStatsCliCommandResponse,
 } from './main/runtime/stats-cli-command';
 import { createStatsServerRuntime } from './main/runtime/stats-server-runtime';
+import { createForceQuitHandler } from './main/runtime/app-lifecycle-actions';
 import { resolveLegacyVocabularyPosFromTokens } from './core/services/immersion-tracker/legacy-vocabulary-pos';
 import { createAnilistUpdateQueue } from './core/services/anilist/anilist-update-queue';
 import {
@@ -429,6 +427,9 @@ import {
 } from './core/services/anilist/anilist-updater';
 import { createCoverArtFetcher } from './core/services/anilist/cover-art-fetcher';
 import { createAnilistRateLimiter } from './core/services/anilist/rate-limiter';
+import { createLiveActionMetadataResolver } from './core/services/tmdb/live-action-resolver';
+import { createTmdbClient, createTmdbApiKeyResolver } from './core/services/tmdb/tmdb-client';
+import { readBundledTmdbApiKey } from './core/services/tmdb/bundled-api-key';
 import { createJellyfinTokenStore } from './core/services/jellyfin-token-store';
 import { applyRuntimeOptionResultRuntime } from './core/services/runtime-options-ipc';
 import { createAnilistTokenStore } from './core/services/anilist/anilist-token-store';
@@ -463,11 +464,29 @@ import {
 } from './main/early-single-instance';
 import { handleMpvCommandFromIpcRuntime } from './main/ipc-mpv-command';
 import { registerIpcRuntimeServices } from './main/ipc-runtime';
+import { createSubtitleGenerationRuntime } from './main/runtime/subtitle-generation-runtime';
+import { registerSubtitleGenerationIpc } from './main/runtime/subtitle-generation-ipc';
+import {
+  createSubtitleSelectionRuntime,
+  openSubtitleSelectionModal,
+  registerSubtitleSelectionIpc,
+} from './main/runtime/subtitle-selection';
+import { openSubtitleGenerationModal } from './main/runtime/subtitle-generation-open';
 import { createAnkiJimakuIpcRuntimeServiceDeps } from './main/dependencies';
 import { createMainBootServices, type MainBootServicesResult } from './main/boot/services';
 import { handleCliCommandRuntimeServiceWithContext } from './main/cli-runtime';
 import { createOverlayModalRuntimeService } from './main/overlay-runtime';
 import { createOverlayModalInputState } from './main/runtime/overlay-modal-input-state';
+import { MediaTimingPreviewSession } from './core/services/media-timing-preview';
+import { getSharedRemoteMediaWindowCache } from './core/services/remote-media-window-cache';
+import { resolveMediaGenerationInput } from './anki-integration/media-source';
+import { generateSpeechWaveform } from './core/services/media-timing-waveform';
+import { createMediaTimingFrameExtractor } from './core/services/media-timing-frame';
+import {
+  collectMediaTimingContextLines,
+  createMediaTimingReviewRuntime,
+} from './main/runtime/media-timing-review';
+import { openMediaTimingReviewModal } from './main/runtime/media-timing-review-open';
 import { openYoutubeTrackPicker } from './main/runtime/youtube-picker-open';
 import { openRuntimeOptionsModal as openRuntimeOptionsModalRuntime } from './main/runtime/runtime-options-open';
 import { openJimakuModal as openJimakuModalRuntime } from './main/runtime/jimaku-open';
@@ -591,9 +610,10 @@ import {
 import { buildSubtitleSidebarSourceKey } from './main/runtime/subtitle-prefetch-source';
 import { createSubtitlePrefetchInitController } from './main/runtime/subtitle-prefetch-init';
 import {
+  createCachedInternalSubtitleTrackExtractor,
   loadSubtitleSourceText,
-  extractInternalSubtitleTrackToTempFile,
 } from './main/runtime/internal-subtitle-extraction';
+import { createRemoteMediaPathDetector } from './main/runtime/network-media-path';
 import { applyCharacterDictionarySelection } from './main/character-dictionary-selection';
 import { getSubsyncConfig } from './subsync/utils';
 
@@ -662,24 +682,7 @@ const MPV_JELLYFIN_DEFAULT_ARGS = [
   '--slang=ja,jp,jpn,japanese,en,eng,english,enus,en-us',
 ] as const;
 
-/**
- * Spawn a SubMiner-managed mpv (Jellyfin/YouTube) detached. On unsupported Wayland
- * sessions it is pinned to XWayland — Wayland-hint env stripped and an X11 GPU context
- * appended — so the XWayland overlay can stay above it, matching the `subminer` launcher.
- */
-function spawnManagedMpvProcess(args: string[]): ReturnType<typeof spawn> {
-  if (!shouldForceX11WaylandSession(process.env)) {
-    return spawn('mpv', args, { detached: true, stdio: 'ignore' });
-  }
-  return spawn('mpv', [...args, ...MPV_X11_BACKEND_ARGS], {
-    detached: true,
-    stdio: 'ignore',
-    env: applyX11EnvOverrides({ ...process.env }),
-  });
-}
-
 let activeJellyfinRemotePlayback: ActiveJellyfinRemotePlaybackState | null = null;
-let activeJellyfinSubtitleDelayKey: { itemId: string; streamIndex: number } | null = null;
 let jellyfinRemoteLastProgressAtMs = 0;
 let jellyfinMpvAutoLaunchInFlight: Promise<boolean> | null = null;
 let backgroundWarmupsStarted = false;
@@ -951,6 +954,8 @@ const reportFatalError = createFatalErrorReporter({
 
 let forceQuitTimer: ReturnType<typeof setTimeout> | null = null;
 const statsDistPath = path.join(__dirname, '..', 'stats', 'dist');
+// Release builds stage a project TMDB key next to the compiled main process.
+const bundledTmdbApiKey = readBundledTmdbApiKey(__dirname);
 const statsPreloadPath = path.join(__dirname, 'preload-stats.js');
 const statsServerRuntime = createStatsServerRuntime({
   userDataPath: USER_DATA_PATH,
@@ -977,6 +982,7 @@ const statsServerRuntime = createStatsServerRuntime({
   },
   getYomitanAnkiDeckName: () => getCurrentYomitanAnkiDeckNameForRuntime(),
   getAnilistRateLimiter: () => anilistRateLimiter,
+  getBundledTmdbApiKey: () => bundledTmdbApiKey,
   resolveAnkiNoteId: (noteId) => appState.ankiIntegration?.resolveCurrentNoteId(noteId) ?? noteId,
   trackDuplicateNoteIdsForNote: (noteId, duplicateNoteIds) => {
     appState.ankiIntegration?.trackDuplicateNoteIdsForNote(noteId, duplicateNoteIds);
@@ -998,11 +1004,17 @@ function requestAppQuit(): void {
   destroyYomitanSettingsWindow(appState.yomitanSettingsWindow);
   appState.yomitanSettingsWindow = null;
   destroyStatsWindow();
-  stopStatsServer();
+  void stopStatsServer().catch((error: unknown) => {
+    logger.warn('Failed to stop stats server while quitting.', error);
+  });
   if (!forceQuitTimer) {
     forceQuitTimer = setTimeout(() => {
       logger.warn('App quit timed out; forcing process exit.');
-      app.exit(0);
+      void createForceQuitHandler({
+        destroyImmersionTracker: () => appState.immersionTracker?.destroy(),
+        logError: (error) => logger.error('Failed to finalize stats before forced exit.', error),
+        exit: () => app.exit(0),
+      })();
     }, 2000);
   }
   app.quit();
@@ -1427,6 +1439,10 @@ const createCommandLineLauncherRuntimeOptions = () => ({
   cwd: process.cwd(),
   resourcesPath: process.resourcesPath,
   appExePath: process.execPath,
+  appVersion: app.getVersion(),
+  bundledBunPath: app.isPackaged
+    ? path.join(process.resourcesPath, 'bun', process.platform === 'win32' ? 'bun.exe' : 'bun')
+    : undefined,
 });
 const firstRunSetupService = createFirstRunSetupService({
   platform: process.platform,
@@ -1516,7 +1532,7 @@ const firstRunSetupService = createFirstRunSetupService({
   },
   installCommandLineLauncher: async () => {
     const snapshot = await installCommandLineLauncher(createCommandLineLauncherRuntimeOptions());
-    const ok = snapshot.status === 'ready' || snapshot.status === 'installed_bun_missing';
+    const ok = snapshot.status === 'ready' || snapshot.status === 'not_on_path';
     return {
       ok,
       installPath: snapshot.installPath,
@@ -1669,6 +1685,17 @@ const anilistRateLimiter = createAnilistRateLimiter();
 const statsCoverArtFetcher = createCoverArtFetcher(
   anilistRateLimiter,
   createLogger('main:stats-cover-art'),
+  {
+    liveAction: createLiveActionMetadataResolver(
+      createTmdbClient({
+        resolveApiKey: createTmdbApiKeyResolver(
+          () => configService.getConfig().tmdb,
+          () => bundledTmdbApiKey,
+        ),
+      }),
+      createLogger('main:tmdb'),
+    ),
+  },
 );
 const anilistStateRuntime = createAnilistStateRuntime(buildAnilistStateRuntimeMainDepsHandler());
 const configDerivedRuntime = createConfigDerivedRuntime(buildConfigDerivedRuntimeMainDepsHandler());
@@ -1830,28 +1857,31 @@ function withCurrentSubtitleTiming(payload: SubtitleData): SubtitleData {
 }
 
 function captureCurrentPrimarySubtitleMiningContext(): SubtitleMiningContext | null {
-  const canonical = resolveCanonicalPrimarySubtitle({
+  // Mine what the overlay shows, not raw mpv `sub-text`: the raw text lists every active
+  // event, so a finished caption row lingering beside a fresh line would end up on the
+  // card. The parsed view also carries the cue's own timings for the clip range.
+  const resolved = resolvePrimarySubtitle({
     liveText: appState.mpvClient?.currentSubText ?? '',
     currentTimeSec: Number(appState.mpvClient?.currentTimePos),
     cues: appState.activeParsedSubtitleCues,
   });
-  // Same validity bar as the live capture path: an unusable canonical span must fall
+  // Same validity bar as the live capture path: an unusable resolved span must fall
   // back rather than hand mining an empty line or an inverted range.
-  const canonicalText = canonical?.text.trim();
+  const resolvedText = resolved?.text.replace(/\n{2,}/g, '\n').trim();
   if (
-    !canonical ||
-    !canonicalText ||
-    !Number.isFinite(canonical.startTime) ||
-    !Number.isFinite(canonical.endTime) ||
-    canonical.endTime <= canonical.startTime
+    !resolved ||
+    !resolvedText ||
+    !Number.isFinite(resolved.startTime) ||
+    !Number.isFinite(resolved.endTime) ||
+    resolved.endTime <= resolved.startTime
   ) {
     return captureLiveSubtitleMiningContext(appState.mpvClient);
   }
   return {
     source: 'overlay',
-    text: canonicalText,
-    startTime: canonical.startTime,
-    endTime: canonical.endTime,
+    text: resolvedText,
+    startTime: resolved.startTime,
+    endTime: resolved.endTime,
     capturedAtMs: Date.now(),
   };
 }
@@ -1960,13 +1990,54 @@ let lastObservedTimePos = 0;
 let lastObservedPrimarySubtitleTrackId: number | null = null;
 let cancelLinuxMpvFullscreenOverlayRefreshBurst: CancelLinuxMpvFullscreenOverlayRefreshBurst | null =
   null;
-let linuxVisibleOverlayWindowMode: LinuxVisibleOverlayWindowMode = 'managed';
-let linuxTrackedMpvFullscreen = false;
-let linuxTrackedMpvFullscreenChangedAtMs = 0;
-let linuxVisibleOverlayOwnerBindingKey: string | null = null;
-let linuxVisibleOverlayWindowModeSwitchToken = 0;
+const linuxOverlayModeRuntime = createLinuxOverlayModeRuntime({
+  isEnabled: shouldRunLinuxOverlayZOrderKeepAlive,
+  isVisible: () => overlayManager.getVisibleOverlayVisible(),
+  getWindow: () => overlayManager.getMainWindow(),
+  clearWindow: () => overlayManager.setMainWindow(null),
+  createWindow: () => {
+    visibleOverlayInteractionRuntime.resetVisibleOverlayInputState();
+    createMainWindow();
+  },
+  refreshWindow: () => {
+    const trackedGeometry = overlayGeometryRuntime.getCurrentTrackedOverlayGeometry();
+    if (trackedGeometry) overlayManager.setOverlayWindowBounds(trackedGeometry);
+    overlayVisibilityRuntime.updateVisibleOverlayVisibility();
+    void ensureOverlayMpvSubtitlesHidden();
+    if (appState.currentSubText.trim()) {
+      subtitleProcessingController.refreshCurrentSubtitle(appState.currentSubText);
+    }
+  },
+  now: Date.now,
+  logDebug: (message) => logger.debug(message),
+});
 let subtitleSidebarRequestedOpen = false;
 const SEEK_THRESHOLD_SECONDS = 3;
+const EXPLICIT_SEEK_INTENT_TTL_MS = 2000;
+let explicitSeekIntentExpiresAtMs = 0;
+
+function isExplicitMpvSeekCommand(command: readonly (string | number)[]): boolean {
+  return command[0] === 'seek' || command[0] === 'sub-seek';
+}
+
+function sendRendererMpvCommand(rawCommand: (string | number)[]): void {
+  const command =
+    resolveSanitizedSubtitleSeekCommand(
+      rawCommand,
+      appState.activeParsedSubtitleCues,
+      appState.mpvClient?.currentTimePos ?? Number.NaN,
+    ) ?? rawCommand;
+  if (isExplicitMpvSeekCommand(command)) {
+    explicitSeekIntentExpiresAtMs = Date.now() + EXPLICIT_SEEK_INTENT_TTL_MS;
+  }
+  sendMpvCommandRuntime(appState.mpvClient, command);
+}
+
+function consumeExplicitSeekIntent(): boolean {
+  const pending = explicitSeekIntentExpiresAtMs >= Date.now();
+  explicitSeekIntentExpiresAtMs = 0;
+  return pending;
+}
 
 const autoplaySubtitlePrimingRuntime = createAutoplaySubtitlePrimingRuntime({
   getCurrentMediaPath: () => appState.currentMediaPath,
@@ -2037,10 +2108,12 @@ const subtitlePrefetchInitController = createSubtitlePrefetchInitController({
     }
   },
 });
+const cachedInternalSubtitleTrackExtractor = createCachedInternalSubtitleTrackExtractor();
+const detectRemoteMediaPath = createRemoteMediaPathDetector();
 const resolveActiveSubtitleSidebarSourceHandler = createResolveActiveSubtitleSidebarSourceHandler({
   getFfmpegPath: () => configService.getConfig().subsync.ffmpeg_path.trim() || 'ffmpeg',
   extractInternalSubtitleTrack: (ffmpegPath, videoPath, track) =>
-    extractInternalSubtitleTrackToTempFile(ffmpegPath, videoPath, track),
+    cachedInternalSubtitleTrackExtractor.extract(ffmpegPath, videoPath, track),
   logDebug: (message) => logger.debug(message),
 });
 
@@ -2069,8 +2142,8 @@ const refreshSubtitlePrefetchFromActiveTrackHandler =
     // Remote media has no extractable on-disk track to fall back to, so a transient
     // resolve miss (sid briefly 'no', a cycle onto an embedded stream track) would
     // otherwise drop a working cue list for the rest of the episode.
-    shouldKeepExistingCuesOnMissingSource: (videoPath) =>
-      isYoutubeMediaPath(videoPath) || isRemoteMediaPath(videoPath),
+    shouldKeepExistingCuesOnMissingSource: async (videoPath) =>
+      isYoutubeMediaPath(videoPath) || (await detectRemoteMediaPath(videoPath)),
     subtitlePrefetchInitController,
     resolveActiveSubtitleSidebarSource: (input) => resolveActiveSubtitleSidebarSourceHandler(input),
     logDebug: (message) => logger.debug(message),
@@ -2462,7 +2535,6 @@ const fieldGroupingOverlayRuntime = createFieldGroupingOverlayRuntime<OverlayHos
 const createFieldGroupingCallback = fieldGroupingOverlayRuntime.createFieldGroupingCallback;
 
 const SUBTITLE_POSITIONS_DIR = path.join(CONFIG_DIR, 'subtitle-positions');
-const JELLYFIN_SUBTITLE_DELAYS_PATH = path.join(CONFIG_DIR, 'jellyfin-subtitle-delays.json');
 
 const mediaRuntime = createMediaRuntimeService(
   createBuildMediaRuntimeMainDepsHandler({
@@ -2634,6 +2706,12 @@ const characterDictionaryAutoSyncRuntime = createCharacterDictionaryAutoSyncRunt
 const characterDictionaryImageLookup = createCharacterDictionaryImageLookup({
   userDataPath: USER_DATA_PATH,
   getCurrentMediaId: () => characterDictionaryAutoSyncRuntime.getCurrentMediaId(),
+  onIndexReady: () => refreshCurrentSubtitleAnnotations(),
+  onIndexReadyError: (error) =>
+    logger.warn(
+      'Failed to refresh subtitle annotations after character portrait index became ready.',
+      error,
+    ),
 });
 
 // Lets the Yomitan scan runtime skip name lookups at positions where no
@@ -2694,7 +2772,7 @@ const overlayVisibilityRuntime = createOverlayVisibilityRuntimeService(
     },
     hideNonNativeOverlayWhenTargetUnfocused: () =>
       shouldRunLinuxOverlayZOrderKeepAlive() &&
-      linuxVisibleOverlayWindowMode === 'fullscreen-override',
+      linuxOverlayModeRuntime.mode === 'fullscreen-override',
     resolveFallbackBounds: () => {
       const cursorPoint = screen.getCursorScreenPoint();
       const display = screen.getDisplayNearestPoint(cursorPoint);
@@ -2740,9 +2818,9 @@ const visibleOverlayInteractionRuntime = createVisibleOverlayInteractionRuntime(
   getBackendOverride: () => appState.backendOverride,
   getInitialArgs: () => appState.initialArgs,
   getOverlayRuntimeInitialized: () => appState.overlayRuntimeInitialized,
-  getLinuxVisibleOverlayWindowMode: () => linuxVisibleOverlayWindowMode,
+  getLinuxVisibleOverlayWindowMode: () => linuxOverlayModeRuntime.mode,
   setLinuxVisibleOverlayOwnerBindingKey: (key) => {
-    linuxVisibleOverlayOwnerBindingKey = key;
+    linuxOverlayModeRuntime.ownerBindingKey = key;
   },
   bindVisibleOverlayToTrackedX11Window: (window) =>
     overlayGeometryRuntime.bindVisibleOverlayToTrackedX11Window(window),
@@ -2861,6 +2939,59 @@ function createOverlayHostedModalOpenDeps(): {
   };
 }
 
+const mediaTimingFrameExtractor = createMediaTimingFrameExtractor();
+const mediaTimingReviewRuntime = createMediaTimingReviewRuntime({
+  getMpvClient: () => appState.mpvClient,
+  getCurrentMediaPath: () =>
+    appState.currentMediaPath?.trim() || appState.mpvClient?.currentVideoPath?.trim() || null,
+  getMpvExecutablePath: () =>
+    configService.getConfig().mpv.executablePath || process.env.SUBMINER_MPV_PATH?.trim() || '',
+  createPreviewSession: () => new MediaTimingPreviewSession(),
+  generateWaveform: (options) => generateSpeechWaveform(options),
+  generateFrame: (options) => mediaTimingFrameExtractor.generate(options),
+  clearFrameCache: () => mediaTimingFrameExtractor.clear(),
+  resolveVideoSource: () =>
+    resolveMediaGenerationInput(appState.mpvClient, 'video', {
+      getCachedMediaPath: (currentVideoPath, kind) =>
+        getCachedYoutubeMediaPathForCurrentPlayback(currentVideoPath, kind),
+      remoteCacheMode: shouldRequireYoutubeMediaCacheForCurrentPlayback() ? 'required' : 'optional',
+    }),
+  resolveMediaSource: async () => {
+    const resolved = await resolveMediaGenerationInput(appState.mpvClient, 'audio', {
+      getCachedMediaPath: (currentVideoPath, kind) =>
+        getCachedYoutubeMediaPathForCurrentPlayback(currentVideoPath, kind),
+      remoteCacheMode: shouldRequireYoutubeMediaCacheForCurrentPlayback() ? 'required' : 'optional',
+    });
+    return resolved
+      ? {
+          path: resolved.path,
+          ...(resolved.inputOptions ? { inputOptions: resolved.inputOptions } : {}),
+          singleResolvedStream: resolved.singleResolvedStream,
+        }
+      : null;
+  },
+  acquireMediaWindow: (source, range) => getSharedRemoteMediaWindowCache().acquire(source, range),
+  getSubtitleContextLines: (range) =>
+    collectMediaTimingContextLines({
+      cues: appState.activeParsedSubtitleCues,
+      fallbackPrevious: appState.subtitleTimingTracker?.getRecentEntries(40) ?? [],
+      startTime: range.startTime,
+      endTime: range.endTime,
+    }),
+  openModal: (payload, signal) =>
+    openMediaTimingReviewModal(createOverlayHostedModalOpenDeps(), payload, signal),
+  onPreviewEnded: (reviewId) => {
+    // The review may live in either overlay window; the renderer ignores foreign review ids.
+    for (const window of [overlayManager.getMainWindow(), overlayManager.getModalWindow()]) {
+      if (window && !window.isDestroyed()) {
+        window.webContents.send(IPC_CHANNELS.event.mediaTimingReviewPreviewEnded, reviewId);
+      }
+    }
+  },
+  showStatus: (message) =>
+    overlayNotificationsRuntime.showConfiguredStatusNotification(message, { variant: 'warning' }),
+});
+
 function openOverlayHostedModalWithOsd(
   openModal: (deps: ReturnType<typeof createOverlayHostedModalOpenDeps>) => Promise<boolean>,
   unavailableMessage: string,
@@ -2906,6 +3037,14 @@ function openTsukihimeOverlay(): void {
   );
 }
 
+function openSubtitleGenerationOverlay(): void {
+  openOverlayHostedModalWithOsd(
+    openSubtitleGenerationModal,
+    'Subtitle generation overlay unavailable.',
+    'Failed to open subtitle generation overlay.',
+  );
+}
+
 function openSessionHelpOverlay(): void {
   openOverlayHostedModalWithOsd(
     openSessionHelpModalRuntime,
@@ -3036,18 +3175,20 @@ const {
     sleep: (delayMs) => new Promise((resolve) => setTimeout(resolve, delayMs)),
   },
   launchMpvIdleForJellyfinPlaybackMainDeps: {
+    getMpvExecutablePath: () =>
+      resolveMpvExecutablePath(configService.getConfig().mpv.executablePath),
     getSocketPath: () => appState.mpvSocketPath,
     getLaunchMode: () => configService.getConfig().mpv.launchMode,
     platform: process.platform,
     execPath: process.execPath,
     getRuntimePluginEntrypoint: () => resolveBundledMpvRuntimePluginEntrypoint(),
-    getInstalledPluginDetection: () =>
+    getInstalledPluginDetection: (mpvExecutablePath) =>
       detectInstalledMpvPlugin({
         platform: process.platform,
         homeDir: os.homedir(),
         xdgConfigHome: process.env.XDG_CONFIG_HOME,
         appDataDir: app.getPath('appData'),
-        mpvExecutablePath: configService.getConfig().mpv.executablePath,
+        mpvExecutablePath,
       }),
     getPluginRuntimeConfig: () => getMpvPluginRuntimeConfig(),
     getDefaultMpvLogPath: () => (isLogFileEnabled('mpv') ? DEFAULT_MPV_LOG_PATH : ''),
@@ -3055,7 +3196,7 @@ const {
     removeSocketPath: (socketPath) => {
       fs.rmSync(socketPath, { force: true });
     },
-    spawnMpv: (args) => spawnManagedMpvProcess(args),
+    spawnMpv: spawnMpvProcess,
     logWarn: (message, error) => logger.warn(message, error),
     logInfo: (message) => logger.info(message),
   },
@@ -3082,23 +3223,6 @@ const {
     wait: (ms) => new Promise<void>((resolve) => setTimeout(resolve, ms)),
     cacheSubtitleTrack: (track) => jellyfinSubtitleCacheIo.cacheSubtitleTrack(track),
     cleanupCachedSubtitles: (dirs) => jellyfinSubtitleCacheIo.cleanupCachedSubtitles(dirs),
-    getSavedSubtitleDelay: (itemId, streamIndex) =>
-      loadJellyfinSubtitleDelay({
-        filePath: JELLYFIN_SUBTITLE_DELAYS_PATH,
-        itemId,
-        streamIndex,
-      }),
-    setActiveSubtitleDelayKey: (key) => {
-      activeJellyfinSubtitleDelayKey = key;
-    },
-    loadSubtitleSourceText,
-    saveSubtitleDelay: (itemId, streamIndex, delaySeconds) =>
-      saveJellyfinSubtitleDelay({
-        filePath: JELLYFIN_SUBTITLE_DELAYS_PATH,
-        itemId,
-        streamIndex,
-        delaySeconds,
-      }),
     initSubtitlePrefetch: (sourcePath) =>
       subtitlePrefetchRuntime.refreshSubtitleSidebarFromSource(sourcePath),
     logDebug: (message, error) => {
@@ -3164,7 +3288,6 @@ const {
     getActivePlayback: () => activeJellyfinRemotePlayback,
     clearActivePlayback: () => {
       activeJellyfinRemotePlayback = null;
-      activeJellyfinSubtitleDelayKey = null;
     },
     getSession: () => appState.jellyfinRemoteSession,
     getNow: () => Date.now(),
@@ -3895,6 +4018,7 @@ const {
     clearWindowsVisibleOverlayForegroundPollLoop: () =>
       visibleOverlayInteractionRuntime.clearWindowsVisibleOverlayForegroundPollLoop(),
     clearLinuxMpvFullscreenOverlayRefreshTimeouts: () => {
+      linuxOverlayModeRuntime.cancelPendingTransition();
       cancelLinuxMpvFullscreenOverlayRefreshBurst = null;
       clearLinuxMpvFullscreenOverlayRefreshTimeouts();
     },
@@ -3918,8 +4042,8 @@ const {
     },
     getSubtitleTimingTracker: () => appState.subtitleTimingTracker,
     getImmersionTracker: () => appState.immersionTracker,
+    stopStatsServer: () => stopStatsServer(),
     clearImmersionTracker: () => {
-      stopStatsServer();
       appState.statsServer = null;
       appState.immersionTracker = null;
     },
@@ -3941,8 +4065,10 @@ const {
       appState.yomitanSettingsWindow = null;
     },
     stopJellyfinRemoteSession: () => stopJellyfinRemoteSession(),
+    cleanupInternalSubtitleTrackCache: () => cachedInternalSubtitleTrackExtractor.clear(),
     cleanupYoutubeSubtitleTempDirs: () => youtubeFlowRuntime.cleanupSubtitleTempDirs(),
     cleanupYoutubeMediaCache: () => youtubeMediaCache.cleanup(),
+    cleanupRemoteMediaWindows: () => getSharedRemoteMediaWindowCache().cleanup(),
     cleanupJellyfinSubtitleCache: () => cleanupJellyfinSubtitleCache(),
     stopDiscordPresenceService: () => {
       void appState.discordPresenceService?.stop();
@@ -4006,7 +4132,9 @@ const immersionTrackerStartupMainDeps: Parameters<
     const trackerHasChanged =
       appState.immersionTracker !== null && appState.immersionTracker !== tracker;
     if (trackerHasChanged && appState.statsServer) {
-      stopStatsServer();
+      void stopStatsServer().catch((error: unknown) => {
+        logger.warn('Failed to stop stats server while replacing immersion tracker.', error);
+      });
       appState.statsServer = null;
     }
 
@@ -4017,15 +4145,21 @@ const immersionTrackerStartupMainDeps: Parameters<
       if (!appState.statsServer) {
         const config = configService.getConfig();
         if (config.stats.autoStartServer) {
-          ensureStatsServerStarted();
+          void ensureStatsServerStarted().catch((error: unknown) => {
+            logger.warn('Failed to auto-start stats server.', error);
+          });
         }
       }
 
       // Register stats overlay toggle IPC handler (idempotent)
       registerStatsOverlayToggle({
-        staticDir: statsDistPath,
         preloadPath: statsPreloadPath,
-        getApiBaseUrl: () => ensureStatsServerStarted().url,
+        getApiBaseUrl: async () => (await ensureStatsServerStarted()).url,
+        onStartupError: (error) =>
+          overlayNotificationsRuntime.showConfiguredStatusNotification(
+            `Stats server startup failed: ${error instanceof Error ? error.message : String(error)}`,
+            { title: 'Stats' },
+          ),
         getToggleKey: () => configService.getConfig().stats.toggleKey,
         resolveBounds: () => overlayGeometryRuntime.getCurrentOverlayGeometry(),
         onVisibilityChanged: (visible) => {
@@ -4058,7 +4192,7 @@ const recordTrackedCardsMined = (count: number, noteIds?: number[]): void => {
   ensureImmersionTrackerStarted();
   appState.immersionTracker?.recordCardsMined(count, noteIds);
 };
-const refreshCurrentSubtitleAfterKnownWordUpdate = (): void => {
+function refreshCurrentSubtitleAnnotations(): void {
   const hasCurrentSubtitle = appState.currentSubText.trim().length > 0;
   if (hasCurrentSubtitle) {
     subtitlePrefetchService?.pause();
@@ -4069,7 +4203,7 @@ const refreshCurrentSubtitleAfterKnownWordUpdate = (): void => {
     // Idle controller: no settle is coming to release the pause above.
     subtitlePrefetchService?.resume();
   }
-};
+}
 let hasAttemptedImmersionTrackerStartup = false;
 const ensureImmersionTrackerStarted = (): void => {
   if (hasAttemptedImmersionTrackerStartup || appState.immersionTracker) {
@@ -4107,7 +4241,7 @@ const runStatsCliCommand = createRunStatsCliCommandHandler({
     await createMecabTokenizerAndCheck();
   },
   getImmersionTracker: () => appState.immersionTracker,
-  ensureStatsServerStarted: () => statsStartupRuntime.ensureStatsServerStarted().url,
+  ensureStatsServerStarted: async () => (await statsStartupRuntime.ensureStatsServerStarted()).url,
   ensureBackgroundStatsServerStarted: () =>
     statsStartupRuntime.ensureBackgroundStatsServerStarted(),
   stopBackgroundStatsServer: () => statsStartupRuntime.stopBackgroundStatsServer(),
@@ -4447,6 +4581,7 @@ const {
       maybeStartOverlayLoadingOsd();
       flushQueuedMpvOsdNotifications();
       secondarySubtitleTrackController.scheduleRefresh(0);
+      void refreshMpvSessionBindings();
       if (appState.sessionBindingsInitialized) {
         sendMpvCommandRuntime(appState.mpvClient, [
           'script-message',
@@ -4501,6 +4636,7 @@ const {
         appState.activeParsedSubtitleMediaPath,
       );
       if ((normalizedPath || null) !== previousPath) {
+        cachedInternalSubtitleTrackExtractor.clear();
         secondarySubtitleTrackController.reset();
         const resetSubtitlePayload = { text: '', tokens: null };
         const frequencyDictionary = configService.getConfig().subtitleStyle.frequencyDictionary;
@@ -4519,7 +4655,6 @@ const {
           appState.activeParsedSubtitleSource = null;
           appState.activeParsedSubtitleMediaPath = null;
         }
-        activeJellyfinSubtitleDelayKey = null;
         overlayManager.broadcastToOverlayWindows('subtitle:set', resetSubtitlePayload);
         subtitleWsService.broadcast(resetSubtitlePayload, frequencyOptions);
         annotationSubtitleWsService.broadcast(resetSubtitlePayload, frequencyOptions);
@@ -4585,6 +4720,7 @@ const {
     reportJellyfinRemoteProgress: (forceImmediate) => {
       void reportJellyfinRemoteProgress(forceImmediate);
     },
+    consumeExplicitSeek: () => consumeExplicitSeekIntent(),
     onTimePosUpdate: (time) => {
       const delta = time - lastObservedTimePos;
       if (subtitlePrefetchService && (delta > SEEK_THRESHOLD_SECONDS || delta < 0)) {
@@ -4603,7 +4739,7 @@ const {
           },
           overlayVisibilityRuntime,
           syncVisibleOverlayMpvFullscreenMode: (nextFullscreen) =>
-            syncLinuxVisibleOverlayMpvFullscreenMode(nextFullscreen),
+            linuxOverlayModeRuntime.sync(nextFullscreen),
           getOverlayInteractionActive: () =>
             visibleOverlayInteractionRuntime.getVisibleOverlayInteractionActive() ||
             visibleOverlayInteractionRuntime.getLinuxOverlayInputShapeActive(),
@@ -4915,14 +5051,14 @@ const overlayGeometryRuntime = createOverlayGeometryRuntime({
   getTrackedWindowNativeId: () => appState.windowTracker?.getTargetWindowNativeId?.(),
   getStatsOverlayVisible: () => appState.statsOverlayVisible,
   getOverlayForegroundSeparateWindows: () => getOverlayForegroundSeparateWindows(),
-  getLinuxVisibleOverlayWindowMode: () => linuxVisibleOverlayWindowMode,
-  getLinuxTrackedMpvFullscreen: () => linuxTrackedMpvFullscreen,
-  getLinuxTrackedMpvFullscreenChangedAtMs: () => linuxTrackedMpvFullscreenChangedAtMs,
+  getLinuxVisibleOverlayWindowMode: () => linuxOverlayModeRuntime.mode,
+  getLinuxTrackedMpvFullscreen: () => linuxOverlayModeRuntime.fullscreen,
+  getLinuxTrackedMpvFullscreenChangedAtMs: () => linuxOverlayModeRuntime.fullscreenChangedAtMs,
   syncLinuxVisibleOverlayMpvFullscreenMode: (fullscreen) =>
-    syncLinuxVisibleOverlayMpvFullscreenMode(fullscreen),
-  getLinuxVisibleOverlayOwnerBindingKey: () => linuxVisibleOverlayOwnerBindingKey,
+    linuxOverlayModeRuntime.sync(fullscreen),
+  getLinuxVisibleOverlayOwnerBindingKey: () => linuxOverlayModeRuntime.ownerBindingKey,
   setLinuxVisibleOverlayOwnerBindingKey: (key) => {
-    linuxVisibleOverlayOwnerBindingKey = key;
+    linuxOverlayModeRuntime.ownerBindingKey = key;
   },
   clearVisibleOverlayX11OwnerBinding: (window) =>
     visibleOverlayInteractionRuntime.clearVisibleOverlayX11OwnerBinding(window),
@@ -5007,83 +5143,11 @@ function createMainWindow(): BrowserWindow {
   return window;
 }
 
-function createLinuxVisibleOverlayWindowForCurrentMode(token: number, fullscreen: boolean): void {
-  if (token !== linuxVisibleOverlayWindowModeSwitchToken) {
-    return;
-  }
-  if (!overlayManager.getVisibleOverlayVisible()) {
-    return;
-  }
-  const existingWindow = overlayManager.getMainWindow();
-  if (existingWindow && !existingWindow.isDestroyed()) {
-    return;
-  }
-
-  visibleOverlayInteractionRuntime.resetVisibleOverlayInputState();
-  createMainWindow();
-  const trackedGeometry = overlayGeometryRuntime.getCurrentTrackedOverlayGeometry();
-  if (trackedGeometry) {
-    overlayManager.setOverlayWindowBounds(trackedGeometry);
-  }
-  overlayVisibilityRuntime.updateVisibleOverlayVisibility();
-  void ensureOverlayMpvSubtitlesHidden();
-  if (appState.currentSubText.trim()) {
-    subtitleProcessingController.refreshCurrentSubtitle(appState.currentSubText);
-  }
-  logger.debug(
-    `Switched Linux visible overlay window mode to ${linuxVisibleOverlayWindowMode} for mpv fullscreen=${fullscreen}`,
-  );
-}
-
-function syncLinuxVisibleOverlayMpvFullscreenMode(fullscreen: boolean): void {
-  if (!shouldRunLinuxOverlayZOrderKeepAlive()) {
-    return;
-  }
-  if (linuxTrackedMpvFullscreen !== fullscreen) {
-    linuxTrackedMpvFullscreenChangedAtMs = Date.now();
-  }
-  linuxTrackedMpvFullscreen = fullscreen;
-  const currentWindow = overlayManager.getMainWindow();
-  const hasLiveWindow = Boolean(currentWindow && !currentWindow.isDestroyed());
-  const action = resolveLinuxVisibleOverlayWindowModeAction({
-    currentMode: linuxVisibleOverlayWindowMode,
-    fullscreen,
-    hasLiveWindow,
-    visibleOverlayVisible: overlayManager.getVisibleOverlayVisible(),
-  });
-
-  linuxVisibleOverlayWindowMode = action.nextMode;
-  linuxVisibleOverlayOwnerBindingKey = null;
-  linuxVisibleOverlayWindowModeSwitchToken += 1;
-  const token = linuxVisibleOverlayWindowModeSwitchToken;
-  if (!action.shouldCreateWindow && !action.shouldDestroyCurrentWindow) {
-    return;
-  }
-
-  const previousWindow = currentWindow;
-  if (action.shouldDestroyCurrentWindow && previousWindow && !previousWindow.isDestroyed()) {
-    previousWindow.once('closed', () => {
-      if (overlayManager.getMainWindow() === previousWindow) {
-        overlayManager.setMainWindow(null);
-      }
-      if (action.createWindowTiming === 'after-current-destroyed') {
-        createLinuxVisibleOverlayWindowForCurrentMode(token, fullscreen);
-      }
-    });
-    previousWindow.hide();
-    previousWindow.destroy();
-  }
-
-  if (!action.shouldCreateWindow) {
-    logger.debug(
-      `Recorded Linux visible overlay window mode ${action.nextMode} for hidden mpv fullscreen=${fullscreen}`,
-    );
-    return;
-  }
-
-  if (action.createWindowTiming === 'now') {
-    createLinuxVisibleOverlayWindowForCurrentMode(token, fullscreen);
-  }
+function generateMiningSentenceFurigana(
+  text: string,
+  highlightedText?: string,
+): Promise<string | null> {
+  return generateSentenceFurigana(text, highlightedText, getYomitanParserRuntimeDeps(), logger);
 }
 
 function initializeOverlayRuntime(): void {
@@ -5092,10 +5156,10 @@ function initializeOverlayRuntime(): void {
     overlayModalRuntime.primeModalWindow();
   }
   appState.ankiIntegration?.setRecordCardsMinedCallback(recordTrackedCardsMined);
-  appState.ankiIntegration?.setKnownWordCacheUpdatedCallback(
-    refreshCurrentSubtitleAfterKnownWordUpdate,
-  );
+  appState.ankiIntegration?.setKnownWordCacheUpdatedCallback(refreshCurrentSubtitleAnnotations);
   appState.ankiIntegration?.setSubtitleMiningContextConsumer(consumePendingSubtitleMiningContext);
+  appState.ankiIntegration?.setMediaTimingReviewCallback(mediaTimingReviewRuntime.requestReview);
+  appState.ankiIntegration?.setSentenceFuriganaGenerator(generateMiningSentenceFurigana);
   syncOverlayMpvSubtitleSuppression();
 }
 
@@ -5178,20 +5242,32 @@ const {
   },
 });
 
-const { persistSessionBindings, refreshCurrentSessionBindings } = createSessionBindingsRuntime({
-  configDir: CONFIG_DIR,
-  getKeybindings: () => appState.keybindings,
-  getConfiguredShortcuts: () => getConfiguredShortcuts(),
-  getResolvedConfig: () => configService.getConfig(),
-  getMpvClient: () => appState.mpvClient,
-  setSessionBindings: (bindings) => {
-    appState.sessionBindings = bindings;
-  },
-  setSessionBindingsInitialized: (initialized) => {
-    appState.sessionBindingsInitialized = initialized;
-  },
-  logWarn: (message) => logger.warn(message),
-});
+const { persistSessionBindings, refreshCurrentSessionBindings, refreshMpvSessionBindings } =
+  createSessionBindingsRuntime({
+    configDir: CONFIG_DIR,
+    getKeybindings: () => appState.keybindings,
+    getConfiguredShortcuts: () => getConfiguredShortcuts(),
+    getResolvedConfig: () => configService.getConfig(),
+    getMpvClient: () => appState.mpvClient,
+    setSessionBindings: (bindings) => {
+      appState.sessionBindings = bindings;
+    },
+    setSessionBindingsInitialized: (initialized) => {
+      appState.sessionBindingsInitialized = initialized;
+    },
+    logWarn: (message) => logger.warn(message),
+    onBindingsChanged: (bindings) =>
+      overlayManager.broadcastToOverlayWindows(IPC_CHANNELS.event.sessionBindingsChanged, bindings),
+    onWarning: (warning) => {
+      if (warning.kind !== 'conflict') return;
+      overlayNotificationsRuntime.showOverlayNotification({
+        id: `session-binding-conflict:${warning.path}`,
+        title: 'Shortcut conflict',
+        body: warning.message,
+        variant: 'warning',
+      });
+    },
+  });
 
 const { flushMpvLog, showMpvOsd } = createMpvOsdRuntimeHandlers({
   appendToMpvLogMainDeps: {
@@ -5229,7 +5305,7 @@ const { getChangelogSnapshot } = createChangelogRuntime({
   logWarn: (message) => logger.warn(message),
 });
 
-const { getUpdateService } = createUpdateServiceRuntime({
+const { getUpdateService, takePendingLauncherMigrationPath } = createUpdateServiceRuntime({
   userDataPath: USER_DATA_PATH,
   getUpdatesConfig: () => configService.getConfig().updates,
   logInfo: (message) => logger.info(message),
@@ -5399,11 +5475,15 @@ const appendClipboardVideoToQueueHandler = createAppendClipboardVideoToQueueHand
 
 async function dispatchSessionAction(request: SessionActionDispatchRequest): Promise<void> {
   await dispatchSessionActionCore(request, {
-    toggleStatsOverlay: () =>
-      toggleStatsOverlayWindow({
-        staticDir: statsDistPath,
+    toggleStatsOverlay: async () =>
+      await toggleStatsOverlayWindow({
         preloadPath: statsPreloadPath,
-        getApiBaseUrl: () => ensureStatsServerStarted().url,
+        getApiBaseUrl: async () => (await ensureStatsServerStarted()).url,
+        onStartupError: (error) =>
+          overlayNotificationsRuntime.showConfiguredStatusNotification(
+            `Stats server startup failed: ${error instanceof Error ? error.message : String(error)}`,
+            { title: 'Stats' },
+          ),
         getToggleKey: () => configService.getConfig().stats.toggleKey,
         resolveBounds: () => overlayGeometryRuntime.getCurrentOverlayGeometry(),
         onVisibilityChanged: (visible) => {
@@ -5442,6 +5522,15 @@ async function dispatchSessionAction(request: SessionActionDispatchRequest): Pro
     openJimaku: () => openJimakuOverlay(),
     openTsukihime: () => openTsukihimeOverlay(),
     openSessionHelp: () => openSessionHelpOverlay(),
+    openSubtitleSelection: () => {
+      if (!configService.getConfig().subtitleSelection.enabled) return;
+      openOverlayHostedModalWithOsd(
+        openSubtitleSelectionModal,
+        'Subtitle selection overlay unavailable.',
+        'Failed to open subtitle selection overlay.',
+      );
+    },
+    openSubtitleGeneration: () => openSubtitleGenerationOverlay(),
     openCharacterDictionaryManager: () => openCharacterDictionaryManagerOverlay(),
     openControllerSelect: () => openControllerSelectOverlay(),
     openControllerDebug: () => openControllerDebugOverlay(),
@@ -5492,8 +5581,7 @@ const { registerIpcRuntimeHandlers } = composeIpcRuntimeHandlers({
     showPlaybackFeedback: (text: string) => showConfiguredPlaybackFeedback(text),
     replayCurrentSubtitle: () => replayCurrentSubtitleRuntime(appState.mpvClient),
     playNextSubtitle: () => playNextSubtitleRuntime(appState.mpvClient),
-    sendMpvCommand: (rawCommand: (string | number)[]) =>
-      sendMpvCommandRuntime(appState.mpvClient, rawCommand),
+    sendMpvCommand: (rawCommand: (string | number)[]) => sendRendererMpvCommand(rawCommand),
     getMpvClient: () => appState.mpvClient,
     isMpvConnected: () => Boolean(appState.mpvClient && appState.mpvClient.connected),
     hasRuntimeOptionsManager: () => appState.runtimeOptionsManager !== null,
@@ -5506,6 +5594,11 @@ const { registerIpcRuntimeHandlers } = composeIpcRuntimeHandlers({
       showMpvOsd: (text: string) => showConfiguredPlaybackFeedback(text),
     },
     mainDeps: {
+      previewMediaTimingReview: (request) => mediaTimingReviewRuntime.previewRange(request),
+      getMediaTimingReviewFrame: (request) => mediaTimingReviewRuntime.getFrame(request),
+      getMediaTimingReviewWaveform: (request) => mediaTimingReviewRuntime.getWaveform(request),
+      stopMediaTimingReviewPreview: (reviewId) => mediaTimingReviewRuntime.stopPreview(reviewId),
+      resolveMediaTimingReview: (request) => mediaTimingReviewRuntime.resolveReview(request),
       getMainWindow: () => overlayManager.getMainWindow(),
       getVisibleOverlayVisibility: () => overlayManager.getVisibleOverlayVisible(),
       focusMainWindow: () => {
@@ -5539,6 +5632,9 @@ const { registerIpcRuntimeHandlers } = composeIpcRuntimeHandlers({
         }
       },
       onOverlayModalClosed: (modal, senderWindow) => {
+        if (modal === 'media-timing-review') {
+          void mediaTimingReviewRuntime.dispose();
+        }
         if (modal === 'subtitle-sidebar' && senderWindow === overlayManager.getMainWindow()) {
           subtitleSidebarRequestedOpen = false;
         }
@@ -5656,6 +5752,10 @@ const { registerIpcRuntimeHandlers } = composeIpcRuntimeHandlers({
         const client = appState.mpvClient;
         if (!client?.connected) {
           return {
+            sourceKey: JSON.stringify([
+              appState.activeParsedSubtitleMediaPath,
+              appState.activeParsedSubtitleSource,
+            ]),
             cues: appState.activeParsedSubtitleCues,
             currentTimeSec,
             currentSubtitle,
@@ -5675,6 +5775,10 @@ const { registerIpcRuntimeHandlers } = composeIpcRuntimeHandlers({
           const videoPath = typeof videoPathRaw === 'string' ? videoPathRaw : '';
           if (!videoPath) {
             return {
+              sourceKey: JSON.stringify([
+                appState.activeParsedSubtitleMediaPath,
+                appState.activeParsedSubtitleSource,
+              ]),
               cues: appState.activeParsedSubtitleCues,
               currentTimeSec,
               currentSubtitle,
@@ -5689,6 +5793,10 @@ const { registerIpcRuntimeHandlers } = composeIpcRuntimeHandlers({
             })
           ) {
             return {
+              sourceKey: JSON.stringify([
+                appState.activeParsedSubtitleMediaPath,
+                appState.activeParsedSubtitleSource,
+              ]),
               cues: appState.activeParsedSubtitleCues,
               currentTimeSec,
               currentSubtitle,
@@ -5705,6 +5813,10 @@ const { registerIpcRuntimeHandlers } = composeIpcRuntimeHandlers({
           });
           if (!resolvedSource) {
             return {
+              sourceKey: JSON.stringify([
+                appState.activeParsedSubtitleMediaPath,
+                appState.activeParsedSubtitleSource,
+              ]),
               cues: appState.activeParsedSubtitleCues,
               currentTimeSec,
               currentSubtitle,
@@ -5715,6 +5827,10 @@ const { registerIpcRuntimeHandlers } = composeIpcRuntimeHandlers({
           try {
             if (appState.activeParsedSubtitleSource === resolvedSource.sourceKey) {
               return {
+                sourceKey: JSON.stringify([
+                  appState.activeParsedSubtitleMediaPath,
+                  appState.activeParsedSubtitleSource,
+                ]),
                 cues: appState.activeParsedSubtitleCues,
                 currentTimeSec,
                 currentSubtitle,
@@ -5728,6 +5844,10 @@ const { registerIpcRuntimeHandlers } = composeIpcRuntimeHandlers({
             appState.activeParsedSubtitleSource = resolvedSource.sourceKey;
             appState.activeParsedSubtitleMediaPath = videoPath || null;
             return {
+              sourceKey: JSON.stringify([
+                appState.activeParsedSubtitleMediaPath,
+                appState.activeParsedSubtitleSource,
+              ]),
               cues,
               currentTimeSec,
               currentSubtitle,
@@ -5738,6 +5858,10 @@ const { registerIpcRuntimeHandlers } = composeIpcRuntimeHandlers({
           }
         } catch {
           return {
+            sourceKey: JSON.stringify([
+              appState.activeParsedSubtitleMediaPath,
+              appState.activeParsedSubtitleSource,
+            ]),
             cues: appState.activeParsedSubtitleCues,
             currentTimeSec,
             currentSubtitle,
@@ -5758,7 +5882,23 @@ const { registerIpcRuntimeHandlers } = composeIpcRuntimeHandlers({
       saveSubtitlePosition: (position) => saveSubtitlePosition(position),
       getMecabTokenizer: () => appState.mecabTokenizer,
       getKeybindings: () => appState.keybindings,
-      getSessionBindings: () => appState.sessionBindings,
+      getMpvInputBindings: async () => {
+        await refreshMpvSessionBindings();
+        return readMpvInputBindings({
+          getMpvClient: () => appState.mpvClient,
+          getConfiguredKeybindings: () => configService.getConfig().keybindings ?? [],
+          platform:
+            process.platform === 'darwin'
+              ? 'darwin'
+              : process.platform === 'win32'
+                ? 'win32'
+                : 'linux',
+        });
+      },
+      getSessionBindings: async () => {
+        await refreshMpvSessionBindings();
+        return appState.sessionBindings;
+      },
       getConfiguredShortcuts: () => getConfiguredShortcuts(),
       dispatchSessionAction: (request) => dispatchSessionAction(request),
       getStatsToggleKey: () => configService.getConfig().stats.toggleKey,
@@ -5887,11 +6027,15 @@ const { registerIpcRuntimeHandlers } = composeIpcRuntimeHandlers({
         appState.ankiIntegration = integration;
         appState.ankiIntegration?.setRecordCardsMinedCallback(recordTrackedCardsMined);
         appState.ankiIntegration?.setKnownWordCacheUpdatedCallback(
-          refreshCurrentSubtitleAfterKnownWordUpdate,
+          refreshCurrentSubtitleAnnotations,
         );
         appState.ankiIntegration?.setSubtitleMiningContextConsumer(
           consumePendingSubtitleMiningContext,
         );
+        appState.ankiIntegration?.setMediaTimingReviewCallback(
+          mediaTimingReviewRuntime.requestReview,
+        );
+        appState.ankiIntegration?.setSentenceFuriganaGenerator(generateMiningSentenceFurigana);
       },
       getKnownWordCacheStatePath: () => path.join(USER_DATA_PATH, 'known-words-cache.json'),
       getCachedMediaPath: (currentVideoPath, kind) =>
@@ -5901,6 +6045,8 @@ const { registerIpcRuntimeHandlers } = composeIpcRuntimeHandlers({
       showDesktopNotification,
       showOverlayNotification: (payload) =>
         overlayNotificationsRuntime.showOverlayNotification(payload),
+      dismissOverlayNotification: (id) =>
+        overlayNotificationsRuntime.dismissOverlayNotification(id),
       createFieldGroupingCallback: () => createFieldGroupingCallback(),
       broadcastRuntimeOptionsChanged: () =>
         overlayVisibilityComposer.broadcastRuntimeOptionsChanged(),
@@ -6148,6 +6294,15 @@ const { runAndApplyStartupState } = composeHeadlessStartupHandlers<
 
 runAndApplyStartupState();
 void app.whenReady().then(() => {
+  void takePendingLauncherMigrationPath(async (pendingLauncherPath) => {
+    const acknowledgedPaths = await refreshManagedCommandLineLauncher({
+      ...createCommandLineLauncherRuntimeOptions(),
+      additionalLauncherPaths: pendingLauncherPath ? [pendingLauncherPath] : [],
+    });
+    return pendingLauncherPath !== undefined && acknowledgedPaths.includes(pendingLauncherPath);
+  }).catch((error) => {
+    logger.warn('Failed to refresh the installed command-line launcher', error);
+  });
   if (!shouldStartAutomaticUpdateChecks(appState.initialArgs)) {
     return;
   }
@@ -6187,8 +6342,8 @@ const { createMainWindow: createMainWindowHandler, createModalWindow: createModa
       forwardTabToMpv: () => sendMpvCommandRuntime(appState.mpvClient, ['keypress', 'TAB']),
       getLinuxX11FullscreenOverlay: () =>
         shouldRunLinuxOverlayZOrderKeepAlive() &&
-        linuxTrackedMpvFullscreen &&
-        linuxVisibleOverlayWindowMode === 'fullscreen-override',
+        linuxOverlayModeRuntime.fullscreen &&
+        linuxOverlayModeRuntime.mode === 'fullscreen-override',
       onVisibleWindowBlurred: () =>
         visibleOverlayInteractionRuntime.scheduleVisibleOverlayBlurRefresh(),
       onVisibleWindowFocused: () =>
@@ -6214,6 +6369,7 @@ const { createMainWindow: createMainWindowHandler, createModalWindow: createModa
           if (overlayManager.getModalWindow() !== window) {
             return;
           }
+          void mediaTimingReviewRuntime.dispose();
           overlayManager.setModalWindow(null);
         }
       },
@@ -6391,6 +6547,8 @@ const { initializeOverlayRuntime: initializeOverlayRuntimeHandler } =
       showDesktopNotification,
       showOverlayNotification: (payload) =>
         overlayNotificationsRuntime.showOverlayNotification(payload),
+      dismissOverlayNotification: (id) =>
+        overlayNotificationsRuntime.dismissOverlayNotification(id),
       createFieldGroupingCallback: () => createFieldGroupingCallback(),
       getKnownWordCacheStatePath: () => path.join(USER_DATA_PATH, 'known-words-cache.json'),
       getCachedMediaPath: (currentVideoPath, kind) =>
@@ -6524,3 +6682,36 @@ function setOverlayVisible(visible: boolean): void {
 }
 
 registerIpcRuntimeHandlers();
+registerSubtitleSelectionIpc({
+  ipc: ipcMain,
+  isAllowedSender: (sender) =>
+    [overlayManager.getMainWindow(), overlayManager.getModalWindow()].some(
+      (window) => window && !window.isDestroyed() && window.webContents === sender,
+    ),
+  runtime: createSubtitleSelectionRuntime({
+    isEnabled: () => configService.getConfig().subtitleSelection.enabled,
+    getMpvClient: () => appState.mpvClient,
+  }),
+});
+const subtitleGenerationRuntime = createSubtitleGenerationRuntime({
+  getConfig: () => configService.getConfig().subtitleGeneration,
+  getModelDirectory: () =>
+    path.join(path.dirname(configService.getConfigPath()), 'models', 'whisper'),
+  getMpvClient: () => appState.mpvClient,
+  onProgress: (progress) => {
+    for (const window of [overlayManager.getMainWindow(), overlayManager.getModalWindow()]) {
+      if (window && !window.isDestroyed())
+        window.webContents.send(IPC_CHANNELS.event.subtitleGenerationProgress, progress);
+    }
+  },
+});
+registerSubtitleGenerationIpc({
+  ipc: ipcMain,
+  isAllowedSender: (sender) =>
+    [overlayManager.getMainWindow(), overlayManager.getModalWindow()].some(
+      (window) => window && !window.isDestroyed() && window.webContents === sender,
+    ),
+  runtime: subtitleGenerationRuntime,
+  openModal: () => openSubtitleGenerationModal(createOverlayHostedModalOpenDeps()),
+});
+app.on('before-quit', () => subtitleGenerationRuntime.cancel());
diff --git a/src/main/character-dictionary-runtime.ts b/src/main/character-dictionary-runtime.ts
index c362d80b..1186775b 100644
--- a/src/main/character-dictionary-runtime.ts
+++ b/src/main/character-dictionary-runtime.ts
@@ -450,7 +450,7 @@ export function createCharacterDictionaryRuntimeService(deps: CharacterDictionar
     }
 
     const nameSplitTokenizerAvailable = isNameSplitTokenizerAvailable();
-    const resolvedNameSplits = nameSplitTokenizerAvailable
+    const nameSplitResolution = nameSplitTokenizerAvailable
       ? await resolveJapaneseNameSplits(
           characters,
           deps.tokenizeJapaneseName!,
@@ -466,8 +466,8 @@ export function createCharacterDictionaryRuntimeService(deps: CharacterDictionar
           },
         )
       : undefined;
-    const nameSplitSource =
-      resolvedNameSplits && resolvedNameSplits.size > 0 ? 'mecab' : 'heuristic';
+    const resolvedNameSplits = nameSplitResolution?.splits;
+    const nameSplitSource = nameSplitResolution?.kind === 'complete' ? 'mecab' : 'heuristic';
 
     progress?.onGenerateProgress?.({
       mediaId,
diff --git a/src/main/character-dictionary-runtime/image-lookup.test.ts b/src/main/character-dictionary-runtime/image-lookup.test.ts
index aadaf39a..c5b84f75 100644
--- a/src/main/character-dictionary-runtime/image-lookup.test.ts
+++ b/src/main/character-dictionary-runtime/image-lookup.test.ts
@@ -198,6 +198,66 @@ test('createCharacterDictionaryImageLookup can scope duplicate names to the curr
   assert.equal(scoped.alt, 'Kazuma');
 });
 
+test('createCharacterDictionaryImageLookup reports and retries a failed index-ready callback', async () => {
+  const outputDir = makeTempDir();
+  const snapshot: CharacterDictionarySnapshot = {
+    formatVersion: CHARACTER_DICTIONARY_FORMAT_VERSION,
+    mediaId: 21858,
+    mediaTitle: 'Little Witch Academia',
+    entryCount: 1,
+    updatedAt: 1_700_000_000_000,
+    termEntries: [
+      [
+        'ダイアナ',
+        'だいあな',
+        'name primary',
+        '',
+        75,
+        [
+          {
+            type: 'structured-content',
+            content: {
+              tag: 'img',
+              path: 'img/m21858-c81709.png',
+              alt: 'ダイアナ・キャベンディッシュ',
+            },
+          },
+        ],
+        0,
+        '',
+      ],
+    ],
+    images: [{ path: 'img/m21858-c81709.png', dataBase64: PNG_1X1_BASE64 }],
+  };
+  await writeSnapshot(getSnapshotPath(outputDir, snapshot.mediaId), snapshot);
+  const callbackError = new Error('annotation refresh failed');
+  const reportingError = new Error('error reporter failed');
+  let readyCount = 0;
+  const reportedErrors: unknown[] = [];
+  const lookup = createCharacterDictionaryImageLookup({
+    outputDir,
+    onIndexReady: () => {
+      readyCount += 1;
+      if (readyCount === 1) {
+        throw callbackError;
+      }
+    },
+    onIndexReadyError: (error) => {
+      reportedErrors.push(error);
+      throw reportingError;
+    },
+  });
+
+  assert.equal(lookup.get('ダイアナ', snapshot.mediaId), null);
+  await waitForRefresh(() => (reportedErrors.length === 1 ? true : null));
+  assert.ok(lookup.get('ダイアナ', snapshot.mediaId));
+
+  assert.equal(readyCount, 2);
+  assert.deepEqual(reportedErrors, [callbackError]);
+  lookup.get('ダイアナ', snapshot.mediaId);
+  assert.equal(readyCount, 2);
+});
+
 test('createCharacterDictionaryImageLookup does not fall back globally on scoped miss', async () => {
   const outputDir = makeTempDir();
   const snapshot: CharacterDictionarySnapshot = {
diff --git a/src/main/character-dictionary-runtime/image-lookup.ts b/src/main/character-dictionary-runtime/image-lookup.ts
index d21e3020..e10e1e5c 100644
--- a/src/main/character-dictionary-runtime/image-lookup.ts
+++ b/src/main/character-dictionary-runtime/image-lookup.ts
@@ -218,6 +218,8 @@ export function createCharacterDictionaryImageLookup(deps: {
   userDataPath?: string;
   outputDir?: string;
   getCurrentMediaId?: () => number | null | undefined;
+  onIndexReady?: () => void;
+  onIndexReadyError?: (error: unknown) => void;
 }): {
   get: (term: string, mediaId?: number | null) => CharacterNameImage | null;
   invalidate: () => void;
@@ -229,6 +231,24 @@ export function createCharacterDictionaryImageLookup(deps: {
   let index = new Map<string, CharacterNameImage>();
   let indexByMediaId = new Map<number, Map<string, CharacterNameImage>>();
   let refreshInFlight = false;
+  let indexReadyDeliveryPending = false;
+
+  function deliverIndexReadyIfPending(): void {
+    if (!indexReadyDeliveryPending || !deps.onIndexReady) {
+      return;
+    }
+    indexReadyDeliveryPending = false;
+    try {
+      deps.onIndexReady();
+    } catch (error) {
+      indexReadyDeliveryPending = true;
+      try {
+        deps.onIndexReadyError?.(error);
+      } catch {
+        // Error reporting must not reject the detached index refresh task.
+      }
+    }
+  }
 
   // Rebuilding means re-reading every cached snapshot (potentially GBs of JSON), which used to run
   // synchronously inside a lookup and froze the whole app right after a snapshot changed. Lookups
@@ -241,6 +261,7 @@ export function createCharacterDictionaryImageLookup(deps: {
       signature = '';
       return;
     }
+    deliverIndexReadyIfPending();
     const nextSignature = getSnapshotDirectorySignature(outputDir);
     if (nextSignature === signature || refreshInFlight) {
       return;
@@ -262,6 +283,8 @@ export function createCharacterDictionaryImageLookup(deps: {
         index = nextIndex;
         indexByMediaId = nextIndexByMediaId;
         signature = nextSignature;
+        indexReadyDeliveryPending = deps.onIndexReady !== undefined;
+        deliverIndexReadyIfPending();
       } finally {
         refreshInFlight = false;
       }
diff --git a/src/main/character-dictionary-runtime/name-split-resolver.test.ts b/src/main/character-dictionary-runtime/name-split-resolver.test.ts
index 84f70c69..9f442ecd 100644
--- a/src/main/character-dictionary-runtime/name-split-resolver.test.ts
+++ b/src/main/character-dictionary-runtime/name-split-resolver.test.ts
@@ -43,7 +43,8 @@ test('resolveJapaneseNameSplits splits a single-kanji surname via person-name PO
     }),
   );
 
-  assert.deepEqual(splits.get('東紫乃'), { family: '東', given: '紫乃' });
+  assert.equal(splits.kind, 'complete');
+  assert.deepEqual(splits.splits.get('東紫乃'), { family: '東', given: '紫乃' });
 });
 
 test('resolveJapaneseNameSplits corrects a hint-length-misleading surname boundary', async () => {
@@ -64,7 +65,8 @@ test('resolveJapaneseNameSplits corrects a hint-length-misleading surname bounda
     }),
   );
 
-  assert.deepEqual(splits.get('渡辺真奈美'), { family: '渡辺', given: '真奈美' });
+  assert.equal(splits.kind, 'complete');
+  assert.deepEqual(splits.splits.get('渡辺真奈美'), { family: '渡辺', given: '真奈美' });
 });
 
 test('resolveJapaneseNameSplits falls back to hint readings when POS tags are generic', async () => {
@@ -85,7 +87,8 @@ test('resolveJapaneseNameSplits falls back to hint readings when POS tags are ge
     }),
   );
 
-  assert.deepEqual(splits.get('鈴木みゆ'), { family: '鈴木', given: 'みゆ' });
+  assert.equal(splits.kind, 'complete');
+  assert.deepEqual(splits.splits.get('鈴木みゆ'), { family: '鈴木', given: 'みゆ' });
 });
 
 test('resolveJapaneseNameSplits skips names whose tokens do not reconstruct the name', async () => {
@@ -96,7 +99,8 @@ test('resolveJapaneseNameSplits skips names whose tokens do not reconstruct the
     }),
   );
 
-  assert.equal(splits.size, 0);
+  assert.equal(splits.kind, 'complete');
+  assert.equal(splits.splits.size, 0);
 });
 
 test('resolveJapaneseNameSplits skips ambiguous or untagged segmentations', async () => {
@@ -117,7 +121,8 @@ test('resolveJapaneseNameSplits skips ambiguous or untagged segmentations', asyn
     }),
   );
 
-  assert.equal(splits.size, 0);
+  assert.equal(splits.kind, 'complete');
+  assert.equal(splits.splits.size, 0);
 });
 
 test('resolveJapaneseNameSplits survives tokenizer failures', async () => {
@@ -130,7 +135,8 @@ test('resolveJapaneseNameSplits survives tokenizer failures', async () => {
     (message) => warnings.push(message),
   );
 
-  assert.equal(splits.size, 0);
+  assert.equal(splits.kind, 'incomplete');
+  assert.equal(splits.splits.size, 0);
   assert.equal(warnings.length, 1);
   assert.match(warnings[0]!, /mecab unavailable/);
 });
diff --git a/src/main/character-dictionary-runtime/name-split-resolver.ts b/src/main/character-dictionary-runtime/name-split-resolver.ts
index a1acedda..399a3a79 100644
--- a/src/main/character-dictionary-runtime/name-split-resolver.ts
+++ b/src/main/character-dictionary-runtime/name-split-resolver.ts
@@ -7,6 +7,10 @@ import type {
   ResolvedNameSplit,
 } from './types';
 
+export type JapaneseNameSplitResolution =
+  | { kind: 'complete'; splits: Map<string, ResolvedNameSplit> }
+  | { kind: 'incomplete'; splits: Map<string, ResolvedNameSplit> };
+
 const NAME_SEPARATOR_PATTERN = /[\s　・･·•]/;
 
 function joinSurfaces(tokens: NameSplitToken[]): string {
@@ -87,8 +91,9 @@ export async function resolveJapaneseNameSplits(
   tokenize: NameSplitTokenizer,
   logWarn?: (message: string) => void,
   onCharacterResolved?: (completed: number, total: number) => void,
-): Promise<Map<string, ResolvedNameSplit>> {
+): Promise<JapaneseNameSplitResolution> {
   const splits = new Map<string, ResolvedNameSplit>();
+  let tokenizerFailed = false;
   let resolvedCharacters = 0;
   for (const character of characters) {
     const familyHintReading = buildReadingFromHint(character.lastNameHint?.trim() || '');
@@ -99,12 +104,17 @@ export async function resolveJapaneseNameSplits(
       try {
         tokens = await tokenize(name);
       } catch (err) {
+        tokenizerFailed = true;
         logWarn?.(
           `[dictionary] name split tokenization failed for "${name}": ${(err as Error).message}`,
         );
         continue;
       }
-      if (!tokens || tokens.length < 2 || joinSurfaces(tokens) !== name) continue;
+      if (!tokens) {
+        tokenizerFailed = true;
+        continue;
+      }
+      if (tokens.length < 2 || joinSurfaces(tokens) !== name) continue;
       const splitIndex =
         splitIndexFromPersonNamePos(tokens) ??
         splitIndexFromHintReadings(tokens, familyHintReading, givenHintReading);
@@ -118,5 +128,5 @@ export async function resolveJapaneseNameSplits(
     resolvedCharacters += 1;
     onCharacterResolved?.(resolvedCharacters, characters.length);
   }
-  return splits;
+  return tokenizerFailed ? { kind: 'incomplete', splits } : { kind: 'complete', splits };
 }
diff --git a/src/main/character-dictionary-runtime/snapshot-refresh.test.ts b/src/main/character-dictionary-runtime/snapshot-refresh.test.ts
index b1d34fcf..25d0ecbd 100644
--- a/src/main/character-dictionary-runtime/snapshot-refresh.test.ts
+++ b/src/main/character-dictionary-runtime/snapshot-refresh.test.ts
@@ -7,7 +7,7 @@ import test from 'node:test';
 import { createCharacterDictionaryRuntimeService } from '../character-dictionary-runtime';
 import { getSnapshotPath, writeSnapshot } from './cache';
 import { CHARACTER_DICTIONARY_FORMAT_VERSION } from './constants';
-import type { CharacterDictionarySnapshot } from './types';
+import type { CharacterDictionarySnapshot, NameSplitTokenizer } from './types';
 
 const GRAPHQL_URL = 'https://graphql.anilist.co';
 const PNG_1X1 = Buffer.from(
@@ -121,7 +121,12 @@ test('generateForCurrentMedia refreshes same-version snapshots missing images wh
   }
 });
 
-test('generateForCurrentMedia keeps failed MeCab name split refreshes retryable', async () => {
+async function runNameSplitRefreshScenario(tokenizeJapaneseName: NameSplitTokenizer): Promise<{
+  characterPageRequests: number;
+  firstResultFromCache: boolean;
+  refreshedNameSplitSource: CharacterDictionarySnapshot['nameSplitSource'];
+  secondResultFromCache: boolean;
+}> {
   const userDataPath = makeTempDir();
   const outputDir = path.join(userDataPath, 'character-dictionaries');
   await writeSnapshot(getSnapshotPath(outputDir, 130298), {
@@ -172,7 +177,6 @@ test('generateForCurrentMedia keeps failed MeCab name split refreshes retryable'
   }) as typeof globalThis.fetch;
 
   try {
-    let tokenizerCalls = 0;
     const runtime = createCharacterDictionaryRuntimeService({
       userDataPath,
       getCurrentMediaPath: () => '/tmp/eminence-s01e05.mkv',
@@ -185,29 +189,54 @@ test('generateForCurrentMedia keeps failed MeCab name split refreshes retryable'
         source: 'fallback',
       }),
       getNameMatchImagesEnabled: () => false,
-      tokenizeJapaneseName: async () => {
-        tokenizerCalls += 1;
-        return null;
-      },
+      tokenizeJapaneseName,
       getJapaneseNameTokenizerAvailable: () => true,
       now: () => 1_700_000_000_500,
     });
 
-    const result = await runtime.generateForCurrentMedia();
+    const firstResult = await runtime.generateForCurrentMedia();
     const refreshedSnapshot = JSON.parse(
       fs.readFileSync(getSnapshotPath(outputDir, 130298), 'utf8'),
     ) as CharacterDictionarySnapshot;
+    const secondResult = await runtime.generateForCurrentMedia();
 
-    assert.equal(result.fromCache, false);
-    assert.equal(refreshedSnapshot.nameSplitSource, 'heuristic');
-
-    const retriedResult = await runtime.generateForCurrentMedia();
-    assert.equal(retriedResult.fromCache, false);
-    assert.equal(characterPageRequests, 2);
-    assert.equal(tokenizerCalls, 2);
+    return {
+      characterPageRequests,
+      firstResultFromCache: firstResult.fromCache,
+      refreshedNameSplitSource: refreshedSnapshot.nameSplitSource,
+      secondResultFromCache: secondResult.fromCache,
+    };
   } finally {
     globalThis.fetch = originalFetch;
   }
+}
+
+test('generateForCurrentMedia keeps failed MeCab name split refreshes retryable', async () => {
+  let tokenizerCalls = 0;
+  const result = await runNameSplitRefreshScenario(async () => {
+    tokenizerCalls += 1;
+    return null;
+  });
+
+  assert.equal(result.firstResultFromCache, false);
+  assert.equal(result.refreshedNameSplitSource, 'heuristic');
+  assert.equal(result.secondResultFromCache, false);
+  assert.equal(result.characterPageRequests, 2);
+  assert.equal(tokenizerCalls, 2);
+});
+
+test('generateForCurrentMedia caches completed MeCab refreshes with no resolved splits', async () => {
+  let tokenizerCalls = 0;
+  const result = await runNameSplitRefreshScenario(async () => {
+    tokenizerCalls += 1;
+    return [];
+  });
+
+  assert.equal(result.firstResultFromCache, false);
+  assert.equal(result.refreshedNameSplitSource, 'mecab');
+  assert.equal(result.secondResultFromCache, true);
+  assert.equal(result.characterPageRequests, 1);
+  assert.equal(tokenizerCalls, 1);
 });
 
 test('generateForCurrentMedia keeps mecab-split snapshots when MeCab is available', async () => {
diff --git a/src/main/dependencies.ts b/src/main/dependencies.ts
index cbbe4beb..90e10f21 100644
--- a/src/main/dependencies.ts
+++ b/src/main/dependencies.ts
@@ -62,6 +62,11 @@ export interface MainIpcRuntimeServiceDepsParams {
   onOverlayInteractiveHint?: IpcDepsRuntimeOptions['onOverlayInteractiveHint'];
   handleOverlayNotificationAction?: IpcDepsRuntimeOptions['handleOverlayNotificationAction'];
   onYoutubePickerResolve: IpcDepsRuntimeOptions['onYoutubePickerResolve'];
+  previewMediaTimingReview?: IpcDepsRuntimeOptions['previewMediaTimingReview'];
+  getMediaTimingReviewFrame?: IpcDepsRuntimeOptions['getMediaTimingReviewFrame'];
+  getMediaTimingReviewWaveform?: IpcDepsRuntimeOptions['getMediaTimingReviewWaveform'];
+  stopMediaTimingReviewPreview?: IpcDepsRuntimeOptions['stopMediaTimingReviewPreview'];
+  resolveMediaTimingReview?: IpcDepsRuntimeOptions['resolveMediaTimingReview'];
   openYomitanSettings: IpcDepsRuntimeOptions['openYomitanSettings'];
   quitApp: IpcDepsRuntimeOptions['quitApp'];
   toggleVisibleOverlay: IpcDepsRuntimeOptions['toggleVisibleOverlay'];
@@ -79,6 +84,7 @@ export interface MainIpcRuntimeServiceDepsParams {
   getMecabTokenizer: IpcDepsRuntimeOptions['getMecabTokenizer'];
   handleMpvCommand: IpcDepsRuntimeOptions['handleMpvCommand'];
   getKeybindings: IpcDepsRuntimeOptions['getKeybindings'];
+  getMpvInputBindings?: IpcDepsRuntimeOptions['getMpvInputBindings'];
   getSessionBindings: IpcDepsRuntimeOptions['getSessionBindings'];
   getConfiguredShortcuts: IpcDepsRuntimeOptions['getConfiguredShortcuts'];
   dispatchSessionAction: IpcDepsRuntimeOptions['dispatchSessionAction'];
@@ -132,6 +138,7 @@ export interface AnkiJimakuIpcRuntimeServiceDepsParams {
   getYoutubeMediaSourceUrl?: AnkiJimakuIpcRuntimeOptions['getYoutubeMediaSourceUrl'];
   showDesktopNotification: AnkiJimakuIpcRuntimeOptions['showDesktopNotification'];
   showOverlayNotification?: (payload: OverlayNotificationPayload) => void;
+  dismissOverlayNotification?: (id: string) => void;
   createFieldGroupingCallback: AnkiJimakuIpcRuntimeOptions['createFieldGroupingCallback'];
   broadcastRuntimeOptionsChanged: AnkiJimakuIpcRuntimeOptions['broadcastRuntimeOptionsChanged'];
   getFieldGroupingResolver: AnkiJimakuIpcRuntimeOptions['getFieldGroupingResolver'];
@@ -256,6 +263,11 @@ export function createMainIpcRuntimeServiceDeps(
     onOverlayInteractiveHint: params.onOverlayInteractiveHint,
     handleOverlayNotificationAction: params.handleOverlayNotificationAction,
     onYoutubePickerResolve: params.onYoutubePickerResolve,
+    previewMediaTimingReview: params.previewMediaTimingReview,
+    getMediaTimingReviewFrame: params.getMediaTimingReviewFrame,
+    getMediaTimingReviewWaveform: params.getMediaTimingReviewWaveform,
+    stopMediaTimingReviewPreview: params.stopMediaTimingReviewPreview,
+    resolveMediaTimingReview: params.resolveMediaTimingReview,
     openYomitanSettings: params.openYomitanSettings,
     quitApp: params.quitApp,
     toggleVisibleOverlay: params.toggleVisibleOverlay,
@@ -271,6 +283,7 @@ export function createMainIpcRuntimeServiceDeps(
     getMecabTokenizer: params.getMecabTokenizer,
     handleMpvCommand: params.handleMpvCommand,
     getKeybindings: params.getKeybindings,
+    getMpvInputBindings: params.getMpvInputBindings,
     getSessionBindings: params.getSessionBindings,
     getConfiguredShortcuts: params.getConfiguredShortcuts,
     dispatchSessionAction: params.dispatchSessionAction,
@@ -334,6 +347,7 @@ export function createAnkiJimakuIpcRuntimeServiceDeps(
       : {}),
     showDesktopNotification: params.showDesktopNotification,
     showOverlayNotification: params.showOverlayNotification,
+    dismissOverlayNotification: params.dismissOverlayNotification,
     createFieldGroupingCallback: params.createFieldGroupingCallback,
     broadcastRuntimeOptionsChanged: params.broadcastRuntimeOptionsChanged,
     getFieldGroupingResolver: params.getFieldGroupingResolver,
diff --git a/src/main/main-wiring.test.ts b/src/main/main-wiring.test.ts
index 73c61ba0..63f67012 100644
--- a/src/main/main-wiring.test.ts
+++ b/src/main/main-wiring.test.ts
@@ -183,7 +183,10 @@ test('remote media keeps parsed cues when the active subtitle source cannot be r
   )?.groups?.body;
 
   assert.ok(actionBlock);
-  assert.match(actionBlock, /isYoutubeMediaPath\(videoPath\) \|\| isRemoteMediaPath\(videoPath\)/);
+  assert.match(
+    actionBlock,
+    /isYoutubeMediaPath\(videoPath\) \|\| \(await detectRemoteMediaPath\(videoPath\)\)/,
+  );
 });
 
 test('jellyfin subtitle preload seeds the tokenization prefetch directly', () => {
@@ -430,11 +433,11 @@ test('warm tokenization release can signal readiness before the first subtitle a
 
 test('stats server Yomitan note creation honors configured Anki server override policy', () => {
   const source = readSource('src/main/runtime/stats-server-runtime.ts');
-  const startStatsServerBlock = source.match(
-    /statsServer = startStatsServer\(\{(?<body>[\s\S]*?)\n      \}\);/,
+  const statsServerConfigBlock = source.match(
+    /const buildStatsServerConfig[\s\S]*?return \{(?<body>[\s\S]*?)\n    \};\n  \};/,
   )?.groups?.body;
-  const addYomitanNoteBlock = startStatsServerBlock?.match(
-    /addYomitanNote:\s*async\s*\(word: string\)\s*=>\s*\{(?<body>[\s\S]*?)\n        \},/,
+  const addYomitanNoteBlock = statsServerConfigBlock?.match(
+    /addYomitanNote:\s*async\s*\(word: string\)\s*=>\s*\{(?<body>[\s\S]*?)\n      \},/,
   )?.groups?.body;
 
   assert.ok(addYomitanNoteBlock);
@@ -450,7 +453,7 @@ test('Linux visible overlay recreation clears stale input state before creating
   const source = readMainSource();
   const runtimeSource = readSource('src/main/runtime/visible-overlay-interaction-runtime.ts');
   const actionBlock = source.match(
-    /function createLinuxVisibleOverlayWindowForCurrentMode\([\s\S]*?\): void \{(?<body>[\s\S]*?)\n\}/,
+    /const linuxOverlayModeRuntime = createLinuxOverlayModeRuntime\(\{[\s\S]*?createWindow: \(\) => \{(?<body>[\s\S]*?)\n  \},/,
   )?.groups?.body;
   const resetBlock = runtimeSource.match(
     /function resetVisibleOverlayInputState\(\): void \{(?<body>[\s\S]*?)\n  \}/,
@@ -469,7 +472,7 @@ test('Linux visible overlay recreation clears stale input state before creating
 test('Linux visible overlay recreation avoids display fallback before tracked geometry exists', () => {
   const source = readMainSource();
   const actionBlock = source.match(
-    /function createLinuxVisibleOverlayWindowForCurrentMode\([\s\S]*?\): void \{(?<body>[\s\S]*?)\n\}/,
+    /const linuxOverlayModeRuntime = createLinuxOverlayModeRuntime\(\{[\s\S]*?refreshWindow: \(\) => \{(?<body>[\s\S]*?)\n  \},/,
   )?.groups?.body;
 
   assert.ok(actionBlock);
@@ -477,15 +480,18 @@ test('Linux visible overlay recreation avoids display fallback before tracked ge
     actionBlock,
     /const trackedGeometry = overlayGeometryRuntime\.getCurrentTrackedOverlayGeometry\(\);/,
   );
-  assert.match(actionBlock, /if \(trackedGeometry\) \{/);
+  assert.match(
+    actionBlock,
+    /if \(trackedGeometry\) overlayManager\.setOverlayWindowBounds\(trackedGeometry\);/,
+  );
   assert.match(actionBlock, /overlayManager\.setOverlayWindowBounds\(trackedGeometry\);/);
   assert.doesNotMatch(actionBlock, /setOverlayWindowBounds\(getCurrentOverlayGeometry\(\)\)/);
 });
 
-test('known-word updates invalidate prefetched tokenizations before refreshing current subtitle', () => {
+test('subtitle annotation updates invalidate prefetched tokenizations before refreshing current subtitle', () => {
   const source = readMainSource();
   const actionBlock = source.match(
-    /const refreshCurrentSubtitleAfterKnownWordUpdate = \(\): void => \{(?<body>[\s\S]*?)\n\};/,
+    /function refreshCurrentSubtitleAnnotations\(\): void \{(?<body>[\s\S]*?)\n\}/,
   )?.groups?.body;
 
   assert.ok(actionBlock);
@@ -503,6 +509,20 @@ test('known-word updates invalidate prefetched tokenizations before refreshing c
   );
 });
 
+test('character portrait index readiness refreshes cached subtitle annotations', () => {
+  const source = readMainSource();
+  const lookupDeps = source.match(
+    /const characterDictionaryImageLookup = createCharacterDictionaryImageLookup\(\{(?<body>[\s\S]*?)\n\}\);/,
+  )?.groups?.body;
+
+  assert.ok(lookupDeps);
+  assert.match(lookupDeps, /onIndexReady: \(\) => refreshCurrentSubtitleAnnotations\(\),/);
+  assert.match(
+    lookupDeps,
+    /onIndexReadyError: \(error\) =>[\s\S]*?logger\.warn\([\s\S]*?character portrait index became ready\.[\s\S]*?error,/,
+  );
+});
+
 test('subtitle processing controller resumes prefetch on settle, not on its emits', () => {
   const source = readMainSource();
   const depsBlock = source.match(
@@ -846,3 +866,19 @@ test('subtitle sidebar snapshot prefers cached YouTube parsed cues before active
       snapshotBlock.indexOf('resolveActiveSubtitleSidebarSourceHandler'),
   );
 });
+
+test('main process extracts internal subtitle tracks without a network-mount guard', () => {
+  const source = readMainSource();
+  const resolverWiring = source.match(
+    /const resolveActiveSubtitleSidebarSourceHandler = createResolveActiveSubtitleSidebarSourceHandler\(\{(?<body>[\s\S]*?)\n\}\);/,
+  )?.groups?.body;
+
+  assert.ok(resolverWiring);
+  // Network-mounted files are extracted like local ones; only remote URLs skip
+  // extraction, handled inside the resolver itself.
+  assert.doesNotMatch(resolverWiring, /isRemoteMediaPath/);
+  assert.match(
+    resolverWiring,
+    /extractInternalSubtitleTrack:[\s\S]*cachedInternalSubtitleTrackExtractor\.extract/,
+  );
+});
diff --git a/src/main/media-runtime.ts b/src/main/media-runtime.ts
index a994c93b..7f5bb355 100644
--- a/src/main/media-runtime.ts
+++ b/src/main/media-runtime.ts
@@ -1,4 +1,5 @@
 import { updateCurrentMediaPath } from '../core/services';
+import { sanitizeMediaTitle } from '../shared/media-identity';
 
 import type { SubtitlePosition } from '../types';
 
@@ -52,17 +53,18 @@ export function createMediaRuntimeService(deps: MediaRuntimeDeps): MediaRuntimeS
 
     updateCurrentMediaTitle(mediaTitle: unknown): void {
       if (typeof mediaTitle === 'string') {
-        const sanitized = mediaTitle.trim();
-        deps.setCurrentMediaTitle(sanitized.length > 0 ? sanitized : null);
+        const sanitized = sanitizeMediaTitle(mediaTitle);
+        if (mediaTitle.trim() && !sanitized) return;
+        deps.setCurrentMediaTitle(sanitized);
         return;
       }
       deps.setCurrentMediaTitle(null);
     },
 
     resolveMediaPathForJimaku(mediaPath: string | null): string | null {
-      return mediaPath && deps.isRemoteMediaPath(mediaPath) && deps.getCurrentMediaTitle()
-        ? deps.getCurrentMediaTitle()
-        : mediaPath;
+      return mediaPath && deps.isRemoteMediaPath(mediaPath)
+        ? sanitizeMediaTitle(deps.getCurrentMediaTitle())
+        : sanitizeMediaTitle(mediaPath);
     },
   };
 }
diff --git a/src/main/overlay-runtime.test.ts b/src/main/overlay-runtime.test.ts
index 78c121f8..2190ad28 100644
--- a/src/main/overlay-runtime.test.ts
+++ b/src/main/overlay-runtime.test.ts
@@ -828,6 +828,7 @@ test('modal fallback reveal skips showing window when content is not ready', asy
       setModalWindowBounds: () => {},
     },
     {
+      platform: 'darwin',
       scheduleRevealFallback: (callback) => {
         scheduledReveal = callback;
         return { scheduled: true } as never;
@@ -1363,3 +1364,62 @@ test('modal placement reconcile cancels stale retry ladder after a newer visible
     globalThis.clearTimeout = originalClearTimeout;
   }
 });
+
+test('Linux keeps the dedicated modal window unmapped until the renderer opens the modal, then hides the overlay before revealing it', () => {
+  const mainWindow = createMockWindow();
+  mainWindow.visible = true;
+  const modalWindow = createMockWindow();
+  const order: string[] = [];
+  const hideMain = mainWindow.hide;
+  mainWindow.hide = () => {
+    order.push('main:hide');
+    hideMain();
+  };
+  const showModal = modalWindow.show;
+  modalWindow.show = () => {
+    order.push('modal:show');
+    showModal();
+  };
+  let revealScheduled = false;
+  const runtime = createOverlayModalRuntimeService(
+    {
+      getMainWindow: () => mainWindow as never,
+      getModalWindow: () => modalWindow as never,
+      createModalWindow: () => modalWindow as never,
+      getModalGeometry: () => ({ x: 0, y: 0, width: 400, height: 300 }),
+      setModalWindowBounds: () => {},
+    },
+    {
+      platform: 'linux',
+      scheduleRevealFallback: () => {
+        revealScheduled = true;
+        return { scheduled: true } as never;
+      },
+      clearRevealFallback: () => {},
+    },
+  );
+
+  const open = () =>
+    runtime.sendToActiveOverlayWindow(
+      'media-timing-review:open',
+      { reviewId: 'review' },
+      { restoreOnModalClose: 'media-timing-review', preferModalWindow: true },
+    );
+
+  assert.equal(open(), true);
+  assert.deepEqual(modalWindow.sent, [['media-timing-review:open', { reviewId: 'review' }]]);
+  assert.equal(revealScheduled, false);
+  assert.equal(modalWindow.getShowCount(), 0);
+  assert.equal(mainWindow.getHideCount(), 0);
+
+  // The open retry must not map the window before the renderer answers either.
+  assert.equal(open(), true);
+  assert.equal(modalWindow.getShowCount(), 0);
+
+  runtime.notifyOverlayModalOpened('media-timing-review');
+
+  assert.deepEqual(order, ['main:hide', 'modal:show']);
+  assert.equal(mainWindow.isVisible(), false);
+  assert.equal(modalWindow.isVisible(), true);
+  assert.equal(modalWindow.ignoreMouseEvents, false);
+});
diff --git a/src/main/overlay-runtime.ts b/src/main/overlay-runtime.ts
index 98ce57d0..8244f521 100644
--- a/src/main/overlay-runtime.ts
+++ b/src/main/overlay-runtime.ts
@@ -90,6 +90,12 @@ export function createOverlayModalRuntimeService(
   const platform = options.platform ?? process.platform;
   const shouldPrimeModalWindow = platform === 'darwin' || platform === 'win32';
   const reuseModalWindowAfterClose = platform === 'darwin';
+  // On Linux (Hyprland) every placement dispatch on a mapped window (resize, move, set_prop)
+  // blanks the still-visible overlay for a few frames while mpv is fullscreen. Revealing the
+  // dedicated modal window before its renderer has the modal open runs the placement ladder,
+  // and the open retry, against a visible overlay, which the user sees as flicker. Keep the
+  // window unmapped until the renderer acknowledges the open, then hide the overlay first.
+  const deferModalRevealUntilOpened = platform === 'linux';
   const focusApplication = options.focusApplication ?? requestOverlayApplicationFocus;
   const scheduleRevealFallback = (callback: () => void, delayMs: number): RevealFallbackHandle =>
     (options.scheduleRevealFallback ?? globalThis.setTimeout)(callback, delayMs);
@@ -457,7 +463,9 @@ export function createOverlayModalRuntimeService(
       deps.setModalWindowBounds(deps.getModalGeometry());
       const wasVisible = modalWindow.isVisible();
       if (!wasVisible) {
-        if (modalWindowPrimedForImmediateShow && isWindowReadyForIpc(modalWindow)) {
+        if (deferModalRevealUntilOpened) {
+          // notifyOverlayModalOpened reveals the window once the renderer has the modal open.
+        } else if (modalWindowPrimedForImmediateShow && isWindowReadyForIpc(modalWindow)) {
           showModalWindow(modalWindow);
         } else {
           scheduleModalWindowReveal(modalWindow);
@@ -560,15 +568,23 @@ export function createOverlayModalRuntimeService(
     }
 
     const modalWindow = deps.getModalWindow();
+    const targetIsModalWindow =
+      modalWindow !== null && !modalWindow.isDestroyed() && targetWindow === modalWindow;
+    const handOffMainWindowToModal = (): void => {
+      setMainWindowMousePassthroughForModal(true);
+      setMainWindowVisibilityForModal(true);
+    };
+
+    if (targetIsModalWindow && deferModalRevealUntilOpened) {
+      handOffMainWindowToModal();
+    }
     if (targetWindow.isVisible()) {
       ensureModalWindowInteractive(targetWindow);
     } else {
       showModalWindow(targetWindow);
     }
-
-    if (modalWindow && !modalWindow.isDestroyed() && targetWindow === modalWindow) {
-      setMainWindowMousePassthroughForModal(true);
-      setMainWindowVisibilityForModal(true);
+    if (targetIsModalWindow && !deferModalRevealUntilOpened) {
+      handOffMainWindowToModal();
     }
   };
 
diff --git a/src/main/runtime/anilist-post-watch.test.ts b/src/main/runtime/anilist-post-watch.test.ts
index 06826d11..45c97d01 100644
--- a/src/main/runtime/anilist-post-watch.test.ts
+++ b/src/main/runtime/anilist-post-watch.test.ts
@@ -9,6 +9,10 @@ import {
 
 test('buildAnilistAttemptKey formats media and episode', () => {
   assert.equal(buildAnilistAttemptKey('/tmp/video.mkv', 3), '/tmp/video.mkv::3');
+  assert.equal(
+    buildAnilistAttemptKey('https://example.com/Videos/item/stream?api_key=test-secret', 3),
+    'jellyfin://example.com/item/item::3',
+  );
 });
 
 test('rememberAnilistAttemptedUpdateKey evicts oldest beyond max size', () => {
@@ -17,6 +21,49 @@ test('rememberAnilistAttemptedUpdateKey evicts oldest beyond max size', () => {
   assert.deepEqual(Array.from(set), ['b', 'c']);
 });
 
+test('post-watch rejects empty media identities before attempted keys or update side effects', async () => {
+  for (const mediaKey of [
+    '  ',
+    'stream?api_key=secret',
+    'stream%3Fapi_key%3Dsecret',
+    'https://[invalid',
+  ]) {
+    assert.equal(buildAnilistAttemptKey(mediaKey, 3), null);
+    const calls: string[] = [];
+    const unexpected = () => assert.fail('invalid identity reached update side effects');
+    const handler = createMaybeRunAnilistPostWatchUpdateHandler({
+      getInFlight: () => false,
+      setInFlight: (value) => calls.push(`inflight:${value}`),
+      getResolvedConfig: () => ({}),
+      isAnilistTrackingEnabled: () => true,
+      getCurrentMediaKey: () => mediaKey,
+      hasMpvClient: () => true,
+      getTrackedMediaKey: () => mediaKey,
+      resetTrackedMedia: unexpected,
+      getWatchedSeconds: () => 1000,
+      maybeProbeAnilistDuration: async () => 1000,
+      ensureAnilistMediaGuess: async () => ({ title: 'Show', season: null, episode: 3 }),
+      hasAttemptedUpdateKey: unexpected,
+      processNextAnilistRetryUpdate: unexpected,
+      refreshAnilistClientSecretState: unexpected,
+      enqueueRetry: unexpected,
+      markRetryFailure: unexpected,
+      markRetrySuccess: unexpected,
+      refreshRetryQueueState: unexpected,
+      updateAnilistPostWatchProgress: unexpected,
+      rememberAttemptedUpdateKey: unexpected,
+      showMpvOsd: unexpected,
+      logInfo: unexpected,
+      logWarn: unexpected,
+      minWatchSeconds: 600,
+      minWatchRatio: 0.85,
+    });
+    await handler();
+    await handler({ force: true });
+    assert.deepEqual(calls, ['inflight:true', 'inflight:false', 'inflight:true', 'inflight:false']);
+  }
+});
+
 test('createProcessNextAnilistRetryUpdateHandler handles successful retry', async () => {
   const calls: string[] = [];
   const handler = createProcessNextAnilistRetryUpdateHandler({
@@ -335,6 +382,7 @@ test('createMaybeRunAnilistPostWatchUpdateHandler notifies when retry already ha
   const attemptedKeys = new Set<string>();
   const mediaKey = '/tmp/video.mkv';
   const attemptKey = buildAnilistAttemptKey(mediaKey, 1);
+  assert.ok(attemptKey);
   const handler = createMaybeRunAnilistPostWatchUpdateHandler({
     getInFlight: () => false,
     setInFlight: (value) => calls.push(`inflight:${value}`),
diff --git a/src/main/runtime/anilist-post-watch.ts b/src/main/runtime/anilist-post-watch.ts
index 932532b6..e81b355b 100644
--- a/src/main/runtime/anilist-post-watch.ts
+++ b/src/main/runtime/anilist-post-watch.ts
@@ -1,4 +1,5 @@
 import { isYoutubeMediaPath } from './youtube-playback';
+import { toMediaIdentityPath } from '../../shared/media-identity';
 
 type AnilistGuess = {
   title: string;
@@ -31,8 +32,9 @@ type AnilistDurationProbeOptions = {
   force?: boolean;
 };
 
-export function buildAnilistAttemptKey(mediaKey: string, episode: number): string {
-  return `${mediaKey}::${episode}`;
+export function buildAnilistAttemptKey(mediaKey: string, episode: number): string | null {
+  const identity = toMediaIdentityPath(mediaKey);
+  return identity ? `${identity}::${episode}` : null;
 }
 
 export function rememberAnilistAttemptedUpdateKey(
@@ -214,6 +216,7 @@ export function createMaybeRunAnilistPostWatchUpdateHandler(deps: {
       }
 
       const attemptKey = buildAnilistAttemptKey(mediaKey, guess.episode);
+      if (!attemptKey) return;
       if (deps.hasAttemptedUpdateKey(attemptKey)) {
         return;
       }
diff --git a/src/main/runtime/app-lifecycle-actions.test.ts b/src/main/runtime/app-lifecycle-actions.test.ts
index 11e75df0..1fff472d 100644
--- a/src/main/runtime/app-lifecycle-actions.test.ts
+++ b/src/main/runtime/app-lifecycle-actions.test.ts
@@ -1,12 +1,32 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
 import {
+  createForceQuitHandler,
   createOnWillQuitCleanupHandler,
   createRestoreWindowsOnActivateHandler,
   createShouldRestoreWindowsOnActivateHandler,
 } from './app-lifecycle-actions';
 
-test('on will quit cleanup handler runs all cleanup steps', () => {
+test('forced quit finalizes stats before exiting, even when finalization throws', async () => {
+  for (const fails of [false, true]) {
+    const calls: string[] = [];
+    await createForceQuitHandler({
+      destroyImmersionTracker: () => {
+        calls.push('finalize');
+        if (fails) throw new Error('flush failed');
+      },
+      logError: () => {
+        calls.push('error');
+      },
+      exit: () => {
+        calls.push('exit');
+      },
+    })();
+    assert.deepEqual(calls, fails ? ['finalize', 'error', 'exit'] : ['finalize', 'exit']);
+  }
+});
+
+test('on will quit cleanup handler runs all cleanup steps', async () => {
   const calls: string[] = [];
   const cleanup = createOnWillQuitCleanupHandler({
     destroyTray: () => calls.push('destroy-tray'),
@@ -32,7 +52,15 @@ test('on will quit cleanup handler runs all cleanup steps', () => {
     destroyMpvSocket: () => calls.push('destroy-socket'),
     clearReconnectTimer: () => calls.push('clear-reconnect'),
     destroySubtitleTimingTracker: () => calls.push('destroy-subtitle-tracker'),
-    destroyImmersionTracker: () => calls.push('destroy-immersion'),
+    stopStatsServer: async () => {
+      calls.push('stop-stats-server-start');
+      await Promise.resolve();
+      calls.push('stop-stats-server-complete');
+    },
+    destroyImmersionTracker: async () => {
+      await Promise.resolve();
+      calls.push('destroy-immersion');
+    },
     destroyAnkiIntegration: () => calls.push('destroy-anki'),
     destroyAnilistSetupWindow: () => calls.push('destroy-anilist-window'),
     clearAnilistSetupWindow: () => calls.push('clear-anilist-window'),
@@ -43,25 +71,57 @@ test('on will quit cleanup handler runs all cleanup steps', () => {
     destroyYomitanSettingsWindow: () => calls.push('destroy-yomitan-settings-window'),
     clearYomitanSettingsWindow: () => calls.push('clear-yomitan-settings-window'),
     stopJellyfinRemoteSession: () => calls.push('stop-jellyfin-remote'),
+    cleanupInternalSubtitleTrackCache: () => calls.push('cleanup-internal-subtitles'),
     cleanupYoutubeSubtitleTempDirs: () => calls.push('cleanup-youtube-subtitles'),
     cleanupYoutubeMediaCache: () => calls.push('cleanup-youtube-media'),
+    cleanupRemoteMediaWindows: () => calls.push('cleanup-remote-media-windows'),
     cleanupJellyfinSubtitleCache: () => calls.push('cleanup-jellyfin-subtitles'),
     stopDiscordPresenceService: () => calls.push('stop-discord-presence'),
   });
 
-  cleanup();
-  assert.equal(calls.length, 34);
+  await cleanup();
+  assert.equal(calls.length, 38);
   assert.equal(calls[0], 'destroy-tray');
   assert.equal(calls[calls.length - 1], 'stop-discord-presence');
   assert.ok(calls.includes('cleanup-jellyfin-subtitles'));
+  assert.ok(calls.includes('cleanup-internal-subtitles'));
   assert.ok(calls.includes('clear-windows-visible-overlay-poll'));
   assert.ok(calls.includes('clear-linux-mpv-fullscreen-overlay-refresh-timeouts'));
   assert.ok(calls.includes('cleanup-youtube-subtitles'));
   assert.ok(calls.includes('cleanup-youtube-media'));
+  assert.ok(calls.includes('cleanup-remote-media-windows'));
   assert.ok(calls.indexOf('flush-mpv-log') < calls.indexOf('destroy-socket'));
+  assert.ok(calls.indexOf('stop-stats-server-complete') < calls.indexOf('destroy-immersion'));
+  assert.ok(calls.indexOf('destroy-immersion') < calls.indexOf('destroy-anki'));
 });
 
-test('on will quit cleanup handler cleans jellyfin subtitle cache when stopping remote session fails', () => {
+test('forced quit waits for asynchronous stats finalization', async () => {
+  const calls: string[] = [];
+  await createForceQuitHandler({
+    destroyImmersionTracker: async () => {
+      await Promise.resolve();
+      calls.push('finalized');
+    },
+    logError: () => calls.push('error'),
+    exit: () => calls.push('exit'),
+  })();
+  assert.deepEqual(calls, ['finalized', 'exit']);
+});
+
+test('forced quit exits when asynchronous stats finalization never settles', async () => {
+  const calls: string[] = [];
+  await createForceQuitHandler({
+    destroyImmersionTracker: () => new Promise<void>(() => {}),
+    logError: (error) => {
+      assert.match(String(error), /Stats finalization timed out/);
+      calls.push('timeout');
+    },
+    exit: () => calls.push('exit'),
+  })();
+  assert.deepEqual(calls, ['timeout', 'exit']);
+});
+
+test('on will quit cleanup handler cleans jellyfin subtitle cache when stopping remote session fails', async () => {
   const calls: string[] = [];
   const cleanup = createOnWillQuitCleanupHandler({
     destroyTray: () => {},
@@ -83,6 +143,7 @@ test('on will quit cleanup handler cleans jellyfin subtitle cache when stopping
     destroyMpvSocket: () => {},
     clearReconnectTimer: () => {},
     destroySubtitleTimingTracker: () => {},
+    stopStatsServer: () => {},
     destroyImmersionTracker: () => {},
     destroyAnkiIntegration: () => {},
     destroyAnilistSetupWindow: () => {},
@@ -97,14 +158,20 @@ test('on will quit cleanup handler cleans jellyfin subtitle cache when stopping
       calls.push('stop-jellyfin-remote');
       throw new Error('stop failed');
     },
+    cleanupInternalSubtitleTrackCache: () => calls.push('cleanup-internal-subtitles'),
     cleanupYoutubeSubtitleTempDirs: () => calls.push('cleanup-youtube-subtitles'),
     cleanupYoutubeMediaCache: () => calls.push('cleanup-youtube-media'),
+    cleanupRemoteMediaWindows: () => calls.push('cleanup-remote-media-windows'),
     cleanupJellyfinSubtitleCache: () => calls.push('cleanup-jellyfin-subtitles'),
     stopDiscordPresenceService: () => calls.push('stop-discord-presence'),
   });
 
-  assert.throws(() => cleanup(), /stop failed/);
-  assert.deepEqual(calls, ['stop-jellyfin-remote', 'cleanup-jellyfin-subtitles']);
+  await assert.rejects(cleanup(), /stop failed/);
+  assert.deepEqual(calls, [
+    'stop-jellyfin-remote',
+    'cleanup-jellyfin-subtitles',
+    'cleanup-internal-subtitles',
+  ]);
 });
 
 test('should restore windows on activate requires initialized runtime and no windows', () => {
diff --git a/src/main/runtime/app-lifecycle-actions.ts b/src/main/runtime/app-lifecycle-actions.ts
index 16f4130a..e754b280 100644
--- a/src/main/runtime/app-lifecycle-actions.ts
+++ b/src/main/runtime/app-lifecycle-actions.ts
@@ -1,3 +1,26 @@
+export function createForceQuitHandler(deps: {
+  destroyImmersionTracker: () => void | Promise<void>;
+  logError: (error: unknown) => void;
+  exit: () => void;
+}) {
+  return async () => {
+    let timeout: ReturnType<typeof setTimeout> | undefined;
+    try {
+      await Promise.race([
+        Promise.resolve().then(() => deps.destroyImmersionTracker()),
+        new Promise<never>((_, reject) => {
+          timeout = setTimeout(() => reject(new Error('Stats finalization timed out.')), 1_000);
+        }),
+      ]);
+    } catch (error) {
+      deps.logError(error);
+    } finally {
+      clearTimeout(timeout);
+      deps.exit();
+    }
+  };
+}
+
 export function createOnWillQuitCleanupHandler(deps: {
   destroyTray: () => void;
   stopConfigHotReload: () => void;
@@ -18,7 +41,8 @@ export function createOnWillQuitCleanupHandler(deps: {
   destroyMpvSocket: () => void;
   clearReconnectTimer: () => void;
   destroySubtitleTimingTracker: () => void;
-  destroyImmersionTracker: () => void;
+  stopStatsServer: () => Promise<void> | void;
+  destroyImmersionTracker: () => void | Promise<void>;
   destroyAnkiIntegration: () => void;
   destroyAnilistSetupWindow: () => void;
   clearAnilistSetupWindow: () => void;
@@ -29,12 +53,14 @@ export function createOnWillQuitCleanupHandler(deps: {
   destroyYomitanSettingsWindow: () => void;
   clearYomitanSettingsWindow: () => void;
   stopJellyfinRemoteSession: () => void;
+  cleanupInternalSubtitleTrackCache: () => void;
   cleanupYoutubeSubtitleTempDirs: () => void;
   cleanupYoutubeMediaCache: () => void;
+  cleanupRemoteMediaWindows: () => void;
   cleanupJellyfinSubtitleCache: () => void;
   stopDiscordPresenceService: () => void;
 }) {
-  return (): Promise<void> => {
+  return async (): Promise<void> => {
     deps.destroyTray();
     deps.stopConfigHotReload();
     deps.restorePreviousSecondarySubVisibility();
@@ -42,7 +68,12 @@ export function createOnWillQuitCleanupHandler(deps: {
     deps.unregisterAllGlobalShortcuts();
     deps.stopSubtitleWebsocket();
     deps.stopTexthookerService();
-    const stopSyncAutoScheduler = deps.stopSyncAutoScheduler();
+    const cleanupErrors: unknown[] = [];
+    const stopSyncAutoScheduler = Promise.resolve(deps.stopSyncAutoScheduler()).catch(
+      (error: unknown) => {
+        cleanupErrors.push(error);
+      },
+    );
     deps.clearWindowsVisibleOverlayForegroundPollLoop();
     deps.clearLinuxMpvFullscreenOverlayRefreshTimeouts();
     deps.destroyMainOverlayWindow();
@@ -54,7 +85,16 @@ export function createOnWillQuitCleanupHandler(deps: {
     deps.destroyMpvSocket();
     deps.clearReconnectTimer();
     deps.destroySubtitleTimingTracker();
-    deps.destroyImmersionTracker();
+    try {
+      await deps.stopStatsServer();
+    } catch (error) {
+      cleanupErrors.push(error);
+    }
+    try {
+      await deps.destroyImmersionTracker();
+    } catch (error) {
+      cleanupErrors.push(error);
+    }
     deps.destroyAnkiIntegration();
     deps.destroyAnilistSetupWindow();
     deps.clearAnilistSetupWindow();
@@ -67,12 +107,20 @@ export function createOnWillQuitCleanupHandler(deps: {
     try {
       deps.stopJellyfinRemoteSession();
     } finally {
-      deps.cleanupJellyfinSubtitleCache();
+      try {
+        deps.cleanupJellyfinSubtitleCache();
+      } finally {
+        deps.cleanupInternalSubtitleTrackCache();
+      }
     }
     deps.cleanupYoutubeSubtitleTempDirs();
     deps.cleanupYoutubeMediaCache();
+    deps.cleanupRemoteMediaWindows();
     deps.stopDiscordPresenceService();
-    return Promise.resolve(stopSyncAutoScheduler);
+    await stopSyncAutoScheduler;
+    if (cleanupErrors.length > 0) {
+      throw cleanupErrors[0];
+    }
   };
 }
 
diff --git a/src/main/runtime/app-lifecycle-main-cleanup.test.ts b/src/main/runtime/app-lifecycle-main-cleanup.test.ts
index 373df2f9..54a3bf15 100644
--- a/src/main/runtime/app-lifecycle-main-cleanup.test.ts
+++ b/src/main/runtime/app-lifecycle-main-cleanup.test.ts
@@ -3,11 +3,14 @@ import test from 'node:test';
 import { createBuildOnWillQuitCleanupDepsHandler } from './app-lifecycle-main-cleanup';
 import { createOnWillQuitCleanupHandler } from './app-lifecycle-actions';
 
-test('cleanup deps builder returns handlers that guard optional runtime objects', () => {
+test('cleanup deps builder returns handlers that guard optional runtime objects', async () => {
   const calls: string[] = [];
   let reconnectTimer: ReturnType<typeof setTimeout> | null = setTimeout(() => {}, 60_000);
-  let immersionTracker: { destroy: () => void } | null = {
-    destroy: () => calls.push('destroy-immersion'),
+  let immersionTracker: { destroy: () => Promise<void> } | null = {
+    destroy: async () => {
+      await Promise.resolve();
+      calls.push('destroy-immersion');
+    },
   };
 
   const depsFactory = createBuildOnWillQuitCleanupDepsHandler({
@@ -54,6 +57,9 @@ test('cleanup deps builder returns handlers that guard optional runtime objects'
 
     getSubtitleTimingTracker: () => ({ destroy: () => calls.push('destroy-subtitle-tracker') }),
     getImmersionTracker: () => immersionTracker,
+    stopStatsServer: () => {
+      calls.push('stop-stats-server');
+    },
     clearImmersionTracker: () => {
       immersionTracker = null;
       calls.push('clear-immersion-ref');
@@ -72,14 +78,16 @@ test('cleanup deps builder returns handlers that guard optional runtime objects'
     clearYomitanSettingsWindow: () => calls.push('clear-yomitan-settings-window'),
 
     stopJellyfinRemoteSession: () => calls.push('stop-jellyfin-remote'),
+    cleanupInternalSubtitleTrackCache: () => calls.push('cleanup-internal-subtitles'),
     cleanupYoutubeSubtitleTempDirs: () => calls.push('cleanup-youtube-subtitles'),
     cleanupYoutubeMediaCache: () => calls.push('cleanup-youtube-media'),
+    cleanupRemoteMediaWindows: () => calls.push('cleanup-remote-media-windows'),
     cleanupJellyfinSubtitleCache: () => calls.push('cleanup-jellyfin-subtitles'),
     stopDiscordPresenceService: () => calls.push('stop-discord-presence'),
   });
 
   const cleanup = createOnWillQuitCleanupHandler(depsFactory());
-  cleanup();
+  await cleanup();
 
   assert.ok(calls.includes('destroy-tray'));
   assert.ok(calls.includes('destroy-main-overlay-window'));
@@ -92,9 +100,11 @@ test('cleanup deps builder returns handlers that guard optional runtime objects'
   assert.ok(calls.includes('clear-reconnect-ref'));
   assert.ok(calls.includes('destroy-immersion'));
   assert.ok(calls.includes('clear-immersion-ref'));
+  assert.ok(calls.indexOf('destroy-immersion') < calls.indexOf('clear-immersion-ref'));
   assert.ok(calls.includes('destroy-first-run-window'));
   assert.ok(calls.includes('destroy-yomitan-settings-window'));
   assert.ok(calls.includes('stop-jellyfin-remote'));
+  assert.ok(calls.includes('cleanup-internal-subtitles'));
   assert.ok(calls.includes('cleanup-youtube-subtitles'));
   assert.ok(calls.includes('cleanup-youtube-media'));
   assert.ok(calls.includes('cleanup-jellyfin-subtitles'));
@@ -141,6 +151,7 @@ test('cleanup deps builder skips destroyed yomitan window', () => {
     clearReconnectTimerRef: () => {},
     getSubtitleTimingTracker: () => null,
     getImmersionTracker: () => null,
+    stopStatsServer: () => {},
     clearImmersionTracker: () => {},
     getAnkiIntegration: () => null,
     getAnilistSetupWindow: () => null,
@@ -152,8 +163,10 @@ test('cleanup deps builder skips destroyed yomitan window', () => {
     getYomitanSettingsWindow: () => null,
     clearYomitanSettingsWindow: () => {},
     stopJellyfinRemoteSession: () => {},
+    cleanupInternalSubtitleTrackCache: () => {},
     cleanupYoutubeSubtitleTempDirs: () => {},
     cleanupYoutubeMediaCache: () => {},
+    cleanupRemoteMediaWindows: () => {},
     cleanupJellyfinSubtitleCache: () => {},
     stopDiscordPresenceService: () => {},
   });
@@ -193,6 +206,7 @@ test('cleanup deps builder skips global shortcut cleanup before app ready', () =
     clearReconnectTimerRef: () => {},
     getSubtitleTimingTracker: () => null,
     getImmersionTracker: () => null,
+    stopStatsServer: () => {},
     clearImmersionTracker: () => {},
     getAnkiIntegration: () => null,
     getAnilistSetupWindow: () => null,
@@ -204,8 +218,10 @@ test('cleanup deps builder skips global shortcut cleanup before app ready', () =
     getYomitanSettingsWindow: () => null,
     clearYomitanSettingsWindow: () => {},
     stopJellyfinRemoteSession: () => {},
+    cleanupInternalSubtitleTrackCache: () => {},
     cleanupYoutubeSubtitleTempDirs: () => {},
     cleanupYoutubeMediaCache: () => {},
+    cleanupRemoteMediaWindows: () => {},
     cleanupJellyfinSubtitleCache: () => {},
     stopDiscordPresenceService: () => {},
   });
diff --git a/src/main/runtime/app-lifecycle-main-cleanup.ts b/src/main/runtime/app-lifecycle-main-cleanup.ts
index 54b751f7..888c0a1f 100644
--- a/src/main/runtime/app-lifecycle-main-cleanup.ts
+++ b/src/main/runtime/app-lifecycle-main-cleanup.ts
@@ -44,7 +44,8 @@ export function createBuildOnWillQuitCleanupDepsHandler(deps: {
   clearReconnectTimerRef: () => void;
 
   getSubtitleTimingTracker: () => Destroyable | null;
-  getImmersionTracker: () => Destroyable | null;
+  getImmersionTracker: () => { destroy: () => void | Promise<void> } | null;
+  stopStatsServer: () => Promise<void> | void;
   clearImmersionTracker: () => void;
   getAnkiIntegration: () => Destroyable | null;
 
@@ -58,8 +59,10 @@ export function createBuildOnWillQuitCleanupDepsHandler(deps: {
   clearYomitanSettingsWindow: () => void;
 
   stopJellyfinRemoteSession: () => void;
+  cleanupInternalSubtitleTrackCache: () => void;
   cleanupYoutubeSubtitleTempDirs: () => void;
   cleanupYoutubeMediaCache: () => void;
+  cleanupRemoteMediaWindows: () => void;
   cleanupJellyfinSubtitleCache: () => void;
   stopDiscordPresenceService: () => void;
 }) {
@@ -118,10 +121,11 @@ export function createBuildOnWillQuitCleanupDepsHandler(deps: {
     destroySubtitleTimingTracker: () => {
       deps.getSubtitleTimingTracker()?.destroy();
     },
-    destroyImmersionTracker: () => {
+    stopStatsServer: () => deps.stopStatsServer(),
+    destroyImmersionTracker: async () => {
       const tracker = deps.getImmersionTracker();
       if (!tracker) return;
-      tracker.destroy();
+      await tracker.destroy();
       deps.clearImmersionTracker();
     },
     destroyAnkiIntegration: () => {
@@ -144,8 +148,10 @@ export function createBuildOnWillQuitCleanupDepsHandler(deps: {
     },
     clearYomitanSettingsWindow: () => deps.clearYomitanSettingsWindow(),
     stopJellyfinRemoteSession: () => deps.stopJellyfinRemoteSession(),
+    cleanupInternalSubtitleTrackCache: () => deps.cleanupInternalSubtitleTrackCache(),
     cleanupYoutubeSubtitleTempDirs: () => deps.cleanupYoutubeSubtitleTempDirs(),
     cleanupYoutubeMediaCache: () => deps.cleanupYoutubeMediaCache(),
+    cleanupRemoteMediaWindows: () => deps.cleanupRemoteMediaWindows(),
     cleanupJellyfinSubtitleCache: () => deps.cleanupJellyfinSubtitleCache(),
     stopDiscordPresenceService: () => deps.stopDiscordPresenceService(),
   });
diff --git a/src/main/runtime/autoplay-subtitle-priming-runtime.test.ts b/src/main/runtime/autoplay-subtitle-priming-runtime.test.ts
index 25f0ef52..0a2c1f4d 100644
--- a/src/main/runtime/autoplay-subtitle-priming-runtime.test.ts
+++ b/src/main/runtime/autoplay-subtitle-priming-runtime.test.ts
@@ -1,5 +1,6 @@
 import assert from 'node:assert/strict';
 import test from 'node:test';
+import { parseSubtitleCues } from '../../core/services/subtitle-cue-parser';
 import { createSubtitleProcessingController } from '../../core/services/subtitle-processing-controller';
 import type { SubtitleData } from '../../types';
 import {
@@ -211,6 +212,69 @@ test('primeCurrentSubtitleForAutoplay emits raw first paint on cache miss before
   ]);
 });
 
+test('parsed cues replace a duplicate raw autoplay subtitle that was already primed', async () => {
+  const rawText = 'ジグザグな道を抜け\nジグザグな道を抜け';
+  const correctedText = 'ジグザグな道を抜け';
+  const mediaPath = '/media/video.mkv';
+  let currentSubText = '';
+  const emitted: string[] = [];
+  const client = {
+    connected: true,
+    currentVideoPath: mediaPath,
+    currentTimePos: 90,
+    currentSubText: rawText,
+    requestProperty: async (name: string) => {
+      if (name === 'sub-text') return rawText;
+      if (name === 'time-pos') return 90;
+      return null;
+    },
+  };
+  const cues = parseSubtitleCues(
+    [
+      '[Events]',
+      'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+      `Dialogue: 1,0:01:29.00,0:01:32.00,EDJP,,0,0,0,,${correctedText}`,
+      `Dialogue: 0,0:01:29.00,0:01:32.00,EDJP,,0,0,0,,${correctedText}`,
+    ].join('\n'),
+    'startup-ending.ass',
+  );
+  let activeCues = cues.slice(0, 0);
+  const runtime = createAutoplaySubtitlePrimingRuntime({
+    getCurrentMediaPath: () => mediaPath,
+    getMpvClient: () => client,
+    setCurrentSubText: (text) => {
+      currentSubText = text;
+    },
+    getCurrentSubText: () => currentSubText,
+    getCurrentSubtitleData: () => null,
+    getActiveParsedSubtitleCues: () => activeCues,
+    setActiveParsedSubtitleMediaPath: () => {},
+    subtitleProcessingController: {
+      consumeCachedSubtitle: () => null,
+      onSubtitleChange: () => true,
+      refreshCurrentSubtitle: () => true,
+      notePlainSubtitleEmitted: () => {},
+    },
+    emitSubtitlePayload: (payload) => emitted.push(payload.text),
+    getSubtitlePrefetchService: () => null,
+    getLastObservedTimePos: () => 90,
+    getVisibleOverlayVisible: () => true,
+    emitSecondarySubtitle: () => {},
+    initSubtitlePrefetch: async () => {},
+    refreshSubtitlePrefetchFromActiveTrack: async () => {},
+    logDebug: () => {},
+  });
+
+  await runtime.primeCurrentSubtitleForAutoplay(mediaPath);
+  assert.equal(currentSubText, rawText);
+
+  activeCues = cues;
+  await runtime.primeAutoplaySubtitleFromParsedCues(mediaPath, cues);
+
+  assert.equal(currentSubText, correctedText);
+  assert.deepEqual(emitted, [rawText, correctedText]);
+});
+
 // Driven by the real processing controller rather than a stub: the failure this
 // covers is a disagreement between the priming path and the controller's own
 // staleness rules, which a hand-written stub cannot reproduce.
diff --git a/src/main/runtime/autoplay-subtitle-priming-runtime.ts b/src/main/runtime/autoplay-subtitle-priming-runtime.ts
index fbf294e0..3ce188a2 100644
--- a/src/main/runtime/autoplay-subtitle-priming-runtime.ts
+++ b/src/main/runtime/autoplay-subtitle-priming-runtime.ts
@@ -12,6 +12,7 @@ type AutoplaySubtitlePrimingMpvClient = {
   requestProperty: (name: string) => Promise<unknown>;
   currentVideoPath?: string;
   currentTimePos?: number;
+  currentSubText?: string;
   currentSecondarySubText?: string;
   setCurrentSecondarySubText?: (text: string) => void;
 };
@@ -107,11 +108,19 @@ export function createAutoplaySubtitlePrimingRuntime(deps: AutoplaySubtitlePrimi
     autoplaySubtitlePrimedMediaPath = null;
   }
 
-  function emitAutoplayPrimedSubtitle(mediaPath: string, text: string): boolean {
+  function emitAutoplayPrimedSubtitle(
+    mediaPath: string,
+    text: string,
+    options: { replaceExisting?: boolean } = {},
+  ): boolean {
     if (!text.trim() || !isCurrentAutoplayMediaPath(mediaPath)) {
       return false;
     }
-    if (!markAutoplaySubtitlePrimeConsumed(mediaPath)) {
+    if (autoplaySubtitlePrimedMediaPath === mediaPath) {
+      if (!options.replaceExisting || deps.getCurrentSubText() === text) {
+        return false;
+      }
+    } else if (!markAutoplaySubtitlePrimeConsumed(mediaPath)) {
       return false;
     }
 
@@ -252,11 +261,7 @@ export function createAutoplaySubtitlePrimingRuntime(deps: AutoplaySubtitlePrimi
     mediaPath: string,
     cues: SubtitleCue[],
   ): Promise<void> {
-    if (
-      cues.length === 0 ||
-      autoplaySubtitlePrimedMediaPath === mediaPath ||
-      !isCurrentAutoplayMediaPath(mediaPath)
-    ) {
+    if (cues.length === 0 || !isCurrentAutoplayMediaPath(mediaPath)) {
       return;
     }
 
@@ -265,16 +270,21 @@ export function createAutoplaySubtitlePrimingRuntime(deps: AutoplaySubtitlePrimi
     const currentTimeSeconds = Number(
       timePosRaw ?? client?.currentTimePos ?? deps.getLastObservedTimePos() ?? 0,
     );
+    const resolvedTimeSeconds = Number.isFinite(currentTimeSeconds) ? currentTimeSeconds : 0;
     const cue = selectAutoplayStartupCue(
       cues,
-      Number.isFinite(currentTimeSeconds) ? currentTimeSeconds : 0,
+      resolvedTimeSeconds,
       AUTOPLAY_SUBTITLE_PRIME_LOOKAHEAD_SECONDS,
     );
-    if (!cue) {
+    const liveText = client?.currentSubText ?? '';
+    const text = liveText.trim()
+      ? resolvePrimarySubtitleText({ liveText, currentTimeSec: resolvedTimeSeconds, cues })
+      : (cue?.text ?? '');
+    if (!text) {
       return;
     }
 
-    emitAutoplayPrimedSubtitle(mediaPath, cue.text);
+    emitAutoplayPrimedSubtitle(mediaPath, text, { replaceExisting: true });
   }
 
   function clearScheduledSubtitlePrefetchRefresh(): void {
diff --git a/src/main/runtime/background-stats-startup.test.ts b/src/main/runtime/background-stats-startup.test.ts
index a2477a7f..c3a5c557 100644
--- a/src/main/runtime/background-stats-startup.test.ts
+++ b/src/main/runtime/background-stats-startup.test.ts
@@ -24,10 +24,10 @@ function createDeps(
   return { deps, calls };
 }
 
-test('ensures background stats server and logs local startup', () => {
+test('ensures background stats server and logs local startup', async () => {
   const { deps, calls } = createDeps();
 
-  createEnsureBackgroundStatsServerHandler(deps)();
+  await createEnsureBackgroundStatsServerHandler(deps)();
 
   assert.ok(calls.includes('ensureBackgroundStatsServerStarted'));
   assert.ok(
@@ -35,7 +35,7 @@ test('ensures background stats server and logs local startup', () => {
   );
 });
 
-test('logs reuse when a background stats server is already running', () => {
+test('logs reuse when a background stats server is already running', async () => {
   const { deps, calls } = createDeps({
     ensureBackgroundStatsServerStarted: () => ({
       url: 'http://127.0.0.1:3888',
@@ -43,36 +43,53 @@ test('logs reuse when a background stats server is already running', () => {
     }),
   });
 
-  createEnsureBackgroundStatsServerHandler(deps)();
+  await createEnsureBackgroundStatsServerHandler(deps)();
 
   assert.ok(
     calls.some((value) => value.startsWith('info:') && /already running|reusing/i.test(value)),
   );
 });
 
-test('skips when stats.autoStartServer is disabled', () => {
+test('skips when stats.autoStartServer is disabled', async () => {
   const { deps, calls } = createDeps({ isStatsAutoStartEnabled: () => false });
 
-  createEnsureBackgroundStatsServerHandler(deps)();
+  await createEnsureBackgroundStatsServerHandler(deps)();
 
   assert.equal(calls.includes('ensureBackgroundStatsServerStarted'), false);
 });
 
-test('skips when immersion tracking is disabled', () => {
+test('skips when immersion tracking is disabled', async () => {
   const { deps, calls } = createDeps({ isImmersionTrackingEnabled: () => false });
 
-  createEnsureBackgroundStatsServerHandler(deps)();
+  await createEnsureBackgroundStatsServerHandler(deps)();
 
   assert.equal(calls.includes('ensureBackgroundStatsServerStarted'), false);
 });
 
-test('logs a warning instead of throwing when startup fails', () => {
+test('logs a warning instead of throwing when startup fails', async () => {
   const { deps, calls } = createDeps({
     ensureBackgroundStatsServerStarted: () => {
       throw new Error('port in use');
     },
   });
 
-  assert.doesNotThrow(() => createEnsureBackgroundStatsServerHandler(deps)());
+  await assert.doesNotReject(createEnsureBackgroundStatsServerHandler(deps)());
   assert.ok(calls.some((value) => value.startsWith('warn:')));
 });
+
+test('logs an asynchronously reported startup failure', async () => {
+  const { deps, calls } = createDeps({
+    ensureBackgroundStatsServerStarted: async () => {
+      await Promise.resolve();
+      throw new Error('address in use');
+    },
+  });
+
+  await createEnsureBackgroundStatsServerHandler(deps)();
+
+  assert.ok(calls.some((value) => value.startsWith('warn:')));
+  assert.equal(
+    calls.some((value) => value.startsWith('info:')),
+    false,
+  );
+});
diff --git a/src/main/runtime/background-stats-startup.ts b/src/main/runtime/background-stats-startup.ts
index 3cdd5754..b03c0ad3 100644
--- a/src/main/runtime/background-stats-startup.ts
+++ b/src/main/runtime/background-stats-startup.ts
@@ -1,18 +1,23 @@
 export interface EnsureBackgroundStatsServerDeps {
   isStatsAutoStartEnabled: () => boolean;
   isImmersionTrackingEnabled: () => boolean;
-  ensureBackgroundStatsServerStarted: () => {
-    url: string;
-    runningInCurrentProcess: boolean;
-  };
+  ensureBackgroundStatsServerStarted: () =>
+    | Promise<{
+        url: string;
+        runningInCurrentProcess: boolean;
+      }>
+    | {
+        url: string;
+        runningInCurrentProcess: boolean;
+      };
   logInfo: (message: string) => void;
   logWarn: (message: string, error?: unknown) => void;
 }
 
 export function createEnsureBackgroundStatsServerHandler(
   deps: EnsureBackgroundStatsServerDeps,
-): () => void {
-  return () => {
+): () => Promise<void> {
+  return async () => {
     if (!deps.isStatsAutoStartEnabled()) {
       deps.logInfo('Background start: stats.autoStartServer is disabled; skipping stats server.');
       return;
@@ -22,7 +27,7 @@ export function createEnsureBackgroundStatsServerHandler(
       return;
     }
     try {
-      const result = deps.ensureBackgroundStatsServerStarted();
+      const result = await deps.ensureBackgroundStatsServerStarted();
       deps.logInfo(
         result.runningInCurrentProcess
           ? `Background start: stats server started at ${result.url}.`
diff --git a/src/main/runtime/command-line-launcher-deps.ts b/src/main/runtime/command-line-launcher-deps.ts
index 69b654af..58f01693 100644
--- a/src/main/runtime/command-line-launcher-deps.ts
+++ b/src/main/runtime/command-line-launcher-deps.ts
@@ -32,6 +32,8 @@ export type CommonOptions = FsDeps & {
   resourcesPath?: string;
   appExePath?: string;
   launcherResourcePath?: string;
+  bundledBunPath?: string;
+  appVersion?: string;
   runCommand?: RunCommand;
 };
 
@@ -143,8 +145,40 @@ function needsWindowsShell(command: string): boolean {
   return process.platform === 'win32' && /\.(cmd|bat)$/i.test(command);
 }
 
-function quoteForWindowsShell(value: string): string {
-  return `"${value.replace(/([&|<>^%!])/g, '^$1').replace(/"/g, '""')}"`;
+/*!
+ * Windows command escaping adapted from cross-spawn 7.0.6.
+ *
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2018 Made With MOXY Lda <hello@moxy.studio>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+const WINDOWS_SHELL_META_CHARACTERS = /([()\][%!^"`<>&|;, *?])/g;
+
+// Quote for both cmd.exe and the Windows argv parser. The outer caret escapes
+// are consumed by cmd, leaving the quoted argument unchanged for the command.
+function escapeWindowsShellArgument(value: string): string {
+  const quotesEscaped = value
+    .replace(/(?=(\\+?)?)\1"/g, '$1$1\\"')
+    .replace(/(?=(\\+?)?)\1$/, '$1$1');
+  return `"${quotesEscaped}"`.replace(WINDOWS_SHELL_META_CHARACTERS, '^$1');
 }
 
 function createDefaultRunCommand(): RunCommand {
@@ -153,16 +187,24 @@ function createDefaultRunCommand(): RunCommand {
       const useShell = needsWindowsShell(command);
       let child: ReturnType<typeof spawn>;
       try {
-        child = useShell
-          ? spawn(quoteForWindowsShell(command), args.map(quoteForWindowsShell), {
-              env: options.env ?? process.env,
-              windowsHide: false,
-              shell: true,
-            })
-          : spawn(command, args, {
-              env: options.env ?? process.env,
-              windowsHide: false,
-            });
+        const env = options.env ?? process.env;
+        if (useShell) {
+          const shellCommand = [
+            escapeWindowsShellArgument(command),
+            ...args.map(escapeWindowsShellArgument),
+          ].join(' ');
+          const commandProcessor = env.ComSpec ?? env.COMSPEC ?? process.env.ComSpec ?? 'cmd.exe';
+          child = spawn(commandProcessor, ['/d', '/s', '/v:off', '/c', `"${shellCommand}"`], {
+            env,
+            windowsHide: false,
+            windowsVerbatimArguments: true,
+          });
+        } else {
+          child = spawn(command, args, {
+            env,
+            windowsHide: false,
+          });
+        }
       } catch (error) {
         resolve({
           exitCode: 1,
diff --git a/src/main/runtime/command-line-launcher.test.ts b/src/main/runtime/command-line-launcher.test.ts
index 68e516b4..97e29600 100644
--- a/src/main/runtime/command-line-launcher.test.ts
+++ b/src/main/runtime/command-line-launcher.test.ts
@@ -91,43 +91,54 @@ test('resolveBunInstallCommand prefers winget on Windows', () => {
 test('default runCommand preserves Windows cmd metacharacter args', async (t) => {
   if (process.platform !== 'win32') return;
 
-  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'subminer-cmd-args-'));
+  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'subminer cmd & 100% ! '));
   const scriptPath = path.join(tempDir, 'argv.cmd');
-  const outputPath = path.join(tempDir, 'argv.txt');
+  const argvScriptPath = path.join(tempDir, 'argv.js');
   t.after(() => {
     fs.rmSync(tempDir, { recursive: true, force: true });
   });
+  fs.writeFileSync(
+    argvScriptPath,
+    'process.stdout.write(JSON.stringify(process.argv.slice(2)));',
+    'utf8',
+  );
   fs.writeFileSync(
     scriptPath,
     [
       '@echo off',
       'setlocal DisableDelayedExpansion',
-      '> "%SUBMINER_ARGV_OUT%" (',
-      '  echo 1=%~1',
-      '  echo 2=%~2',
-      '  echo 3=%~3',
-      '  echo 4=%~4',
-      '  echo 5=%~5',
-      '  echo 6=%~6',
-      ')',
+      '"%SUBMINER_TEST_RUNTIME%" "%SUBMINER_ARGV_SCRIPT%" %*',
+      'exit /b %errorlevel%',
       '',
     ].join('\r\n'),
     'utf8',
   );
 
-  const result = await getRunCommand({})(
-    scriptPath,
-    ['plain', 'has space', 'a&b', 'x|y', 'p%PATH%q', 'bang!z'],
-    {
-      env: { ...process.env, SUBMINER_ARGV_OUT: outputPath },
+  const args = [
+    'plain',
+    'has space',
+    'a&b',
+    'x|y',
+    'p%TEMP%q',
+    'bang!z',
+    'caret^z',
+    '<left>',
+    'say "hi"',
+    'slash\\"quote',
+    'trailing\\',
+    '',
+    '日本語',
+  ];
+  const result = await getRunCommand({})(scriptPath, args, {
+    env: {
+      ...process.env,
+      SUBMINER_ARGV_SCRIPT: argvScriptPath,
+      SUBMINER_TEST_RUNTIME: process.execPath,
     },
-  );
+  });
 
   assert.equal(result.exitCode, 0, result.stderr);
-  assert.equal(
-    fs.readFileSync(outputPath, 'utf8'),
-    ['1=plain', '2=has space', '3=a&b', '4=x|y', '5=p%PATH%q', '6=bang!z', ''].join('\r\n'),
-  );
+  assert.deepEqual(JSON.parse(result.stdout), args);
 });
 
 test('resolveBunInstallCommand falls back to scoop on Windows before official installer', () => {
@@ -189,7 +200,7 @@ test('resolveLauncherInstallTarget prefers writable user bin on Linux', async ()
   assert.equal(target.installPath, '/home/tester/.local/bin/subminer');
 });
 
-test('resolveLauncherInstallTarget returns not_installable without writable PATH dirs', async () => {
+test('resolveLauncherInstallTarget offers a user bin without writable PATH dirs', async () => {
   const target = await resolveLauncherInstallTarget({
     platform: 'linux',
     homeDir: '/home/tester',
@@ -200,8 +211,9 @@ test('resolveLauncherInstallTarget returns not_installable without writable PATH
     },
   });
 
-  assert.equal(target.status, 'not_installable');
-  assert.equal(target.installPath, null);
+  assert.equal(target.status, 'not_installed');
+  assert.equal(target.installPath, '/home/tester/.local/bin/subminer');
+  assert.match(target.message ?? '', /export PATH=/);
 });
 
 test('resolveLauncherInstallTarget skips Homebrew bin for empty macOS manual installs', async () => {
diff --git a/src/main/runtime/command-line-launcher.ts b/src/main/runtime/command-line-launcher.ts
index 0194b4b5..eab7c053 100644
--- a/src/main/runtime/command-line-launcher.ts
+++ b/src/main/runtime/command-line-launcher.ts
@@ -1,6 +1,13 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import {
+  cleanupOldWindowsManagedRuntimes,
+  isManagedLauncher,
+  managedLauncherContent,
+  shellQuote,
+  stageManagedLauncher,
+} from './managed-launcher';
 import {
   accessSyncOf,
   envOf,
@@ -115,8 +122,13 @@ export function resolveBunInstallCommand(
 }
 
 export async function detectBun(options: CommonOptions = {}): Promise<BunSnapshot> {
-  const bunPath = findCommand('bun', options);
-  const installCommand = resolveBunInstallCommand(options);
+  const bundled = options.bundledBunPath;
+  const bunPath = bundled
+    ? existsSyncOf(options)(bundled)
+      ? bundled
+      : null
+    : findCommand('bun', options);
+  const installCommand = bundled ? null : resolveBunInstallCommand(options);
   if (!bunPath) {
     return {
       status: 'missing',
@@ -124,7 +136,9 @@ export async function detectBun(options: CommonOptions = {}): Promise<BunSnapsho
       version: null,
       installMethod: installMethodForCommand(installCommand),
       installCommand,
-      message: null,
+      message: bundled
+        ? 'The included launcher runtime is missing. Reinstall SubMiner to repair it.'
+        : null,
     };
   }
 
@@ -139,7 +153,7 @@ export async function detectBun(options: CommonOptions = {}): Promise<BunSnapsho
       version: result.stdout.trim() || null,
       installMethod: null,
       installCommand: null,
-      message: null,
+      message: bundled ? 'Included with SubMiner. No separate Bun installation is needed.' : null,
     };
   }
 
@@ -158,9 +172,11 @@ export function resolveLauncherResourcePath(options: CommonOptions): string {
   if (options.launcherResourcePath) return options.launcherResourcePath;
   const resourcesPath =
     options.resourcesPath ?? (process as typeof process & { resourcesPath?: string }).resourcesPath;
-  const packaged = resourcesPath ? platformPath.join(resourcesPath, 'launcher', 'subminer') : null;
+  const packaged = resourcesPath
+    ? platformPath.join(resourcesPath, 'launcher', 'subminer.js')
+    : null;
   if (packaged && existsSyncOf(options)(packaged)) return packaged;
-  return platformPath.join(options.cwd ?? process.cwd(), 'dist', 'launcher', 'subminer');
+  return platformPath.join(options.cwd ?? process.cwd(), 'dist', 'launcher', 'subminer.js');
 }
 
 function isWritableDir(candidate: string, options: CommonOptions): boolean {
@@ -183,6 +199,21 @@ function collectPathDirs(options: CommonOptions): string[] {
   return dirs;
 }
 
+function preferredLauncherDirs(platform: NodeJS.Platform, homeDir: string): string[] {
+  return platform === 'darwin'
+    ? [
+        '/opt/homebrew/bin',
+        '/usr/local/bin',
+        path.posix.join(homeDir, '.local', 'bin'),
+        path.posix.join(homeDir, 'bin'),
+      ]
+    : [
+        path.posix.join(homeDir, '.local', 'bin'),
+        path.posix.join(homeDir, 'bin'),
+        '/usr/local/bin',
+      ];
+}
+
 export async function resolveLauncherInstallTarget(
   options: CommonOptions & WindowsPathOptions = {},
 ): Promise<LauncherSnapshot> {
@@ -201,19 +232,7 @@ export async function resolveLauncherInstallTarget(
 
   const homeDir = options.homeDir ?? os.homedir();
   const pathDirs = collectPathDirs(options);
-  const preferred =
-    platform === 'darwin'
-      ? [
-          '/opt/homebrew/bin',
-          '/usr/local/bin',
-          path.posix.join(homeDir, '.local', 'bin'),
-          path.posix.join(homeDir, 'bin'),
-        ]
-      : [
-          path.posix.join(homeDir, '.local', 'bin'),
-          path.posix.join(homeDir, 'bin'),
-          '/usr/local/bin',
-        ];
+  const preferred = preferredLauncherDirs(platform, homeDir);
   const manualPreferred =
     platform === 'darwin'
       ? [
@@ -251,13 +270,15 @@ export async function resolveLauncherInstallTarget(
       isWritableDir(dir, options),
   );
   if (!selected) {
+    const pathDir = path.posix.join(homeDir, '.local', 'bin');
+    const installPath = path.posix.join(pathDir, 'subminer');
     return {
-      status: 'not_installable',
-      commandPath: null,
-      installPath: null,
-      pathDir: null,
+      status: existsSyncOf(options)(installPath) ? 'not_on_path' : 'not_installed',
+      commandPath: existsSyncOf(options)(installPath) ? installPath : null,
+      installPath,
+      pathDir,
       shadowedBy: null,
-      message: 'No writable directory was found on your command-line PATH.',
+      message: `Add ${pathDir} to your terminal PATH: export PATH=${shellQuote(pathDir)}:"$PATH". Save this in your shell configuration for future terminals.`,
     };
   }
   const installPath = path.posix.join(selected, 'subminer');
@@ -283,7 +304,29 @@ export async function detectLauncher(
   const launcherResourcePath = resolveLauncherResourcePath(options);
   const appExePath = options.appExePath ?? process.execPath;
 
-  if (platform === 'win32' && existsSyncOf(options)(expectedPath)) {
+  if (options.bundledBunPath && existsSyncOf(options)(expectedPath)) {
+    const content = String((options.readFileSync ?? fs.readFileSync)(expectedPath, 'utf8'));
+    if (!isManagedLauncher(content)) {
+      return {
+        ...target,
+        status: 'not_installed',
+        message: 'Reinstall the launcher to use the runtime included with SubMiner.',
+      };
+    }
+    if (
+      content !==
+      managedLauncherContent({
+        platform,
+        appPath: envOf(options).APPIMAGE ?? appExePath,
+      })
+    ) {
+      return {
+        ...target,
+        status: 'not_installed',
+        message: 'Reinstall the launcher to refresh its SubMiner location.',
+      };
+    }
+  } else if (platform === 'win32' && existsSyncOf(options)(expectedPath)) {
     const content = String((options.readFileSync ?? fs.readFileSync)(expectedPath, 'utf8'));
     if (!shimMatchesCurrentInstall(content, appExePath, launcherResourcePath)) {
       return {
@@ -305,26 +348,19 @@ export async function detectLauncher(
   }
   if (!existsSyncOf(options)(expectedPath))
     return { ...target, status: 'not_installed', commandPath: null };
-  if (!commandPath) {
-    return {
-      ...target,
-      status: 'not_on_path',
-      commandPath: expectedPath,
-      message: 'Launcher exists but its directory is not on PATH.',
-    };
-  }
-
   const bunSnapshot = options.bunSnapshot ?? (await detectBun(options));
   if (bunSnapshot.status !== 'ready') {
     return {
       ...target,
       status: 'installed_bun_missing',
       commandPath,
-      message: 'Launcher is installed, but Bun is missing. Install Bun, then open a new terminal.',
+      message: options.bundledBunPath
+        ? bunSnapshot.message
+        : 'Launcher is installed, but Bun is missing. Install Bun, then open a new terminal.',
     };
   }
 
-  const result = await getRunCommand(options)(commandPath, ['--help'], {
+  const result = await getRunCommand(options)(expectedPath, ['--help'], {
     timeoutMs: COMMAND_TIMEOUT_MS,
     env: envOf(options) as NodeJS.ProcessEnv,
   });
@@ -336,6 +372,16 @@ export async function detectLauncher(
       message: failureMessage(result, 'subminer --help failed'),
     };
   }
+  if (!commandPath) {
+    return {
+      ...target,
+      status: 'not_on_path',
+      commandPath: expectedPath,
+      message:
+        target.message ??
+        `Launcher installed. Add ${target.pathDir} to your terminal PATH: export PATH=${shellQuote(target.pathDir ?? '')}:"$PATH". Save this in your shell configuration for future terminals.`,
+    };
+  }
   return { ...target, status: 'ready', commandPath, message: null };
 }
 
@@ -354,6 +400,48 @@ export async function installLauncher(
     };
   }
 
+  if (options.bundledBunPath) {
+    const bun = await detectBun(options);
+    if (bun.status !== 'ready')
+      return {
+        ...target,
+        status: 'failed',
+        message: bun.message ?? 'The included launcher runtime failed to start.',
+      };
+    try {
+      stageManagedLauncher({
+        ...options,
+        bundledBunPath: options.bundledBunPath,
+        launcherResourcePath,
+        force: true,
+      });
+      (options.mkdirSync ?? fs.mkdirSync)(target.pathDir, { recursive: true });
+      (options.writeFileSync ?? fs.writeFileSync)(
+        target.installPath,
+        managedLauncherContent({
+          platform,
+          appPath: envOf(options).APPIMAGE ?? options.appExePath ?? process.execPath,
+        }),
+      );
+      (options.chmodSync ?? fs.chmodSync)(target.installPath, 0o755);
+      if (platform === 'win32') {
+        cleanupOldWindowsManagedRuntimes(options);
+        const nextPath = await appendWindowsUserPathDir(target.pathDir, options);
+        if (nextPath && options.env) {
+          options.env.PATH = nextPath;
+          options.env.Path = nextPath;
+        }
+      }
+      return await detectLauncher({ ...options, bunSnapshot: bun });
+    } catch (error) {
+      return {
+        ...target,
+        status: 'failed',
+        message: error instanceof Error ? error.message : String(error),
+      };
+    }
+  }
+
   if (platform === 'win32') {
     (options.mkdirSync ?? fs.mkdirSync)(target.pathDir, { recursive: true });
     (options.writeFileSync ?? fs.writeFileSync)(
@@ -375,6 +463,8 @@ export async function installLauncher(
       };
     }
   } else {
+    if (!existsSyncOf(options)(target.pathDir))
+      (options.mkdirSync ?? fs.mkdirSync)(target.pathDir, { recursive: true });
     (options.copyFileSync ?? fs.copyFileSync)(launcherResourcePath, target.installPath);
     (options.chmodSync ?? fs.chmodSync)(target.installPath, 0o755);
   }
@@ -384,6 +474,7 @@ export async function installLauncher(
 export async function installBun(
   options: CommonOptions & WindowsPathOptions = {},
 ): Promise<BunSnapshot> {
+  if (options.bundledBunPath) return detectBun(options);
   const platform = platformOf(options);
   if (platform === 'win32') {
     const bunDir = defaultBunRepairPath(options);
@@ -455,6 +546,84 @@ export async function installBun(
   };
 }
 
+// Runs at app startup. Migrates recognized launchers in the standard bin dirs,
+// the setup install target, and any paths a deferred update handed over.
+// Returns paths that were refreshed or are no longer eligible for migration.
+export async function refreshManagedCommandLineLauncher(
+  options: CommonOptions & WindowsPathOptions & { additionalLauncherPaths?: string[] },
+): Promise<string[]> {
+  if (!options.bundledBunPath) return [];
+  const target = await resolveLauncherInstallTarget(options);
+  const platform = platformOf(options);
+  const platformPath = pathModuleFor(platform);
+  // cmd.exe reads a batch file incrementally while it runs, so the launcher that
+  // started this app is left alone until a later app start rewrites it.
+  const runningLauncherPath =
+    platform === 'win32' ? envOf(options).SUBMINER_LAUNCHER_PATH : undefined;
+  const isRunningLauncher = (candidate: string) =>
+    runningLauncherPath !== undefined &&
+    platformPath.normalize(candidate).toLowerCase() ===
+      platformPath.normalize(runningLauncherPath).toLowerCase();
+  const candidates = new Set([
+    ...(target.installPath ? [target.installPath] : []),
+    ...(options.additionalLauncherPaths ?? []),
+    ...(platform === 'win32'
+      ? []
+      : preferredLauncherDirs(platform, options.homeDir ?? os.homedir()).map((directory) =>
+          path.posix.join(directory, 'subminer'),
+        )),
+  ]);
+  const readFile = options.readFileSync ?? fs.readFileSync;
+  const acknowledgedPaths: string[] = [];
+  let payload: ReturnType<typeof stageManagedLauncher> | undefined;
+  for (const candidate of candidates) {
+    if (isRunningLauncher(candidate)) continue;
+    if (!existsSyncOf(options)(candidate)) {
+      acknowledgedPaths.push(candidate);
+      continue;
+    }
+    let existing: string;
+    try {
+      existing = String(readFile(candidate, 'utf8'));
+    } catch {
+      continue;
+    }
+    const legacy =
+      (existing.startsWith('#!/usr/bin/env bun\n') &&
+        (existing.includes('SubMiner launcher') ||
+          existing.includes('Launch MPV with SubMiner'))) ||
+      (platform === 'win32' &&
+        existing ===
+          windowsShimContent(
+            options.appExePath ?? process.execPath,
+            resolveLauncherResourcePath(options).replace(/subminer\.js$/, 'subminer'),
+          ));
+    if (!isManagedLauncher(existing) && !legacy) {
+      acknowledgedPaths.push(candidate);
+      continue;
+    }
+    if (!isWritableDir(pathModuleFor(platform).dirname(candidate), options)) continue;
+    try {
+      accessSyncOf(options)(candidate, fs.constants.W_OK);
+    } catch {
+      continue;
+    }
+    payload ??= stageManagedLauncher({
+      ...options,
+      bundledBunPath: options.bundledBunPath,
+      launcherResourcePath: resolveLauncherResourcePath(options),
+    });
+    const content = managedLauncherContent({
+      platform,
+      appPath: envOf(options).APPIMAGE ?? options.appExePath ?? process.execPath,
+    });
+    if (existing !== content) (options.writeFileSync ?? fs.writeFileSync)(candidate, content);
+    acknowledgedPaths.push(candidate);
+  }
+  if (platform === 'win32' && payload) cleanupOldWindowsManagedRuntimes(options);
+  return acknowledgedPaths;
+}
+
 export async function detectCommandLineLauncher(
   options: CommonOptions & WindowsPathOptions = {},
 ): Promise<CommandLineLauncherSnapshot> {
diff --git a/src/main/runtime/composers/jellyfin-remote-composer.ts b/src/main/runtime/composers/jellyfin-remote-composer.ts
index 2de85547..f16fe964 100644
--- a/src/main/runtime/composers/jellyfin-remote-composer.ts
+++ b/src/main/runtime/composers/jellyfin-remote-composer.ts
@@ -7,6 +7,7 @@ import {
   createHandleJellyfinRemoteGeneralCommand,
   createHandleJellyfinRemotePlay,
   createHandleJellyfinRemotePlaystate,
+  createJellyfinRemoteReportTracker,
   createReportJellyfinRemoteProgressHandler,
   createReportJellyfinRemoteStoppedHandler,
 } from '../domains/jellyfin';
@@ -91,13 +92,17 @@ export function composeJellyfinRemoteHandlers(
       getNow: options.getNow,
       ticksPerSecond: options.ticksPerSecond,
       logDebug: options.logDebug,
+      logWarn: options.logWarn,
     });
-  const reportJellyfinRemoteProgress = createReportJellyfinRemoteProgressHandler(
-    buildReportJellyfinRemoteProgressMainDepsHandler(),
-  );
-  const reportJellyfinRemoteStopped = createReportJellyfinRemoteStoppedHandler(
-    buildReportJellyfinRemoteStoppedMainDepsHandler(),
-  );
+  const reportTracker = createJellyfinRemoteReportTracker();
+  const reportJellyfinRemoteProgress = createReportJellyfinRemoteProgressHandler({
+    ...buildReportJellyfinRemoteProgressMainDepsHandler(),
+    reportTracker,
+  });
+  const reportJellyfinRemoteStopped = createReportJellyfinRemoteStoppedHandler({
+    ...buildReportJellyfinRemoteStoppedMainDepsHandler(),
+    reportTracker,
+  });
 
   const buildHandleJellyfinRemotePlayMainDepsHandler =
     createBuildHandleJellyfinRemotePlayMainDepsHandler({
diff --git a/src/main/runtime/composers/jellyfin-runtime-composer.test.ts b/src/main/runtime/composers/jellyfin-runtime-composer.test.ts
index ec2308c0..b587eabc 100644
--- a/src/main/runtime/composers/jellyfin-runtime-composer.test.ts
+++ b/src/main/runtime/composers/jellyfin-runtime-composer.test.ts
@@ -54,6 +54,7 @@ test('composeJellyfinRuntimeHandlers returns callable jellyfin runtime handlers'
       sleep: async () => {},
     },
     launchMpvIdleForJellyfinPlaybackMainDeps: {
+      getMpvExecutablePath: () => 'mpv',
       getSocketPath: () => '/tmp/test-mpv.sock',
       getLaunchMode: () => 'normal',
       platform: 'linux',
diff --git a/src/main/runtime/composers/startup-lifecycle-composer.test.ts b/src/main/runtime/composers/startup-lifecycle-composer.test.ts
index b4db3e1c..a1c484a4 100644
--- a/src/main/runtime/composers/startup-lifecycle-composer.test.ts
+++ b/src/main/runtime/composers/startup-lifecycle-composer.test.ts
@@ -38,6 +38,7 @@ test('composeStartupLifecycleHandlers returns callable startup lifecycle handler
       clearReconnectTimerRef: () => {},
       getSubtitleTimingTracker: () => null,
       getImmersionTracker: () => null,
+      stopStatsServer: () => {},
       clearImmersionTracker: () => {},
       getAnkiIntegration: () => null,
       getAnilistSetupWindow: () => null,
@@ -49,8 +50,10 @@ test('composeStartupLifecycleHandlers returns callable startup lifecycle handler
       getYomitanSettingsWindow: () => null,
       clearYomitanSettingsWindow: () => {},
       stopJellyfinRemoteSession: async () => {},
+      cleanupInternalSubtitleTrackCache: () => {},
       cleanupYoutubeSubtitleTempDirs: () => {},
       cleanupYoutubeMediaCache: () => {},
+      cleanupRemoteMediaWindows: () => {},
       cleanupJellyfinSubtitleCache: () => {},
       stopDiscordPresenceService: () => {},
     },
diff --git a/src/main/runtime/composers/startup-lifecycle-composer.ts b/src/main/runtime/composers/startup-lifecycle-composer.ts
index 07a15b8d..adcf5a1c 100644
--- a/src/main/runtime/composers/startup-lifecycle-composer.ts
+++ b/src/main/runtime/composers/startup-lifecycle-composer.ts
@@ -8,13 +8,10 @@ import {
   createBuildRestoreWindowsOnActivateMainDepsHandler,
   createBuildShouldRestoreWindowsOnActivateMainDepsHandler,
 } from '../app-lifecycle-main-activate';
-import { createBuildRegisterProtocolUrlHandlersMainDepsHandler } from '../protocol-url-handlers-main-deps';
 import { registerProtocolUrlHandlers } from '../protocol-url-handlers';
 import type { ComposerInputs, ComposerOutputs } from './contracts';
 
-type RegisterProtocolUrlHandlersMainDeps = Parameters<
-  typeof createBuildRegisterProtocolUrlHandlersMainDepsHandler
->[0];
+type RegisterProtocolUrlHandlersMainDeps = Parameters<typeof registerProtocolUrlHandlers>[0];
 type OnWillQuitCleanupDeps = Parameters<typeof createBuildOnWillQuitCleanupDepsHandler>[0];
 type ShouldRestoreWindowsOnActivateMainDeps = Parameters<
   typeof createBuildShouldRestoreWindowsOnActivateMainDepsHandler
@@ -32,7 +29,7 @@ export type StartupLifecycleComposerOptions = ComposerInputs<{
 
 export type StartupLifecycleComposerResult = ComposerOutputs<{
   registerProtocolUrlHandlers: () => void;
-  onWillQuitCleanup: () => void;
+  onWillQuitCleanup: () => Promise<void>;
   shouldRestoreWindowsOnActivate: () => boolean;
   restoreWindowsOnActivate: () => void;
 }>;
@@ -40,10 +37,6 @@ export type StartupLifecycleComposerResult = ComposerOutputs<{
 export function composeStartupLifecycleHandlers(
   options: StartupLifecycleComposerOptions,
 ): StartupLifecycleComposerResult {
-  const registerProtocolUrlHandlersMainDeps = createBuildRegisterProtocolUrlHandlersMainDepsHandler(
-    options.registerProtocolUrlHandlersMainDeps,
-  )();
-
   const onWillQuitCleanupHandler = createOnWillQuitCleanupHandler(
     createBuildOnWillQuitCleanupDepsHandler(options.onWillQuitCleanupMainDeps)(),
   );
@@ -58,9 +51,9 @@ export function composeStartupLifecycleHandlers(
 
   return {
     registerProtocolUrlHandlers: () =>
-      registerProtocolUrlHandlers(registerProtocolUrlHandlersMainDeps),
-    onWillQuitCleanup: () => onWillQuitCleanupHandler(),
-    shouldRestoreWindowsOnActivate: () => shouldRestoreWindowsOnActivateHandler(),
-    restoreWindowsOnActivate: () => restoreWindowsOnActivateHandler(),
+      registerProtocolUrlHandlers(options.registerProtocolUrlHandlersMainDeps),
+    onWillQuitCleanup: onWillQuitCleanupHandler,
+    shouldRestoreWindowsOnActivate: shouldRestoreWindowsOnActivateHandler,
+    restoreWindowsOnActivate: restoreWindowsOnActivateHandler,
   };
 }
diff --git a/src/main/runtime/config-hot-reload-handlers.test.ts b/src/main/runtime/config-hot-reload-handlers.test.ts
index d8b2b761..d7d49f7a 100644
--- a/src/main/runtime/config-hot-reload-handlers.test.ts
+++ b/src/main/runtime/config-hot-reload-handlers.test.ts
@@ -156,6 +156,7 @@ test('createConfigHotReloadAppliedHandler applies only changed Anki media option
   const config = deepCloneConfig(DEFAULT_CONFIG);
   config.ankiConnect.media.normalizeAudio = false;
   config.ankiConnect.media.mirrorMpvVolume = false;
+  config.ankiConnect.media.reviewTiming = true;
   const ankiPatches: unknown[] = [];
 
   const applyHotReload = createConfigHotReloadAppliedHandler({
@@ -181,10 +182,18 @@ test('createConfigHotReloadAppliedHandler applies only changed Anki media option
     },
     config,
   );
+  applyHotReload(
+    {
+      hotReloadFields: ['ankiConnect.media.reviewTiming'],
+      restartRequiredFields: [],
+    },
+    config,
+  );
 
   assert.deepEqual(ankiPatches, [
     { media: { normalizeAudio: false } },
     { media: { mirrorMpvVolume: false } },
+    { media: { reviewTiming: true } },
   ]);
 });
 
diff --git a/src/main/runtime/config-hot-reload-handlers.ts b/src/main/runtime/config-hot-reload-handlers.ts
index 1a74e9d1..9aece9d2 100644
--- a/src/main/runtime/config-hot-reload-handlers.ts
+++ b/src/main/runtime/config-hot-reload-handlers.ts
@@ -100,6 +100,9 @@ function buildAnkiRuntimeConfigPatch(
   if (diff.hotReloadFields.includes('ankiConnect.media.mirrorMpvVolume')) {
     mediaPatch.mirrorMpvVolume = config.ankiConnect.media.mirrorMpvVolume;
   }
+  if (diff.hotReloadFields.includes('ankiConnect.media.reviewTiming')) {
+    mediaPatch.reviewTiming = config.ankiConnect.media.reviewTiming;
+  }
   if (Object.keys(mediaPatch).length > 0) {
     patch.media = mediaPatch;
   }
@@ -134,6 +137,9 @@ function buildAnkiRuntimeConfigPatch(
   if (diff.hotReloadFields.includes('ankiConnect.isKiku.fieldGrouping')) {
     patch.isKiku = { fieldGrouping: config.ankiConnect.isKiku.fieldGrouping };
   }
+  if (diff.hotReloadFields.includes('ankiConnect.isSenren.fieldGrouping')) {
+    patch.isSenren = { fieldGrouping: config.ankiConnect.isSenren.fieldGrouping };
+  }
   if (diff.hotReloadFields.includes('ankiConnect.lapisKiku.wordCardKind')) {
     patch.lapisKiku = { wordCardKind: config.ankiConnect.lapisKiku.wordCardKind };
   }
@@ -157,7 +163,10 @@ export function createConfigHotReloadAppliedHandler(deps: ConfigHotReloadApplied
     deps.setKeybindings(payload.keybindings);
     deps.setSessionBindings(payload.sessionBindings, payload.sessionBindingWarnings);
 
-    if (diff.hotReloadFields.includes('shortcuts')) {
+    if (
+      diff.hotReloadFields.includes('shortcuts') ||
+      diff.hotReloadFields.includes('subtitleSelection')
+    ) {
       deps.refreshGlobalAndOverlayShortcuts();
     }
 
diff --git a/src/main/runtime/config-settings-runtime.test.ts b/src/main/runtime/config-settings-runtime.test.ts
index 77d2e714..85ebbdec 100644
--- a/src/main/runtime/config-settings-runtime.test.ts
+++ b/src/main/runtime/config-settings-runtime.test.ts
@@ -5,9 +5,91 @@ import os from 'node:os';
 import path from 'node:path';
 import { DEFAULT_CONFIG, deepCloneConfig } from '../../config';
 import { resolveConfig } from '../../config/resolve';
+import { buildConfigSettingsRegistry } from '../../config/settings/registry';
+import type { RawConfig } from '../../types/config';
 import { IPC_CHANNELS } from '../../shared/ipc/contracts';
 import { createConfigSettingsRuntime } from './config-settings-runtime';
 
+test('settings saves report live changes and only the sections that actually need restart', () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'subminer-settings-live-'));
+  const configPath = path.join(dir, 'config.jsonc');
+  let rawConfig: RawConfig = {};
+  let resolvedConfig = resolveConfig(rawConfig).resolved;
+  const applied: string[][] = [];
+  const runtime = createConfigSettingsRuntime({
+    fields: buildConfigSettingsRegistry(DEFAULT_CONFIG),
+    getConfigPath: () => configPath,
+    getRawConfig: () => rawConfig,
+    getConfig: () => resolvedConfig,
+    getWarnings: () => [],
+    reloadConfigStrict: () => {
+      rawConfig = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+      const result = resolveConfig(rawConfig);
+      resolvedConfig = result.resolved;
+      return { ok: true, config: resolvedConfig, warnings: result.warnings, path: configPath };
+    },
+    onHotReloadApplied: (diff) => {
+      applied.push(diff.hotReloadFields);
+    },
+    getSettingsWindow: () => null,
+    setSettingsWindow: () => {},
+    createSettingsWindow: () => {
+      throw new Error('Save must not open a window');
+    },
+    settingsHtmlPath: '/tmp/settings.html',
+    openPath: async () => '',
+    defaultAnkiConnectUrl: DEFAULT_CONFIG.ankiConnect.url,
+    createAnkiClient: () => {
+      throw new Error('Save must not query Anki');
+    },
+    ipcMain: { handle: () => {} },
+    ipcChannels: IPC_CHANNELS.request,
+  });
+
+  try {
+    const live = runtime.savePatch({
+      operations: [
+        { op: 'set', path: 'notifications.overlayPosition', value: 'top' },
+        {
+          op: 'set',
+          path: 'subtitleGeneration.threads',
+          value: DEFAULT_CONFIG.subtitleGeneration.threads + 1,
+        },
+      ],
+    });
+    assert.equal(live.ok, true);
+    assert.deepEqual(live.restartRequiredFields, []);
+    assert.deepEqual(live.restartRequiredSections, []);
+    assert.deepEqual(
+      new Set(live.hotReloadFields),
+      new Set(['notifications.overlayPosition', 'subtitleGeneration.threads']),
+    );
+    assert.deepEqual(applied, [live.hotReloadFields]);
+
+    const mixed = runtime.savePatch({
+      operations: [
+        { op: 'set', path: 'ankiConnect.deck', value: 'Mining' },
+        { op: 'set', path: 'ankiConnect.url', value: 'http://127.0.0.1:9999' },
+      ],
+    });
+    assert.equal(mixed.ok, true);
+    assert.deepEqual(mixed.hotReloadFields, ['ankiConnect.deck']);
+    assert.deepEqual(mixed.restartRequiredSections, ['AnkiConnect']);
+
+    const reset = runtime.savePatch({
+      operations: [
+        { op: 'reset', path: 'notifications.overlayPosition' },
+        { op: 'reset', path: 'subtitleGeneration.threads' },
+      ],
+    });
+    assert.equal(reset.ok, true);
+    assert.deepEqual(reset.restartRequiredSections, []);
+    assert.deepEqual(new Set(reset.hotReloadFields), new Set(live.hotReloadFields));
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
 test('config settings runtime exposes inferred Yomitan Anki deck lookup', async () => {
   const handlers = new Map<string, (event: unknown, ...args: unknown[]) => unknown>();
   const runtime = createConfigSettingsRuntime({
diff --git a/src/main/runtime/domains/anilist.ts b/src/main/runtime/domains/anilist.ts
index 6650c4ca..7cee9eda 100644
--- a/src/main/runtime/domains/anilist.ts
+++ b/src/main/runtime/domains/anilist.ts
@@ -13,4 +13,3 @@ export * from '../anilist-state';
 export * from '../anilist-token-refresh';
 export * from '../anilist-token-refresh-main-deps';
 export * from '../protocol-url-handlers';
-export * from '../protocol-url-handlers-main-deps';
diff --git a/src/main/runtime/first-run-setup-window.test.ts b/src/main/runtime/first-run-setup-window.test.ts
index e62dc335..024ff27e 100644
--- a/src/main/runtime/first-run-setup-window.test.ts
+++ b/src/main/runtime/first-run-setup-window.test.ts
@@ -271,7 +271,7 @@ test('parseFirstRunSetupSubmissionUrl parses supported custom actions', () => {
   assert.equal(parseFirstRunSetupSubmissionUrl('https://example.com'), null);
 });
 
-test('buildFirstRunSetupHtml renders command-line launcher section and actions', () => {
+test('buildFirstRunSetupHtml reports a broken included runtime in the optional launcher controls', () => {
   const html = buildFirstRunSetupHtml({
     configReady: true,
     dictionaryCount: 1,
@@ -294,9 +294,9 @@ test('buildFirstRunSetupHtml renders command-line launcher section and actions',
         status: 'failed',
         commandPath: null,
         version: null,
-        installMethod: 'official-script',
-        installCommand: ['bash', '-lc', 'curl -fsSL https://bun.com/install | bash'],
-        message: 'network failed',
+        installMethod: null,
+        installCommand: null,
+        message: 'Included Bun runtime is missing.',
       },
       launcher: {
         status: 'installed_bun_missing',
@@ -311,14 +311,11 @@ test('buildFirstRunSetupHtml renders command-line launcher section and actions',
   });
 
   assert.match(html, /Command line launcher/);
-  assert.match(html, /Optional\. Setup can finish without Bun or the launcher\./);
-  assert.match(html, /Bun runtime/);
+  assert.match(html, /Optional\. Install the launcher to use SubMiner from your terminal\./);
   assert.match(html, /Failed/);
-  assert.match(html, /bash -lc curl -fsSL https:\/\/bun\.com\/install \| bash/);
-  assert.match(html, /Install Bun/);
-  assert.match(html, /action=install-bun/);
   assert.match(html, /SubMiner launcher/);
-  assert.match(html, /Installed, Bun missing/);
+  assert.match(html, /Reinstall SubMiner to repair it/);
+  assert.match(html, /<button disabled[^>]+action=install-command-line-launcher/);
   assert.match(html, /\/home\/tester\/\.local\/bin\/subminer/);
   assert.match(html, /action=install-command-line-launcher/);
   assert.match(
@@ -360,7 +357,7 @@ test('buildFirstRunSetupHtml disables launcher install when no target is install
 
   assert.match(
     html,
-    /<button disabled onclick="window\.location\.href='subminer:\/\/first-run-setup\?action=install-command-line-launcher'">Install launcher<\/button>/,
+    /<button disabled onclick="window\.location\.href='subminer:\/\/first-run-setup\?action=install-command-line-launcher'">Install command-line launcher<\/button>/,
   );
 });
 
diff --git a/src/main/runtime/first-run-setup-window.ts b/src/main/runtime/first-run-setup-window.ts
index ff9df2e3..f0135e8a 100644
--- a/src/main/runtime/first-run-setup-window.ts
+++ b/src/main/runtime/first-run-setup-window.ts
@@ -1,9 +1,5 @@
 import { getFirstRunSetupCompletionMessage } from './first-run-setup-service';
-import type {
-  BunSnapshot,
-  CommandLineLauncherSnapshot,
-  LauncherSnapshot,
-} from './command-line-launcher';
+import type { CommandLineLauncherSnapshot, LauncherSnapshot } from './command-line-launcher';
 
 type FocusableWindowLike = {
   focus: () => void;
@@ -74,29 +70,12 @@ function renderStatusBadge(value: string, tone: 'ready' | 'warn' | 'muted' | 'da
   return `<span class="badge ${tone}">${escapeHtml(value)}</span>`;
 }
 
-function formatCommand(command: string[] | null): string {
-  return command?.join(' ') ?? 'No install command detected';
-}
-
-function getBunStatusLabel(status: BunSnapshot['status']): string {
-  switch (status) {
-    case 'ready':
-      return 'Ready';
-    case 'installing':
-      return 'Installing';
-    case 'failed':
-      return 'Failed';
-    case 'missing':
-      return 'Missing';
-  }
-}
-
 function getLauncherStatusLabel(status: LauncherSnapshot['status']): string {
   switch (status) {
     case 'ready':
       return 'Ready';
     case 'installed_bun_missing':
-      return 'Installed, Bun missing';
+      return 'Unavailable';
     case 'not_installed':
       return 'Not installed';
     case 'not_on_path':
@@ -110,13 +89,6 @@ function getLauncherStatusLabel(status: LauncherSnapshot['status']): string {
   }
 }
 
-function getToolTone(status: BunSnapshot['status']): 'ready' | 'warn' | 'muted' | 'danger' {
-  if (status === 'ready') return 'ready';
-  if (status === 'failed') return 'danger';
-  if (status === 'installing') return 'muted';
-  return 'warn';
-}
-
 function getLauncherTone(
   status: LauncherSnapshot['status'],
 ): 'ready' | 'warn' | 'muted' | 'danger' {
@@ -135,49 +107,26 @@ function renderCommandLineLauncherSection(
 
   const bun = commandLineLauncher.bun;
   const launcher = commandLineLauncher.launcher;
-  const bunMeta =
-    bun.status === 'ready'
-      ? [
-          bun.commandPath ? `Path: ${bun.commandPath}` : null,
-          bun.version ? `Version: ${bun.version}` : null,
-        ].filter(Boolean)
-      : [
-          bun.installMethod ? `Method: ${bun.installMethod}` : null,
-          `Command: ${formatCommand(bun.installCommand)}`,
-          bun.message,
-        ].filter(Boolean);
+  const runtimeUnavailable = bun.status !== 'ready';
+  const launcherStatus = runtimeUnavailable ? 'failed' : launcher.status;
+  const runtimeError = bun.installCommand
+    ? "The launcher runtime is unavailable. Install the project's Bun dependency, then refresh."
+    : 'The launcher runtime is unavailable. Reinstall SubMiner to repair it.';
   const launcherMeta = [
     launcher.commandPath ? `Command: ${launcher.commandPath}` : null,
     launcher.installPath ? `Install target: ${launcher.installPath}` : null,
     launcher.pathDir ? `PATH dir: ${launcher.pathDir}` : null,
     launcher.shadowedBy ? `Shadowed by: ${launcher.shadowedBy}` : null,
-    launcher.message,
-    bun.status !== 'ready' ? 'Warning: subminer will not run until Bun is available.' : null,
+    runtimeUnavailable ? runtimeError : launcher.message,
   ].filter(Boolean);
-  const bunInstallButton =
-    bun.status === 'missing' || bun.status === 'failed'
-      ? `<button onclick="window.location.href='subminer://first-run-setup?action=install-bun'">Install Bun</button>`
-      : '';
-  const launcherButtonDisabled = launcher.status === 'not_installable' ? 'disabled' : '';
+  const launcherButtonDisabled =
+    launcher.status === 'not_installable' || bun.status !== 'ready' ? 'disabled' : '';
 
   return `
     <section class="setup-section">
       <div class="section-head">
         <h2>Command line launcher</h2>
-        <div class="meta">Optional. Setup can finish without Bun or the launcher.</div>
-      </div>
-      <div class="card block">
-        <div class="card-head">
-          <div>
-            <strong>Bun runtime</strong>
-            ${bunMeta.map((line) => `<div class="meta">${escapeHtml(String(line))}</div>`).join('')}
-          </div>
-          ${renderStatusBadge(getBunStatusLabel(bun.status), getToolTone(bun.status))}
-        </div>
-        <div class="inline-actions">
-          ${bunInstallButton}
-          <button class="ghost" onclick="window.location.href='subminer://first-run-setup?action=refresh'">Refresh</button>
-        </div>
+        <div class="meta">Optional. Install the launcher to use SubMiner from your terminal.</div>
       </div>
       <div class="card block">
         <div class="card-head">
@@ -185,10 +134,10 @@ function renderCommandLineLauncherSection(
             <strong>SubMiner launcher</strong>
             ${launcherMeta.map((line) => `<div class="meta">${escapeHtml(String(line))}</div>`).join('')}
           </div>
-          ${renderStatusBadge(getLauncherStatusLabel(launcher.status), getLauncherTone(launcher.status))}
+          ${renderStatusBadge(getLauncherStatusLabel(launcherStatus), getLauncherTone(launcherStatus))}
         </div>
         <div class="inline-actions">
-          <button ${launcherButtonDisabled} onclick="window.location.href='subminer://first-run-setup?action=install-command-line-launcher'">Install launcher</button>
+          <button ${launcherButtonDisabled} onclick="window.location.href='subminer://first-run-setup?action=install-command-line-launcher'">Install command-line launcher</button>
           <button class="ghost" onclick="window.location.href='subminer://first-run-setup?action=refresh'">Refresh</button>
         </div>
       </div>
diff --git a/src/main/runtime/global-shortcuts-runtime-handlers.test.ts b/src/main/runtime/global-shortcuts-runtime-handlers.test.ts
index 76431508..174c6e7d 100644
--- a/src/main/runtime/global-shortcuts-runtime-handlers.test.ts
+++ b/src/main/runtime/global-shortcuts-runtime-handlers.test.ts
@@ -20,6 +20,8 @@ function createShortcuts(): ConfiguredShortcuts {
     openRuntimeOptions: null,
     openJimaku: null,
     openTsukihime: null,
+    openSubtitleSelection: null,
+    openSubtitleGeneration: null,
     openSessionHelp: null,
     openControllerSelect: null,
     openControllerDebug: null,
diff --git a/src/main/runtime/global-shortcuts.test.ts b/src/main/runtime/global-shortcuts.test.ts
index f144ef22..4e1cc12b 100644
--- a/src/main/runtime/global-shortcuts.test.ts
+++ b/src/main/runtime/global-shortcuts.test.ts
@@ -24,6 +24,8 @@ function createShortcuts(): ConfiguredShortcuts {
     openRuntimeOptions: null,
     openJimaku: null,
     openTsukihime: null,
+    openSubtitleSelection: null,
+    openSubtitleGeneration: null,
     openSessionHelp: null,
     openControllerSelect: null,
     openControllerDebug: null,
diff --git a/src/main/runtime/immersion-media.ts b/src/main/runtime/immersion-media.ts
index 35ddd276..744d12f1 100644
--- a/src/main/runtime/immersion-media.ts
+++ b/src/main/runtime/immersion-media.ts
@@ -1,3 +1,5 @@
+import { toMediaIdentityPath } from '../../shared/media-identity';
+
 type ResolvedConfigLike = {
   immersionTracking?: {
     dbPath?: string | null;
@@ -119,7 +121,7 @@ export function createImmersionMediaRuntime(deps: ImmersionMediaRuntimeDeps): {
         const mediaState = await getCurrentMpvMediaStateForTracker();
         if (mediaState.path) {
           deps.logInfo(
-            `Seeded immersion tracker media state at attempt ${attempt + 1}/${attempts}: ${mediaState.path}`,
+            `Seeded immersion tracker media state at attempt ${attempt + 1}/${attempts}: ${toMediaIdentityPath(mediaState.path)}`,
           );
           tracker.handleMediaChange(mediaState.path, mediaState.title);
           return;
diff --git a/src/main/runtime/internal-subtitle-extraction.test.ts b/src/main/runtime/internal-subtitle-extraction.test.ts
index 658d4ea8..1aee8b87 100644
--- a/src/main/runtime/internal-subtitle-extraction.test.ts
+++ b/src/main/runtime/internal-subtitle-extraction.test.ts
@@ -6,6 +6,7 @@ import process from 'node:process';
 import test from 'node:test';
 import {
   buildFfmpegSubtitleExtractionArgs,
+  createCachedInternalSubtitleTrackExtractor,
   extractInternalSubtitleTrackToTempFile,
   parseTrackId,
 } from './internal-subtitle-extraction';
@@ -22,6 +23,65 @@ test('parseTrackId rejects negative track ids', () => {
   assert.equal(parseTrackId(' -2 '), null);
 });
 
+test('cached internal subtitle extraction shares concurrent and repeated track requests', async () => {
+  let extractionCalls = 0;
+  let cleanupCalls = 0;
+  let resolveExtraction:
+    | ((result: { path: string; cleanup: () => Promise<void> }) => void)
+    | undefined;
+  const firstExtraction = new Promise<{ path: string; cleanup: () => Promise<void> }>((resolve) => {
+    resolveExtraction = resolve;
+  });
+  const extractor = createCachedInternalSubtitleTrackExtractor({
+    extract: async () => {
+      extractionCalls += 1;
+      if (extractionCalls === 1) {
+        return firstExtraction;
+      }
+      return {
+        path: `/tmp/subtitle-${extractionCalls}.ass`,
+        cleanup: async () => {
+          cleanupCalls += 1;
+        },
+      };
+    },
+  });
+  const request = () =>
+    extractor.extract('ffmpeg', '/Volumes/media/episode.mkv', {
+      'ff-index': 3,
+      codec: 'ass',
+    });
+
+  const concurrent = Array.from({ length: 6 }, request);
+  assert.equal(extractionCalls, 1);
+  if (!resolveExtraction) {
+    throw new Error('extraction did not start');
+  }
+  resolveExtraction({
+    path: '/tmp/subtitle-1.ass',
+    cleanup: async () => {
+      cleanupCalls += 1;
+    },
+  });
+
+  const results = await Promise.all(concurrent);
+  assert.deepEqual(
+    results.map((result) => result?.path),
+    Array.from({ length: 6 }, () => '/tmp/subtitle-1.ass'),
+  );
+  await Promise.all(results.map((result) => result?.cleanup()));
+  assert.equal(cleanupCalls, 0);
+
+  assert.equal((await request())?.path, '/tmp/subtitle-1.ass');
+  assert.equal(extractionCalls, 1);
+
+  extractor.clear();
+  await new Promise((resolve) => setImmediate(resolve));
+  assert.equal(cleanupCalls, 1);
+  assert.equal((await request())?.path, '/tmp/subtitle-2.ass');
+  assert.equal(extractionCalls, 2);
+});
+
 test('extractInternalSubtitleTrackToTempFile times out stalled ffmpeg process', async () => {
   const root = fs.mkdtempSync(path.join(os.tmpdir(), 'subminer-ffmpeg-timeout-'));
   const videoPath = path.join(root, 'video.mkv');
diff --git a/src/main/runtime/internal-subtitle-extraction.ts b/src/main/runtime/internal-subtitle-extraction.ts
index d303466d..d5beae55 100644
--- a/src/main/runtime/internal-subtitle-extraction.ts
+++ b/src/main/runtime/internal-subtitle-extraction.ts
@@ -35,7 +35,21 @@ export type MpvSubtitleTrackLike = {
   'external-filename'?: unknown;
 };
 
-const DEFAULT_EXTRACTION_TIMEOUT_MS = 30_000;
+export type ExtractedInternalSubtitleTrack = {
+  path: string;
+  cleanup: () => Promise<void>;
+};
+
+export type InternalSubtitleTrackExtractor = (
+  ffmpegPath: string,
+  videoPath: string,
+  track: MpvSubtitleTrackLike,
+) => Promise<ExtractedInternalSubtitleTrack | null>;
+
+// Subtitle packets are interleaved through the container, so extraction reads the
+// entire file. Network mounts move ~100 MB/s on gigabit, so large Bluray remuxes
+// need well over 30 seconds.
+const DEFAULT_EXTRACTION_TIMEOUT_MS = 120_000;
 
 export function parseTrackId(value: unknown): number | null {
   if (typeof value === 'number' && Number.isInteger(value) && value >= 0) {
@@ -80,7 +94,7 @@ export async function extractInternalSubtitleTrackToTempFile(
   videoPath: string,
   track: MpvSubtitleTrackLike,
   options: { extractionTimeoutMs?: number; spawnArgsOverride?: string[] } = {},
-): Promise<{ path: string; cleanup: () => Promise<void> } | null> {
+): Promise<ExtractedInternalSubtitleTrack | null> {
   const ffIndex = parseTrackId(track['ff-index']);
   const codec = typeof track.codec === 'string' ? track.codec : null;
   const extension = codecToExtension(codec ?? undefined);
@@ -145,3 +159,69 @@ export async function extractInternalSubtitleTrackToTempFile(
     },
   };
 }
+
+type CachedExtraction = {
+  promise: Promise<ExtractedInternalSubtitleTrack | null>;
+};
+
+function buildCachedExtractionKey(
+  ffmpegPath: string,
+  videoPath: string,
+  track: MpvSubtitleTrackLike,
+): string {
+  const codec = typeof track.codec === 'string' ? track.codec : null;
+  return JSON.stringify([ffmpegPath, videoPath, parseTrackId(track['ff-index']), codec]);
+}
+
+const releaseCachedExtraction = async (): Promise<void> => {};
+
+/**
+ * Owns extracted subtitle files for the active media and shares one extraction between callers.
+ * Caller cleanup releases only its view; clear removes the owned files on media changes or quit.
+ */
+export function createCachedInternalSubtitleTrackExtractor(
+  deps: { extract?: InternalSubtitleTrackExtractor } = {},
+): {
+  extract: InternalSubtitleTrackExtractor;
+  clear: () => void;
+} {
+  const extractTrack = deps.extract ?? extractInternalSubtitleTrackToTempFile;
+  const extractions = new Map<string, CachedExtraction>();
+
+  const extract: InternalSubtitleTrackExtractor = async (ffmpegPath, videoPath, track) => {
+    const key = buildCachedExtractionKey(ffmpegPath, videoPath, track);
+    let cached = extractions.get(key);
+    if (!cached) {
+      const next: CachedExtraction = {
+        promise: extractTrack(ffmpegPath, videoPath, track),
+      };
+      cached = next;
+      extractions.set(key, next);
+      void next.promise.catch(() => {
+        if (extractions.get(key) === next) {
+          extractions.delete(key);
+        }
+      });
+    }
+
+    const result = await cached.promise;
+    if (extractions.get(key) !== cached || !result) {
+      return null;
+    }
+
+    return {
+      path: result.path,
+      cleanup: releaseCachedExtraction,
+    };
+  };
+
+  const clear = (): void => {
+    const staleExtractions = [...extractions.values()];
+    extractions.clear();
+    for (const extraction of staleExtractions) {
+      void extraction.promise.then((result) => result?.cleanup()).catch(() => undefined);
+    }
+  };
+
+  return { extract, clear };
+}
diff --git a/src/main/runtime/jellyfin-playback-launch.test.ts b/src/main/runtime/jellyfin-playback-launch.test.ts
index f6d2916c..46d1e86b 100644
--- a/src/main/runtime/jellyfin-playback-launch.test.ts
+++ b/src/main/runtime/jellyfin-playback-launch.test.ts
@@ -103,6 +103,7 @@ test('playback handler drives mpv commands and playback state', async () => {
     ['set_property', 'sub-visibility', 'no'],
     ['set_property', 'secondary-sub-visibility', 'no'],
     ['script-message', 'subminer-managed-subtitles-loading'],
+    ['set_property', 'force-media-title', 'Episode 1'],
     [
       'loadfile',
       'https://stream.example/video.m3u8',
@@ -110,7 +111,6 @@ test('playback handler drives mpv commands and playback state', async () => {
       -1,
       'sid=no,secondary-sid=no,sub-auto=no,sub-visibility=no,secondary-sub-visibility=no,start=1.2',
     ],
-    ['set_property', 'force-media-title', 'Episode 1'],
   ]);
   assert.equal(scheduled.length, 0);
   assert.equal(
@@ -437,6 +437,8 @@ test('playback handler publishes Jellyfin title before loading tokenized stream
   assert.ok(titleIndex >= 0);
   assert.ok(loadIndex >= 0);
   assert.ok(titleIndex < loadIndex);
+  const mpvTitleIndex = timeline.indexOf('cmd:set_property:force-media-title');
+  assert.ok(mpvTitleIndex >= 0 && mpvTitleIndex < loadIndex);
   assert.equal(timeline[titleIndex]?.includes('api_key'), false);
 });
 
diff --git a/src/main/runtime/jellyfin-playback-launch.ts b/src/main/runtime/jellyfin-playback-launch.ts
index 9b1ad344..bf709dcf 100644
--- a/src/main/runtime/jellyfin-playback-launch.ts
+++ b/src/main/runtime/jellyfin-playback-launch.ts
@@ -165,7 +165,7 @@ export function createPlayJellyfinItemInMpvHandler(deps: {
     const mpvClient = deps.getMpvClient();
     if (!connected || !mpvClient) {
       throw new Error(
-        'MPV not connected and auto-launch failed. Ensure mpv is installed and available in PATH.',
+        'MPV not connected and auto-launch failed. Check mpv.executablePath or ensure mpv is available in PATH.',
       );
     }
 
@@ -221,11 +221,12 @@ export function createPlayJellyfinItemInMpvHandler(deps: {
     });
     deps.setLastProgressAtMs(0);
     deps.sendMpvCommand(['script-message', 'subminer-managed-subtitles-loading']);
+    // Set mpv's title before loadfile can emit a URL-derived media-title event.
+    deps.sendMpvCommand(['set_property', 'force-media-title', plan.title]);
     deps.sendMpvCommand(['loadfile', playbackUrl, 'replace', -1, loadfileOptions]);
     if (params.setQuitOnDisconnectArm !== false) {
       deps.armQuitOnDisconnect();
     }
-    deps.sendMpvCommand(['set_property', 'force-media-title', plan.title]);
 
     await awaitBestEffortPlaybackHook(() =>
       deps.preloadExternalSubtitles({
diff --git a/src/main/runtime/jellyfin-remote-connection-main-deps.test.ts b/src/main/runtime/jellyfin-remote-connection-main-deps.test.ts
index e7101b9e..924b1914 100644
--- a/src/main/runtime/jellyfin-remote-connection-main-deps.test.ts
+++ b/src/main/runtime/jellyfin-remote-connection-main-deps.test.ts
@@ -32,6 +32,7 @@ test('launch mpv for jellyfin main deps builder maps callbacks', () => {
     },
   };
   const deps = createBuildLaunchMpvIdleForJellyfinPlaybackMainDepsHandler({
+    getMpvExecutablePath: () => '/usr/local/bin/mpv',
     getSocketPath: () => '/tmp/mpv.sock',
     getLaunchMode: () => 'fullscreen',
     platform: 'darwin',
@@ -47,8 +48,8 @@ test('launch mpv for jellyfin main deps builder maps callbacks', () => {
     getDefaultMpvLogPath: () => '/tmp/mpv.log',
     defaultMpvArgs: ['--no-config'],
     removeSocketPath: (socketPath) => calls.push(`rm:${socketPath}`),
-    spawnMpv: (args) => {
-      calls.push(`spawn:${args.join(' ')}`);
+    spawnMpv: (executablePath, args) => {
+      calls.push(`spawn:${executablePath} ${args.join(' ')}`);
       return proc;
     },
     logWarn: (message) => calls.push(`warn:${message}`),
@@ -60,14 +61,20 @@ test('launch mpv for jellyfin main deps builder maps callbacks', () => {
   assert.equal(deps.platform, 'darwin');
   assert.equal(deps.execPath, '/tmp/subminer');
   assert.equal(deps.getRuntimePluginEntrypoint?.(), '/tmp/plugin/subminer/main.lua');
-  assert.equal(deps.getInstalledPluginDetection?.().installed, false);
+  assert.equal(deps.getMpvExecutablePath(), '/usr/local/bin/mpv');
+  assert.equal(deps.getInstalledPluginDetection?.('/usr/local/bin/mpv').installed, false);
   assert.equal(deps.getDefaultMpvLogPath(), '/tmp/mpv.log');
   assert.deepEqual(deps.defaultMpvArgs, ['--no-config']);
   deps.removeSocketPath('/tmp/mpv.sock');
-  deps.spawnMpv(['--idle=yes']);
+  deps.spawnMpv('/usr/local/bin/mpv', ['--idle=yes']);
   deps.logInfo('launched');
   deps.logWarn('bad', null);
-  assert.deepEqual(calls, ['rm:/tmp/mpv.sock', 'spawn:--idle=yes', 'info:launched', 'warn:bad']);
+  assert.deepEqual(calls, [
+    'rm:/tmp/mpv.sock',
+    'spawn:/usr/local/bin/mpv --idle=yes',
+    'info:launched',
+    'warn:bad',
+  ]);
 });
 
 test('ensure mpv connected for jellyfin main deps builder maps callbacks', async () => {
diff --git a/src/main/runtime/jellyfin-remote-connection-main-deps.ts b/src/main/runtime/jellyfin-remote-connection-main-deps.ts
index e5faa5cf..80fbd0c3 100644
--- a/src/main/runtime/jellyfin-remote-connection-main-deps.ts
+++ b/src/main/runtime/jellyfin-remote-connection-main-deps.ts
@@ -16,6 +16,7 @@ export function createBuildLaunchMpvIdleForJellyfinPlaybackMainDepsHandler(
   deps: LaunchMpvForJellyfinDeps,
 ) {
   return (): LaunchMpvForJellyfinDeps => ({
+    getMpvExecutablePath: () => deps.getMpvExecutablePath(),
     getSocketPath: () => deps.getSocketPath(),
     getLaunchMode: () => deps.getLaunchMode(),
     platform: deps.platform,
@@ -26,7 +27,7 @@ export function createBuildLaunchMpvIdleForJellyfinPlaybackMainDepsHandler(
     getDefaultMpvLogPath: () => deps.getDefaultMpvLogPath(),
     defaultMpvArgs: deps.defaultMpvArgs,
     removeSocketPath: (socketPath: string) => deps.removeSocketPath(socketPath),
-    spawnMpv: (args: string[]) => deps.spawnMpv(args),
+    spawnMpv: (executablePath, args) => deps.spawnMpv(executablePath, args),
     logWarn: (message: string, error: unknown) => deps.logWarn(message, error),
     logInfo: (message: string) => deps.logInfo(message),
   });
diff --git a/src/main/runtime/jellyfin-remote-connection.test.ts b/src/main/runtime/jellyfin-remote-connection.test.ts
index f17e6a8b..d9e0d0dc 100644
--- a/src/main/runtime/jellyfin-remote-connection.test.ts
+++ b/src/main/runtime/jellyfin-remote-connection.test.ts
@@ -1,5 +1,7 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
+import { detectInstalledMpvPlugin } from './first-run-setup-plugin';
+import { resolveWindowsMpvPath } from './mpv-process';
 import {
   createEnsureMpvConnectedForJellyfinPlaybackHandler,
   createLaunchMpvIdleForJellyfinPlaybackHandler,
@@ -30,6 +32,7 @@ test('createLaunchMpvIdleForJellyfinPlaybackHandler builds expected mpv args', (
   const spawnedArgs: string[][] = [];
   const logs: string[] = [];
   const launch = createLaunchMpvIdleForJellyfinPlaybackHandler({
+    getMpvExecutablePath: () => 'mpv',
     getSocketPath: () => '/tmp/subminer.sock',
     getLaunchMode: () => 'maximized',
     platform: 'darwin',
@@ -39,7 +42,7 @@ test('createLaunchMpvIdleForJellyfinPlaybackHandler builds expected mpv args', (
     getDefaultMpvLogPath: () => ' /tmp/mp.log ',
     defaultMpvArgs: ['--sid=auto'],
     removeSocketPath: () => {},
-    spawnMpv: (args) => {
+    spawnMpv: (_executable, args) => {
       spawnedArgs.push(args);
       return {
         on: () => {},
@@ -67,6 +70,7 @@ test('createLaunchMpvIdleForJellyfinPlaybackHandler builds expected mpv args', (
 test('createLaunchMpvIdleForJellyfinPlaybackHandler forwards runtime plugin config', () => {
   const spawnedArgs: string[][] = [];
   const launch = createLaunchMpvIdleForJellyfinPlaybackHandler({
+    getMpvExecutablePath: () => 'mpv',
     getSocketPath: () => '/tmp/subminer.sock',
     getLaunchMode: () => 'normal',
     platform: 'linux',
@@ -84,7 +88,7 @@ test('createLaunchMpvIdleForJellyfinPlaybackHandler forwards runtime plugin conf
     getDefaultMpvLogPath: () => '/tmp/mp.log',
     defaultMpvArgs: ['--sid=auto'],
     removeSocketPath: () => {},
-    spawnMpv: (args) => {
+    spawnMpv: (_executable, args) => {
       spawnedArgs.push(args);
       return {
         on: () => {},
@@ -108,41 +112,53 @@ test('createLaunchMpvIdleForJellyfinPlaybackHandler forwards runtime plugin conf
   assert.doesNotMatch(scriptOpts ?? '', /subminer-aniskip_button_key=/);
 });
 
-test('createLaunchMpvIdleForJellyfinPlaybackHandler skips bundled script when installed plugin exists', () => {
-  const spawnedArgs: string[][] = [];
-  const launch = createLaunchMpvIdleForJellyfinPlaybackHandler({
-    getSocketPath: () => '/tmp/subminer.sock',
-    getLaunchMode: () => 'normal',
-    platform: 'linux',
-    execPath: '/opt/SubMiner/SubMiner.AppImage',
-    getRuntimePluginEntrypoint: () => '/opt/SubMiner/plugin/subminer/main.lua',
-    getInstalledPluginDetection: () => ({
-      installed: true,
-      path: '/home/tester/.config/mpv/scripts/subminer/main.lua',
-      version: '0.1.0',
-      source: 'default-config',
-      message: null,
-    }),
-    getDefaultMpvLogPath: () => '/tmp/mp.log',
-    defaultMpvArgs: ['--sid=auto'],
-    removeSocketPath: () => {},
-    spawnMpv: (args) => {
-      spawnedArgs.push(args);
-      return {
-        on: () => {},
-        unref: () => {},
-      };
-    },
-    logWarn: () => {},
-    logInfo: () => {},
-  });
+test('Jellyfin detects portable plugins beside the executable selected for launch', () => {
+  const mpvPath = 'C:\\portable player\\mpv.exe';
+  const pluginPath = 'C:\\portable player\\portable_config\\scripts\\subminer\\main.lua';
+  for (const source of ['environment', 'PATH']) {
+    let resolutions = 0;
+    const spawned: Array<{ executable: string; args: string[] }> = [];
+    const launch = createLaunchMpvIdleForJellyfinPlaybackHandler({
+      getMpvExecutablePath: () => {
+        resolutions += 1;
+        return resolveWindowsMpvPath({
+          getEnv: () => (source === 'environment' ? mpvPath : undefined),
+          runWhere: () => ({ status: 0, stdout: mpvPath }),
+          fileExists: (candidate) => candidate === mpvPath,
+        });
+      },
+      getSocketPath: () => '\\\\.\\pipe\\subminer-test',
+      getLaunchMode: () => 'normal',
+      platform: 'win32',
+      execPath: 'C:\\SubMiner\\SubMiner.exe',
+      getRuntimePluginEntrypoint: () => 'C:\\SubMiner\\plugin\\subminer\\main.lua',
+      getInstalledPluginDetection: (mpvExecutablePath) =>
+        detectInstalledMpvPlugin({
+          platform: 'win32',
+          homeDir: 'C:\\Users\\test',
+          mpvExecutablePath,
+          existsSync: (candidate) => candidate === pluginPath,
+        }),
+      getDefaultMpvLogPath: () => '',
+      defaultMpvArgs: [],
+      removeSocketPath: () => {},
+      spawnMpv: (executable, args) => {
+        spawned.push({ executable, args });
+        return { on: () => {}, unref: () => {} };
+      },
+      logWarn: () => {},
+      logInfo: () => {},
+    });
 
-  launch();
-  assert.equal(
-    spawnedArgs[0]?.some((arg) => arg.startsWith('--script=/opt/SubMiner/plugin/subminer')),
-    false,
-  );
-  assert.ok(spawnedArgs[0]?.some((arg) => arg.startsWith('--script-opts=')));
+    launch();
+    assert.equal(resolutions, 1, source);
+    assert.equal(spawned.length, 1);
+    assert.equal(spawned[0]!.executable, mpvPath);
+    assert.equal(
+      spawned[0]!.args.some((arg) => arg.startsWith('--script=')),
+      false,
+    );
+  }
 });
 
 test('createEnsureMpvConnectedForJellyfinPlaybackHandler auto-launches once', async () => {
diff --git a/src/main/runtime/jellyfin-remote-connection.ts b/src/main/runtime/jellyfin-remote-connection.ts
index 67162aa0..3731beee 100644
--- a/src/main/runtime/jellyfin-remote-connection.ts
+++ b/src/main/runtime/jellyfin-remote-connection.ts
@@ -41,23 +41,25 @@ export function createWaitForMpvConnectedHandler(deps: WaitForMpvConnectedDeps)
 }
 
 export type LaunchMpvForJellyfinDeps = {
+  getMpvExecutablePath: () => string;
   getSocketPath: () => string;
   getLaunchMode: () => MpvLaunchMode;
   platform: NodeJS.Platform;
   execPath: string;
   getRuntimePluginEntrypoint?: () => string | null | undefined;
-  getInstalledPluginDetection?: () => InstalledMpvPluginDetection;
+  getInstalledPluginDetection?: (mpvExecutablePath: string) => InstalledMpvPluginDetection;
   getPluginRuntimeConfig?: () => SubminerPluginRuntimeScriptOptConfig;
   getDefaultMpvLogPath: () => string;
   defaultMpvArgs: readonly string[];
   removeSocketPath: (socketPath: string) => void;
-  spawnMpv: (args: string[]) => SpawnedProcessLike;
+  spawnMpv: (executablePath: string, args: string[]) => SpawnedProcessLike;
   logWarn: (message: string, error: unknown) => void;
   logInfo: (message: string) => void;
 };
 
 export function createLaunchMpvIdleForJellyfinPlaybackHandler(deps: LaunchMpvForJellyfinDeps) {
   return (): void => {
+    const executablePath = deps.getMpvExecutablePath();
     const socketPath = deps.getSocketPath();
     if (deps.platform !== 'win32') {
       try {
@@ -78,7 +80,7 @@ export function createLaunchMpvIdleForJellyfinPlaybackHandler(deps: LaunchMpvFor
         )
       : [`subminer-binary_path=${deps.execPath}`, `subminer-socket_path=${socketPath}`];
     const scriptOpts = `--script-opts=${scriptOptParts.join(',')}`;
-    const installedPlugin = deps.getInstalledPluginDetection?.();
+    const installedPlugin = deps.getInstalledPluginDetection?.(executablePath);
     const runtimePluginEntrypoint = installedPlugin?.installed
       ? ''
       : (deps.getRuntimePluginEntrypoint?.()?.trim() ?? '');
@@ -95,7 +97,7 @@ export function createLaunchMpvIdleForJellyfinPlaybackHandler(deps: LaunchMpvFor
       ...(defaultMpvLogPath ? [`--log-file=${defaultMpvLogPath}`] : []),
       `--input-ipc-server=${socketPath}`,
     ];
-    const proc = deps.spawnMpv(mpvArgs);
+    const proc = deps.spawnMpv(executablePath, mpvArgs);
     proc.on('error', (error) => {
       deps.logWarn('Failed to launch mpv for Jellyfin remote playback', error);
     });
diff --git a/src/main/runtime/jellyfin-remote-main-deps.ts b/src/main/runtime/jellyfin-remote-main-deps.ts
index d5b4dd20..ed3ca45d 100644
--- a/src/main/runtime/jellyfin-remote-main-deps.ts
+++ b/src/main/runtime/jellyfin-remote-main-deps.ts
@@ -75,5 +75,6 @@ export function createBuildReportJellyfinRemoteStoppedMainDepsHandler(
     getNow: deps.getNow ? () => deps.getNow?.() ?? Date.now() : undefined,
     ticksPerSecond: deps.ticksPerSecond,
     logDebug: (message: string, error: unknown) => deps.logDebug(message, error),
+    ...(deps.logWarn ? { logWarn: (message: string) => deps.logWarn?.(message) } : {}),
   });
 }
diff --git a/src/main/runtime/jellyfin-remote-playback.test.ts b/src/main/runtime/jellyfin-remote-playback.test.ts
index b227f5aa..919250e5 100644
--- a/src/main/runtime/jellyfin-remote-playback.test.ts
+++ b/src/main/runtime/jellyfin-remote-playback.test.ts
@@ -2,6 +2,7 @@ import test from 'node:test';
 import assert from 'node:assert/strict';
 import {
   markJellyfinRemotePlaybackLoaded,
+  createJellyfinRemoteReportTracker,
   createReportJellyfinRemoteProgressHandler,
   createReportJellyfinRemoteStoppedHandler,
   secondsToJellyfinTicks,
@@ -528,3 +529,70 @@ test('createReportJellyfinRemoteStoppedHandler ignores startup stop churn before
   assert.equal(stopped, false);
   assert.equal(cleared, false);
 });
+
+test('createReportJellyfinRemoteStoppedHandler clears playback before reporting and waits for in-flight progress', async () => {
+  const tracker = createJellyfinRemoteReportTracker();
+  let playback: { itemId: string; playMethod: 'DirectPlay'; loadedMediaPath: string } | null = {
+    itemId: 'item-1',
+    playMethod: 'DirectPlay',
+    loadedMediaPath: 'http://pve-main:8096/Videos/item-1/stream',
+  };
+  const calls: string[] = [];
+  let releaseProgress: () => void = () => undefined;
+  const progressGate = new Promise<void>((resolve) => {
+    releaseProgress = resolve;
+  });
+  const session = {
+    isConnected: () => true,
+    reportProgress: async ({ eventName }: { eventName: string }) => {
+      calls.push(`progress:${eventName}:${playback ? 'active' : 'cleared'}`);
+      if (calls.length === 1) await progressGate;
+      return true;
+    },
+    reportStopped: async () => {
+      calls.push(`stopped:${playback ? 'active' : 'cleared'}`);
+      return true;
+    },
+  };
+  const shared = {
+    getActivePlayback: () => playback,
+    clearActivePlayback: () => {
+      playback = null;
+    },
+    getSession: () => session,
+    getMpvClient: () => ({ currentTimePos: 42 }),
+    ticksPerSecond: 10_000_000,
+    logDebug: () => undefined,
+    reportTracker: tracker,
+  };
+  const reportProgress = createReportJellyfinRemoteProgressHandler({
+    ...shared,
+    getNow: () => 10_000,
+    getLastProgressAtMs: () => 0,
+    setLastProgressAtMs: () => undefined,
+    progressIntervalMs: 3000,
+  });
+  const reportStopped = createReportJellyfinRemoteStoppedHandler(shared);
+
+  // A periodic tick is mid-request when the stop starts.
+  const tick = reportProgress(true);
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  assert.deepEqual(calls, ['progress:TimeUpdate:active']);
+  const stop = reportStopped();
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  assert.equal(playback, null);
+  assert.deepEqual(calls, ['progress:TimeUpdate:active']);
+
+  // A tick fired after the stop began must not report anything.
+  await reportProgress(true);
+  assert.deepEqual(calls, ['progress:TimeUpdate:active']);
+
+  releaseProgress();
+  await tick;
+  await stop;
+  assert.deepEqual(calls, [
+    'progress:TimeUpdate:active',
+    'progress:TimeUpdate:cleared',
+    'stopped:cleared',
+  ]);
+});
diff --git a/src/main/runtime/jellyfin-remote-playback.ts b/src/main/runtime/jellyfin-remote-playback.ts
index 8ea0c6c9..3e49e452 100644
--- a/src/main/runtime/jellyfin-remote-playback.ts
+++ b/src/main/runtime/jellyfin-remote-playback.ts
@@ -134,6 +134,29 @@ function isSeekLikePositionJump(
   return Math.abs(nextPositionSeconds - previousPositionSeconds) >= thresholdSeconds;
 }
 
+// Jellyfin re-creates a session's NowPlayingItem from any progress report, so a progress
+// tick that lands after the stop report leaves the server showing playback forever. The
+// tracker lets the stop handler wait for reports that are already in flight.
+export type JellyfinRemoteReportTracker = {
+  track: (report: Promise<void>) => void;
+  settled: () => Promise<void>;
+};
+
+export function createJellyfinRemoteReportTracker(): JellyfinRemoteReportTracker {
+  const active = new Set<Promise<void>>();
+  return {
+    track: (report) => {
+      active.add(report);
+      void report.finally(() => active.delete(report));
+    },
+    settled: async () => {
+      while (active.size > 0) {
+        await Promise.allSettled([...active]);
+      }
+    },
+  };
+}
+
 export type JellyfinRemoteProgressReporterDeps = {
   getActivePlayback: () => ActiveJellyfinRemotePlaybackState | null;
   clearActivePlayback: () => void;
@@ -145,6 +168,7 @@ export type JellyfinRemoteProgressReporterDeps = {
   progressIntervalMs: number;
   ticksPerSecond: number;
   logDebug: (message: string, error: unknown) => void;
+  reportTracker?: JellyfinRemoteReportTracker;
 };
 
 export function createReportJellyfinRemoteProgressHandler(
@@ -152,7 +176,7 @@ export function createReportJellyfinRemoteProgressHandler(
 ) {
   let lastReportedPositionSeconds: number | null = null;
 
-  return async (force = false): Promise<void> => {
+  const report = async (force: boolean): Promise<void> => {
     const playback = deps.getActivePlayback();
     if (!playback) return;
     const session = deps.getSession();
@@ -193,6 +217,12 @@ export function createReportJellyfinRemoteProgressHandler(
       deps.logDebug('Failed to report Jellyfin remote progress', error);
     }
   };
+
+  return async (force = false): Promise<void> => {
+    const pending = report(force);
+    deps.reportTracker?.track(pending);
+    await pending;
+  };
 }
 
 export type JellyfinRemoteStoppedReporterDeps = {
@@ -203,6 +233,8 @@ export type JellyfinRemoteStoppedReporterDeps = {
   getNow?: () => number;
   ticksPerSecond: number;
   logDebug: (message: string, error: unknown) => void;
+  logWarn?: (message: string) => void;
+  reportTracker?: JellyfinRemoteReportTracker;
 };
 
 export function createReportJellyfinRemoteStoppedHandler(deps: JellyfinRemoteStoppedReporterDeps) {
@@ -226,6 +258,10 @@ export function createReportJellyfinRemoteStoppedHandler(deps: JellyfinRemoteSto
       deps.clearActivePlayback();
       return;
     }
+    // Clear before any network call so progress ticks fired during the stop find nothing to
+    // report, then let reports already in flight finish so none can arrive after the stop.
+    deps.clearActivePlayback();
+    await deps.reportTracker?.settled();
     try {
       const observedPositionSeconds = await readMpvPositionSecondsOrFallback(deps.getMpvClient());
       const positionSeconds = resolveReportablePositionSeconds(playback, observedPositionSeconds);
@@ -244,7 +280,7 @@ export function createReportJellyfinRemoteStoppedHandler(deps: JellyfinRemoteSto
       } catch (error) {
         deps.logDebug('Failed to report Jellyfin remote final progress', error);
       }
-      await session.reportStopped({
+      const reported = await session.reportStopped({
         itemId: playback.itemId,
         mediaSourceId: playback.mediaSourceId,
         positionTicks,
@@ -254,10 +290,13 @@ export function createReportJellyfinRemoteStoppedHandler(deps: JellyfinRemoteSto
         subtitleStreamIndex: playback.subtitleStreamIndex,
         eventName: 'stop',
       });
+      if (reported === false) {
+        deps.logWarn?.(
+          `Jellyfin did not accept the playback stop report for item ${playback.itemId}; the server may keep showing it as playing.`,
+        );
+      }
     } catch (error) {
       deps.logDebug('Failed to report Jellyfin remote stop', error);
-    } finally {
-      deps.clearActivePlayback();
     }
   };
 }
diff --git a/src/main/runtime/jellyfin-remote-session-lifecycle.ts b/src/main/runtime/jellyfin-remote-session-lifecycle.ts
index 233f94af..a7b5759c 100644
--- a/src/main/runtime/jellyfin-remote-session-lifecycle.ts
+++ b/src/main/runtime/jellyfin-remote-session-lifecycle.ts
@@ -38,6 +38,7 @@ type JellyfinRemoteServiceOptions = {
   };
   onConnected: () => void;
   onDisconnected: () => void;
+  logWarn?: (message: string, details?: unknown) => void;
   onPlay: (payload: JellyfinRemoteEventPayload) => void;
   onPlaystate: (payload: JellyfinRemoteEventPayload) => void;
   onGeneralCommand: (payload: JellyfinRemoteEventPayload) => void;
@@ -110,6 +111,7 @@ export function createStartJellyfinRemoteSessionHandler(deps: {
       onDisconnected: () => {
         deps.logWarn('Jellyfin remote websocket disconnected; retrying.');
       },
+      logWarn: (message, details) => deps.logWarn(message, details),
       onPlay: (payload) => {
         void deps.handlePlay(payload).catch((error) => {
           deps.logWarn('Failed handling Jellyfin remote Play event', error);
diff --git a/src/main/runtime/jellyfin-subtitle-preload-main-deps.test.ts b/src/main/runtime/jellyfin-subtitle-preload-main-deps.test.ts
index bb79a4de..f6f4d1b5 100644
--- a/src/main/runtime/jellyfin-subtitle-preload-main-deps.test.ts
+++ b/src/main/runtime/jellyfin-subtitle-preload-main-deps.test.ts
@@ -19,19 +19,6 @@ test('preload jellyfin external subtitles main deps builder maps callbacks', asy
       return { path: '/tmp/sub.srt', cleanupDir: '/tmp/subs' };
     },
     cleanupCachedSubtitles: () => calls.push('cleanup'),
-    getSavedSubtitleDelay: (_itemId, streamIndex) => {
-      calls.push(`load-delay:${streamIndex}`);
-      return 1.25;
-    },
-    setActiveSubtitleDelayKey: (key) => calls.push(`active-delay:${key?.streamIndex ?? 'none'}`),
-    loadSubtitleSourceText: async (source) => {
-      calls.push(`load-source:${source}`);
-      return 'subtitle';
-    },
-    saveSubtitleDelay: (_itemId, streamIndex, delaySeconds) => {
-      calls.push(`save-delay:${streamIndex}:${delaySeconds}`);
-      return true;
-    },
     logDebug: (message) => calls.push(`debug:${message}`),
   })();
 
@@ -41,21 +28,6 @@ test('preload jellyfin external subtitles main deps builder maps callbacks', asy
   await deps.wait(1);
   await deps.cacheSubtitleTrack({ index: 1, deliveryUrl: 'https://example.test/sub.srt' });
   deps.cleanupCachedSubtitles(['/tmp/subs']);
-  assert.equal(deps.getSavedSubtitleDelay?.('item', 3), 1.25);
-  deps.setActiveSubtitleDelayKey?.({ itemId: 'item', streamIndex: 3 });
-  assert.equal(await deps.loadSubtitleSourceText?.('/tmp/sub.srt'), 'subtitle');
-  assert.equal(deps.saveSubtitleDelay?.('item', 3, -31.5), true);
   deps.logDebug('oops', null);
-  assert.deepEqual(calls, [
-    'list',
-    'send',
-    'wait',
-    'cache',
-    'cleanup',
-    'load-delay:3',
-    'active-delay:3',
-    'load-source:/tmp/sub.srt',
-    'save-delay:3:-31.5',
-    'debug:oops',
-  ]);
+  assert.deepEqual(calls, ['list', 'send', 'wait', 'cache', 'cleanup', 'debug:oops']);
 });
diff --git a/src/main/runtime/jellyfin-subtitle-preload-main-deps.ts b/src/main/runtime/jellyfin-subtitle-preload-main-deps.ts
index f5ca73a7..b00f08ff 100644
--- a/src/main/runtime/jellyfin-subtitle-preload-main-deps.ts
+++ b/src/main/runtime/jellyfin-subtitle-preload-main-deps.ts
@@ -15,19 +15,6 @@ export function createBuildPreloadJellyfinExternalSubtitlesMainDepsHandler(
     wait: (ms: number) => deps.wait(ms),
     cacheSubtitleTrack: (track) => deps.cacheSubtitleTrack(track),
     cleanupCachedSubtitles: (dirs) => deps.cleanupCachedSubtitles(dirs),
-    getSavedSubtitleDelay: deps.getSavedSubtitleDelay
-      ? (itemId, streamIndex) => deps.getSavedSubtitleDelay!(itemId, streamIndex)
-      : undefined,
-    setActiveSubtitleDelayKey: deps.setActiveSubtitleDelayKey
-      ? (key) => deps.setActiveSubtitleDelayKey!(key)
-      : undefined,
-    loadSubtitleSourceText: deps.loadSubtitleSourceText
-      ? (source) => deps.loadSubtitleSourceText!(source)
-      : undefined,
-    saveSubtitleDelay: deps.saveSubtitleDelay
-      ? (itemId, streamIndex, delaySeconds) =>
-          deps.saveSubtitleDelay!(itemId, streamIndex, delaySeconds)
-      : undefined,
     initSubtitlePrefetch: deps.initSubtitlePrefetch
       ? (sourcePath) => deps.initSubtitlePrefetch!(sourcePath)
       : undefined,
diff --git a/src/main/runtime/jellyfin-subtitle-preload.test.ts b/src/main/runtime/jellyfin-subtitle-preload.test.ts
index 8477f174..4c78169d 100644
--- a/src/main/runtime/jellyfin-subtitle-preload.test.ts
+++ b/src/main/runtime/jellyfin-subtitle-preload.test.ts
@@ -32,14 +32,6 @@ function makeDeps(overrides: {
   cleanupCachedSubtitles?: Parameters<
     typeof createPreloadJellyfinExternalSubtitlesHandler
   >[0]['cleanupCachedSubtitles'];
-  getSavedSubtitleDelay?: Parameters<
-    typeof createPreloadJellyfinExternalSubtitlesHandler
-  >[0]['getSavedSubtitleDelay'];
-  setActiveSubtitleDelayKey?: Parameters<
-    typeof createPreloadJellyfinExternalSubtitlesHandler
-  >[0]['setActiveSubtitleDelayKey'];
-  loadSubtitleSourceText?: (source: string) => Promise<string>;
-  saveSubtitleDelay?: (itemId: string, streamIndex: number, delaySeconds: number) => void;
   initSubtitlePrefetch?: Parameters<
     typeof createPreloadJellyfinExternalSubtitlesHandler
   >[0]['initSubtitlePrefetch'];
@@ -57,10 +49,6 @@ function makeDeps(overrides: {
         cleanupDir: '/tmp/subminer-jellyfin-subtitles',
       })),
     cleanupCachedSubtitles: overrides.cleanupCachedSubtitles ?? (() => {}),
-    getSavedSubtitleDelay: overrides.getSavedSubtitleDelay,
-    setActiveSubtitleDelayKey: overrides.setActiveSubtitleDelayKey,
-    loadSubtitleSourceText: overrides.loadSubtitleSourceText,
-    saveSubtitleDelay: overrides.saveSubtitleDelay,
     initSubtitlePrefetch: overrides.initSubtitlePrefetch,
     logDebug: overrides.logDebug ?? (() => {}),
   };
@@ -375,22 +363,177 @@ test('preload jellyfin subtitles waits for delayed external japanese track inste
   ]);
 });
 
+test('preload jellyfin subtitles selects japanese before slower tracks finish downloading', async () => {
+  const commands: Array<Array<string | number>> = [];
+  let releaseSlowTrack!: () => void;
+  const slowTrackBlocked = new Promise<void>((resolve) => {
+    releaseSlowTrack = resolve;
+  });
+  const mpvTracks: Array<Record<string, unknown>> = [];
+  const preload = createPreloadJellyfinExternalSubtitlesHandler(
+    makeDeps({
+      listJellyfinSubtitleTracks: async () => [
+        { index: 0, language: 'eng', title: 'English', deliveryUrl: 'https://sub/eng.ass' },
+        { index: 1, language: 'jpn', title: 'Japanese', deliveryUrl: 'https://sub/jpn.srt' },
+      ],
+      getMpvClient: () => ({ requestProperty: async () => mpvTracks }),
+      cacheSubtitleTrack: async (track) => {
+        if (track.index === 0) {
+          await slowTrackBlocked;
+        }
+        return {
+          path: `/tmp/subminer-jellyfin-subtitles/${track.index}.srt`,
+          cleanupDir: '/tmp/subminer-jellyfin-subtitles',
+        };
+      },
+      sendMpvCommand: (command) => {
+        commands.push(command);
+        if (command[0] === 'sub-add') {
+          mpvTracks.push({
+            type: 'sub',
+            id: mpvTracks.length + 1,
+            lang: command[4],
+            title: command[3],
+            external: true,
+            'external-filename': command[1],
+          });
+        }
+      },
+    }),
+  );
+
+  const done = preload({ session, clientInfo, itemId: 'item-1' });
+  const hasJapanesePrimary = () =>
+    commands.some(
+      (command) => command[0] === 'set_property' && command[1] === 'sid' && command[2] === 1,
+    );
+  for (let tick = 0; tick < 1000 && !hasJapanesePrimary(); tick += 1) {
+    await new Promise((resolve) => setImmediate(resolve));
+  }
+  const selectedBeforeSlowTrack = setPropertyCommandsExceptTrackAutoSelection(commands);
+  // Release before asserting so a regression fails here instead of leaving the preload hanging.
+  releaseSlowTrack();
+  await done;
+
+  assert.deepEqual(selectedBeforeSlowTrack, [['set_property', 'sid', 1]]);
+  assert.deepEqual(setPropertyCommandsExceptTrackAutoSelection(commands), [
+    ['set_property', 'sid', 1],
+    ['set_property', 'secondary-sid', 2],
+  ]);
+});
+
+test('preload jellyfin subtitles does not lock in a fallback japanese track during early selection', async () => {
+  const commands: Array<Array<string | number>> = [];
+  let requestCount = 0;
+  const fallbackJapanese = {
+    type: 'sub',
+    id: 5,
+    lang: 'jpn',
+    title: 'Japanese SDH',
+    external: true,
+    'external-filename': '/tmp/subminer-jellyfin-subtitles/0.srt',
+  };
+  const preferredJapanese = {
+    type: 'sub',
+    id: 6,
+    lang: 'jpn',
+    title: 'Japanese',
+    external: true,
+    'external-filename': '/tmp/subminer-jellyfin-subtitles/1.srt',
+  };
+  const preload = createPreloadJellyfinExternalSubtitlesHandler(
+    makeDeps({
+      listJellyfinSubtitleTracks: async () => [
+        { index: 0, language: 'jpn', title: 'Japanese SDH', deliveryUrl: 'https://sub/sdh.srt' },
+        {
+          index: 1,
+          language: 'jpn',
+          title: 'Japanese',
+          isDefault: true,
+          deliveryUrl: 'https://sub/jpn.srt',
+        },
+      ],
+      getMpvClient: () => ({
+        requestProperty: async () => {
+          requestCount += 1;
+          // mpv lists the preferred track only after the early selection poll gives up.
+          return requestCount <= 10 ? [fallbackJapanese] : [fallbackJapanese, preferredJapanese];
+        },
+      }),
+      sendMpvCommand: (command) => commands.push(command),
+    }),
+  );
+
+  await preload({ session, clientInfo, itemId: 'item-1' });
+
+  assert.deepEqual(setPropertyCommandsExceptTrackAutoSelection(commands), [
+    ['set_property', 'sid', 6],
+  ]);
+});
+
+test('preload jellyfin subtitles still selects remaining tracks when one download fails', async () => {
+  const commands: Array<Array<string | number>> = [];
+  const preload = createPreloadJellyfinExternalSubtitlesHandler(
+    makeDeps({
+      listJellyfinSubtitleTracks: async () => [
+        { index: 0, language: 'eng', title: 'English', deliveryUrl: 'https://sub/eng.srt' },
+        { index: 1, language: 'jpn', title: 'Japanese', deliveryUrl: 'https://sub/jpn.srt' },
+        { index: 5, language: 'eng', title: 'English PGS', deliveryUrl: 'https://sub/pgs.srt' },
+      ],
+      getMpvClient: () => ({
+        requestProperty: async () => [
+          {
+            type: 'sub',
+            id: 1,
+            lang: 'eng',
+            title: 'English',
+            external: true,
+            'external-filename': '/tmp/subminer-jellyfin-subtitles/0.srt',
+          },
+          {
+            type: 'sub',
+            id: 2,
+            lang: 'jpn',
+            title: 'Japanese',
+            external: true,
+            'external-filename': '/tmp/subminer-jellyfin-subtitles/1.srt',
+          },
+        ],
+      }),
+      cacheSubtitleTrack: async (track) => {
+        if (track.index === 5) {
+          throw new Error('Failed to download Jellyfin subtitle (HTTP 400)');
+        }
+        return {
+          path: `/tmp/subminer-jellyfin-subtitles/${track.index}.srt`,
+          cleanupDir: '/tmp/subminer-jellyfin-subtitles',
+        };
+      },
+      sendMpvCommand: (command) => commands.push(command),
+    }),
+  );
+
+  await preload({ session, clientInfo, itemId: 'item-1' });
+
+  assert.deepEqual(setPropertyCommandsExceptTrackAutoSelection(commands), [
+    ['set_property', 'sid', 2],
+    ['set_property', 'secondary-sid', 1],
+  ]);
+});
+
 test('preload jellyfin subtitles clears managed delay when no external tracks are available', async () => {
   const commands: Array<Array<string | number>> = [];
-  const activeDelayKeys: Array<unknown> = [];
   const preload = createPreloadJellyfinExternalSubtitlesHandler(
     makeDeps({
       listJellyfinSubtitleTracks: async () => [
         { index: 0, language: 'jpn', title: 'Embedded Japanese' },
       ],
       sendMpvCommand: (command) => commands.push(command),
-      setActiveSubtitleDelayKey: (key) => activeDelayKeys.push(key),
     }),
   );
 
   await preload({ session, clientInfo, itemId: 'item-1' });
 
-  assert.deepEqual(activeDelayKeys, [null]);
   assert.deepEqual(commands, [['set_property', 'sub-delay', 0]]);
 });
 
@@ -461,42 +604,7 @@ test('preload jellyfin subtitles prefers Jellyfin default and embedded japanese
   ]);
 });
 
-test('preload jellyfin subtitles applies saved delay for selected japanese stream', async () => {
-  const commands: Array<Array<string | number>> = [];
-  const activeKeys: Array<{ itemId: string; streamIndex: number } | null> = [];
-  const preload = createPreloadJellyfinExternalSubtitlesHandler(
-    makeDeps({
-      listJellyfinSubtitleTracks: async () => [
-        { index: 3, language: 'jpn', title: 'Japanese', deliveryUrl: 'https://sub/jpn.srt' },
-      ],
-      getMpvClient: () => ({
-        requestProperty: async () => [
-          {
-            type: 'sub',
-            id: 11,
-            lang: 'jpn',
-            title: 'Japanese',
-            external: true,
-            'external-filename': '/tmp/subminer-jellyfin-subtitles/3.srt',
-          },
-        ],
-      }),
-      sendMpvCommand: (command) => commands.push(command),
-      getSavedSubtitleDelay: (_itemId, streamIndex) => (streamIndex === 3 ? 1.25 : null),
-      setActiveSubtitleDelayKey: (key) => activeKeys.push(key),
-    }),
-  );
-
-  await preload({ session, clientInfo, itemId: 'item-9' });
-
-  assert.deepEqual(setPropertyCommandsExceptTrackAutoSelection(commands), [
-    ['set_property', 'sub-delay', 1.25],
-    ['set_property', 'sid', 11],
-  ]);
-  assert.deepEqual(activeKeys, [{ itemId: 'item-9', streamIndex: 3 }]);
-});
-
-test('preload jellyfin subtitles applies saved delay before selecting japanese stream', async () => {
+test('preload jellyfin subtitles resets delay before selecting japanese stream', async () => {
   const commands: Array<Array<string | number>> = [];
   const preload = createPreloadJellyfinExternalSubtitlesHandler(
     makeDeps({
@@ -516,14 +624,13 @@ test('preload jellyfin subtitles applies saved delay before selecting japanese s
         ],
       }),
       sendMpvCommand: (command) => commands.push(command),
-      getSavedSubtitleDelay: () => 1.25,
     }),
   );
 
   await preload({ session, clientInfo, itemId: 'item-9' });
 
   const delayIndex = commands.findIndex(
-    (command) => command[0] === 'set_property' && command[1] === 'sub-delay' && command[2] === 1.25,
+    (command) => command[0] === 'set_property' && command[1] === 'sub-delay' && command[2] === 0,
   );
   const selectedSidIndex = commands.findIndex(
     (command) => command[0] === 'set_property' && command[1] === 'sid' && command[2] === 11,
@@ -533,143 +640,6 @@ test('preload jellyfin subtitles applies saved delay before selecting japanese s
   assert.ok(delayIndex < selectedSidIndex);
 });
 
-test('preload jellyfin subtitles auto-aligns late japanese track from english reference', async () => {
-  const commands: Array<Array<string | number>> = [];
-  const savedDelays: Array<{ itemId: string; streamIndex: number; delaySeconds: number }> = [];
-  const primarySrt = `1
-00:00:34,935 --> 00:00:36,937
-Japanese 1
-
-2
-00:00:36,937 --> 00:00:41,441
-Japanese 2
-
-3
-00:00:41,441 --> 00:00:45,279
-Japanese 3
-
-4
-00:00:45,279 --> 00:00:48,115
-Japanese 4
-
-5
-00:00:48,115 --> 00:00:52,286
-Japanese 5
-
-6
-00:00:52,286 --> 00:00:54,955
-Japanese 6
-
-7
-00:00:54,955 --> 00:00:59,793
-Japanese 7
-
-8
-00:00:59,793 --> 00:01:03,630
-Japanese 8
-
-9
-00:01:03,630 --> 00:01:07,634
-Japanese 9
-
-10
-00:01:07,634 --> 00:01:13,040
-Japanese 10
-
-11
-00:01:16,643 --> 00:01:20,814
-Japanese 11
-
-12
-00:01:20,814 --> 00:01:23,116
-Japanese 12
-
-13
-00:01:27,988 --> 00:01:30,991
-Japanese 13
-
-14
-00:01:30,991 --> 00:01:34,094
-Japanese 14
-
-15
-00:01:34,094 --> 00:01:37,097
-Japanese 15
-
-16
-00:01:37,097 --> 00:01:39,100
-Japanese 16
-`;
-  const referenceAss = `[Events]
-Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text
-Dialogue: 0,0:00:03.46,0:00:08.73,Default,,0,0,0,,English 1
-Dialogue: 0,0:00:09.48,0:00:13.61,Default,,0,0,0,,English 2
-Dialogue: 0,0:00:13.61,0:00:19.64,Default,,0,0,0,,English 3
-Dialogue: 0,0:00:21.40,0:00:27.32,Default,,0,0,0,,English 4
-Dialogue: 0,0:00:28.16,0:00:31.75,Default,,0,0,0,,English 5
-Dialogue: 0,0:00:32.06,0:00:34.52,Default,,0,0,0,,English 6
-Dialogue: 0,0:00:35.93,0:00:40.57,Default,,0,0,0,,English 7
-Dialogue: 0,0:00:45.10,0:00:51.01,Default,,0,0,0,,English 8
-Dialogue: 0,0:00:56.57,0:00:59.12,Default,,0,0,0,,English 9
-Dialogue: 0,0:00:59.68,0:01:02.44,Default,,0,0,0,,English 10
-Dialogue: 0,0:01:02.44,0:01:05.56,Default,,0,0,0,,English 11
-Dialogue: 0,0:01:05.56,0:01:06.87,Default,,0,0,0,,English 12
-`;
-  const preload = createPreloadJellyfinExternalSubtitlesHandler(
-    makeDeps({
-      listJellyfinSubtitleTracks: async () => [
-        { index: 0, language: 'jpn', title: 'Japanese', deliveryUrl: 'https://sub/jpn.srt' },
-        { index: 4, language: 'eng', title: 'English', deliveryUrl: 'https://sub/eng.ass' },
-      ],
-      getMpvClient: () => ({
-        requestProperty: async () => [
-          {
-            type: 'sub',
-            id: 10,
-            lang: 'jpn',
-            title: 'Japanese',
-            external: true,
-            'external-filename': '/tmp/subminer-jellyfin-subtitles/0.srt',
-          },
-          {
-            type: 'sub',
-            id: 12,
-            lang: 'eng',
-            title: 'English',
-            external: true,
-            'external-filename': '/tmp/subminer-jellyfin-subtitles/4.ass',
-          },
-        ],
-      }),
-      sendMpvCommand: (command) => commands.push(command),
-      cacheSubtitleTrack: async (track) => ({
-        path: `/tmp/subminer-jellyfin-subtitles/${track.index}.${track.index === 4 ? 'ass' : 'srt'}`,
-        cleanupDir: '/tmp/subminer-jellyfin-subtitles',
-      }),
-      getSavedSubtitleDelay: () => null,
-      loadSubtitleSourceText: async (source) =>
-        source.endsWith('.ass') ? referenceAss : primarySrt,
-      saveSubtitleDelay: (itemId, streamIndex, delaySeconds) => {
-        savedDelays.push({ itemId, streamIndex, delaySeconds });
-      },
-    }),
-  );
-
-  await preload({ session, clientInfo, itemId: 'item-9' });
-
-  const delayCommand = commands.find(
-    (command) => command[0] === 'set_property' && command[1] === 'sub-delay',
-  );
-  assert.ok(delayCommand);
-  const delaySeconds = delayCommand[2];
-  if (typeof delaySeconds !== 'number') {
-    assert.fail('Expected numeric subtitle delay.');
-  }
-  assert.ok(delaySeconds > -32);
-  assert.ok(delaySeconds < -31);
-  assert.deepEqual(savedDelays, [{ itemId: 'item-9', streamIndex: 0, delaySeconds }]);
-});
-
 test('preload jellyfin subtitles accepts numeric string mpv track ids', async () => {
   const commands: Array<Array<string | number>> = [];
   const preload = createPreloadJellyfinExternalSubtitlesHandler(
diff --git a/src/main/runtime/jellyfin-subtitle-preload.ts b/src/main/runtime/jellyfin-subtitle-preload.ts
index 5843075f..7d9f6b7c 100644
--- a/src/main/runtime/jellyfin-subtitle-preload.ts
+++ b/src/main/runtime/jellyfin-subtitle-preload.ts
@@ -1,6 +1,3 @@
-import { parseSubtitleCues } from '../../core/services/subtitle-cue-parser';
-import { estimateSubtitleTimingOffset } from '../../core/services/subtitle-timing-offset';
-
 type JellyfinSession = {
   serverUrl: string;
   accessToken: string;
@@ -35,11 +32,6 @@ type CachedExternalSubtitleTrack = CachedSubtitleTrack & {
   source: JellyfinSubtitleTrack;
 };
 
-type JellyfinSubtitleDelayKey = {
-  itemId: string;
-  streamIndex: number;
-};
-
 type MpvSubtitleTrack = {
   id: number;
   lang: string;
@@ -137,24 +129,48 @@ function pickBestCachedTrackId(
         : false,
     )
     .filter(({ track }) => track.id !== excludeId)
-    .map(({ track, cached }) => {
-      const title = cached?.source.title || track.title;
-      return {
-        track,
-        score:
-          (track.external ? 100 : 0) +
-          (cached?.source.isDefault ? 35 : 0) +
-          (cached?.source.isExternal === false ? 25 : 0) +
-          (cached?.source.isExternal === true ? -10 : 0) +
-          (cached?.source.isForced ? -25 : 0) +
-          (isLikelyHearingImpaired(title) ? -10 : 10) +
-          (/\bdefault\b/i.test(title) ? 3 : 0),
-      };
-    })
+    .flatMap(({ track, cached }) =>
+      cached
+        ? [
+            {
+              track,
+              score:
+                (track.external ? 100 : 0) +
+                scoreJellyfinSource(cached.source, cached.source.title || track.title),
+            },
+          ]
+        : [],
+    )
     .sort((a, b) => b.score - a.score);
   return ranked[0]?.track.id ?? null;
 }
 
+// Ranks Jellyfin subtitle sources by metadata alone, so the preferred track is known before download.
+function scoreJellyfinSource(source: JellyfinSubtitleTrack, title: string): number {
+  return (
+    (source.isDefault ? 35 : 0) +
+    (source.isExternal === false ? 25 : 0) +
+    (source.isExternal === true ? -10 : 0) +
+    (source.isForced ? -25 : 0) +
+    (isLikelyHearingImpaired(title) ? -10 : 10) +
+    (/\bdefault\b/i.test(title) ? 3 : 0)
+  );
+}
+
+function pickPreferredJapaneseSource(
+  sources: JellyfinSubtitleTrack[],
+): JellyfinSubtitleTrack | null {
+  const ranked = sources
+    .filter((source) => isJapanese(source.language || '') || isJapanese(source.title || ''))
+    .map((source) => ({ source, score: scoreJellyfinSource(source, source.title || '') }))
+    .sort((a, b) => b.score - a.score);
+  return ranked[0]?.source ?? null;
+}
+
+function findMpvTrackIdByPath(tracks: MpvSubtitleTrack[], filePath: string): number | null {
+  return tracks.find((track) => track.externalFilename === filePath)?.id ?? null;
+}
+
 function findCachedTrackForMpvTrackId(
   tracks: MpvSubtitleTrack[],
   cachedTracks: CachedExternalSubtitleTrack[],
@@ -257,54 +273,6 @@ async function waitForPreferredSubtitleTracks(
   return subtitleTracks;
 }
 
-async function estimateSubtitleDelayFromReference(
-  deps: {
-    loadSubtitleSourceText?: (source: string) => Promise<string>;
-    logDebug: (message: string, error: unknown) => void;
-  },
-  primaryTrack: CachedExternalSubtitleTrack | null,
-  referenceTrack: CachedExternalSubtitleTrack | null,
-): Promise<number | null> {
-  if (!deps.loadSubtitleSourceText || !primaryTrack || !referenceTrack) {
-    return null;
-  }
-
-  try {
-    const [primaryContent, referenceContent] = await Promise.all([
-      deps.loadSubtitleSourceText(primaryTrack.path),
-      deps.loadSubtitleSourceText(referenceTrack.path),
-    ]);
-    const primaryCues = parseSubtitleCues(primaryContent, primaryTrack.path);
-    const referenceCues = parseSubtitleCues(referenceContent, referenceTrack.path);
-    return estimateSubtitleTimingOffset(primaryCues, referenceCues)?.offsetSeconds ?? null;
-  } catch (error) {
-    deps.logDebug('Failed to auto-align Jellyfin subtitle timing', error);
-    return null;
-  }
-}
-
-function saveEstimatedSubtitleDelay(
-  deps: {
-    saveSubtitleDelay?: (
-      itemId: string,
-      streamIndex: number,
-      delaySeconds: number,
-    ) => boolean | void;
-    logDebug: (message: string, error: unknown) => void;
-  },
-  key: JellyfinSubtitleDelayKey,
-  delaySeconds: number,
-): void {
-  try {
-    const saved = deps.saveSubtitleDelay?.(key.itemId, key.streamIndex, delaySeconds);
-    if (saved === false) {
-      deps.logDebug('Failed to save Jellyfin auto subtitle delay', key);
-    }
-  } catch (error) {
-    deps.logDebug('Failed to save Jellyfin auto subtitle delay', error);
-  }
-}
-
 export function createPreloadJellyfinExternalSubtitlesHandler(deps: {
   listJellyfinSubtitleTracks: (
     session: JellyfinSession,
@@ -316,10 +284,6 @@ export function createPreloadJellyfinExternalSubtitlesHandler(deps: {
   wait: (ms: number) => Promise<void>;
   cacheSubtitleTrack: (track: JellyfinSubtitleTrack) => Promise<CachedSubtitleTrack>;
   cleanupCachedSubtitles: (dirs: string[]) => void;
-  getSavedSubtitleDelay?: (itemId: string, streamIndex: number) => number | null;
-  setActiveSubtitleDelayKey?: (key: JellyfinSubtitleDelayKey | null) => void;
-  loadSubtitleSourceText?: (source: string) => Promise<string>;
-  saveSubtitleDelay?: (itemId: string, streamIndex: number, delaySeconds: number) => boolean | void;
   initSubtitlePrefetch?: (sourcePath: string) => void | Promise<void>;
   logDebug: (message: string, error: unknown) => void;
 }): PreloadJellyfinExternalSubtitlesHandler {
@@ -342,6 +306,22 @@ export function createPreloadJellyfinExternalSubtitlesHandler(deps: {
       });
   }
 
+  function selectJapanesePrimary(
+    subtitleTracks: MpvSubtitleTrack[],
+    cachedTracks: CachedExternalSubtitleTrack[],
+    trackId: number | null,
+  ): void {
+    if (trackId === null) {
+      deps.sendMpvCommand(['set_property', 'sid', 'no']);
+      return;
+    }
+    deps.sendMpvCommand(['set_property', 'sid', trackId]);
+    const selectedCachedTrack = findCachedTrackForMpvTrackId(subtitleTracks, cachedTracks, trackId);
+    if (selectedCachedTrack) {
+      startSubtitlePrefetchForCachedTrack(selectedCachedTrack.path);
+    }
+  }
+
   function cleanupActiveCache(): void {
     const dirs = [...activeCacheDirs];
     if (dirs.length === 0) return;
@@ -357,6 +337,7 @@ export function createPreloadJellyfinExternalSubtitlesHandler(deps: {
     itemId: string;
   }): Promise<void> => {
     try {
+      resetManagedSubtitleDelay();
       try {
         cleanupActiveCache();
       } catch (error) {
@@ -369,8 +350,6 @@ export function createPreloadJellyfinExternalSubtitlesHandler(deps: {
       );
       const externalTracks = tracks.filter((track) => Boolean(track.deliveryUrl));
       if (externalTracks.length === 0) {
-        deps.setActiveSubtitleDelayKey?.(null);
-        resetManagedSubtitleDelay();
         return;
       }
 
@@ -380,91 +359,93 @@ export function createPreloadJellyfinExternalSubtitlesHandler(deps: {
       deps.sendMpvCommand(['set_property', 'secondary-sub-visibility', 'no']);
       await deps.wait(300);
       const seenUrls = new Set<string>();
-      const cachedTracks: CachedExternalSubtitleTrack[] = [];
-      for (const track of externalTracks) {
-        if (!track.deliveryUrl || seenUrls.has(track.deliveryUrl)) {
-          continue;
-        }
+      const uniqueTracks = externalTracks.filter((track) => {
+        if (!track.deliveryUrl || seenUrls.has(track.deliveryUrl)) return false;
         seenUrls.add(track.deliveryUrl);
-        const labelBase = (track.title || track.language || '').trim();
-        const label = labelBase || `Jellyfin Subtitle ${track.index}`;
-        const cached = await deps.cacheSubtitleTrack(track);
-        activeCacheDirs.add(cached.cleanupDir);
-        cachedTracks.push({ ...cached, source: track });
-        deps.sendMpvCommand(['sub-add', cached.path, 'auto', label, track.language || '']);
-      }
+        return true;
+      });
 
-      await deps.wait(TRACK_SELECTION_INITIAL_WAIT_MS);
-      const shouldWaitForExternalJapanese = externalTracks.some(
-        (track) => isJapanese(track.language || '') || isJapanese(track.title || ''),
-      );
-      const subtitleTracks = await waitForPreferredSubtitleTracks(
-        deps,
-        shouldWaitForExternalJapanese,
-        cachedTracks.map((track) => track.path),
-      );
-      if (
-        shouldWaitForExternalJapanese &&
-        (!subtitleTracks || !hasExternalJapaneseTrack(subtitleTracks))
-      ) {
-        deps.logDebug('Timed out waiting for Jellyfin Japanese subtitle track', {
-          itemId: params.itemId,
-        });
-        return;
-      }
-
-      const resolvedSubtitleTracks = subtitleTracks ?? [];
-      const japanesePrimaryId =
-        pickBestCachedTrackId(resolvedSubtitleTracks, cachedTracks, isJapanese) ??
-        pickBestTrackId(resolvedSubtitleTracks, isJapanese);
-      const englishSecondaryId =
-        pickBestCachedTrackId(resolvedSubtitleTracks, cachedTracks, isEnglish, japanesePrimaryId) ??
-        pickBestTrackId(resolvedSubtitleTracks, isEnglish, japanesePrimaryId);
-      if (japanesePrimaryId !== null) {
-        const selectedCachedTrack = findCachedTrackForMpvTrackId(
-          resolvedSubtitleTracks,
-          cachedTracks,
-          japanesePrimaryId,
-        );
-        if (selectedCachedTrack) {
-          const delayKey = { itemId: params.itemId, streamIndex: selectedCachedTrack.source.index };
-          deps.setActiveSubtitleDelayKey?.(delayKey);
-          const savedDelay = deps.getSavedSubtitleDelay?.(delayKey.itemId, delayKey.streamIndex);
-          if (typeof savedDelay === 'number' && Number.isFinite(savedDelay)) {
-            deps.sendMpvCommand(['set_property', 'sub-delay', savedDelay]);
-          } else {
-            const referenceCachedTrack = findCachedTrackForMpvTrackId(
-              resolvedSubtitleTracks,
-              cachedTracks,
-              englishSecondaryId,
-            );
-            const estimatedDelay = await estimateSubtitleDelayFromReference(
-              deps,
-              selectedCachedTrack,
-              referenceCachedTrack,
-            );
-            if (estimatedDelay !== null) {
-              deps.sendMpvCommand(['set_property', 'sub-delay', estimatedDelay]);
-              saveEstimatedSubtitleDelay(deps, delayKey, estimatedDelay);
-            } else {
-              resetManagedSubtitleDelay();
+      // Download every track at once and add each to mpv as soon as it lands. Jellyfin has
+      // to extract embedded tracks from the container, so one slow track must not hold up
+      // the Japanese primary that annotations depend on. A failed track is skipped rather
+      // than failing the whole preload, so the remaining tracks still get selected.
+      const cachedTracks: CachedExternalSubtitleTrack[] = [];
+      const downloads = new Map(
+        uniqueTracks.map((track) => [
+          track,
+          (async (): Promise<CachedExternalSubtitleTrack | null> => {
+            const labelBase = (track.title || track.language || '').trim();
+            const label = labelBase || `Jellyfin Subtitle ${track.index}`;
+            let cached: CachedExternalSubtitleTrack;
+            try {
+              cached = { ...(await deps.cacheSubtitleTrack(track)), source: track };
+            } catch (error) {
+              deps.logDebug(`Failed to download Jellyfin subtitle track ${track.index}`, error);
+              return null;
             }
-          }
-          deps.sendMpvCommand(['set_property', 'sid', japanesePrimaryId]);
-          startSubtitlePrefetchForCachedTrack(selectedCachedTrack.path);
-        } else {
-          deps.setActiveSubtitleDelayKey?.(null);
-          resetManagedSubtitleDelay();
-          deps.sendMpvCommand(['set_property', 'sid', japanesePrimaryId]);
-        }
-      } else {
-        deps.sendMpvCommand(['set_property', 'sid', 'no']);
-        deps.setActiveSubtitleDelayKey?.(null);
-        resetManagedSubtitleDelay();
-      }
+            activeCacheDirs.add(cached.cleanupDir);
+            cachedTracks.push(cached);
+            deps.sendMpvCommand(['sub-add', cached.path, 'auto', label, track.language || '']);
+            return cached;
+          })(),
+        ]),
+      );
+      const allDownloads = Promise.all(downloads.values());
 
-      if (englishSecondaryId !== null) {
-        deps.sendMpvCommand(['set_property', 'secondary-sid', englishSecondaryId]);
+      try {
+        let subtitleTracks: MpvSubtitleTrack[] = [];
+        let japanesePrimaryId: number | null | undefined;
+
+        const preferredJapaneseSource = pickPreferredJapaneseSource(uniqueTracks);
+        const preferredJapanese = preferredJapaneseSource
+          ? await downloads.get(preferredJapaneseSource)
+          : null;
+        if (preferredJapanese) {
+          await deps.wait(TRACK_SELECTION_INITIAL_WAIT_MS);
+          subtitleTracks =
+            (await waitForPreferredSubtitleTracks(deps, true, [preferredJapanese.path])) ?? [];
+          if (!hasExternalJapaneseTrack(subtitleTracks)) {
+            deps.logDebug('Timed out waiting for Jellyfin Japanese subtitle track', {
+              itemId: params.itemId,
+            });
+            return;
+          }
+          // Only commit early to the preferred track. If mpv has not listed it yet, leave the
+          // choice to the full ranking below instead of locking in a lower-ranked fallback.
+          const preferredJapaneseTrackId = findMpvTrackIdByPath(
+            subtitleTracks,
+            preferredJapanese.path,
+          );
+          if (preferredJapaneseTrackId !== null) {
+            japanesePrimaryId = preferredJapaneseTrackId;
+            selectJapanesePrimary(subtitleTracks, cachedTracks, japanesePrimaryId);
+          }
+        }
+
+        await allDownloads;
+        const cachedPaths = cachedTracks.map((track) => track.path);
+        if (!hasExpectedExternalSubtitleTracks(subtitleTracks, cachedPaths)) {
+          await deps.wait(TRACK_SELECTION_INITIAL_WAIT_MS);
+          subtitleTracks = (await waitForPreferredSubtitleTracks(deps, false, cachedPaths)) ?? [];
+        }
+
+        if (japanesePrimaryId === undefined) {
+          japanesePrimaryId =
+            pickBestCachedTrackId(subtitleTracks, cachedTracks, isJapanese) ??
+            pickBestTrackId(subtitleTracks, isJapanese);
+          selectJapanesePrimary(subtitleTracks, cachedTracks, japanesePrimaryId);
+        }
+
+        const englishSecondaryId =
+          pickBestCachedTrackId(subtitleTracks, cachedTracks, isEnglish, japanesePrimaryId) ??
+          pickBestTrackId(subtitleTracks, isEnglish, japanesePrimaryId);
+        if (englishSecondaryId !== null) {
+          deps.sendMpvCommand(['set_property', 'secondary-sid', englishSecondaryId]);
+        }
+      } finally {
+        // Keep this run in the queue until every download has registered its cache dir, so
+        // the next run's cleanup sees them all.
+        await allDownloads;
       }
     } catch (error) {
       deps.logDebug('Failed to preload Jellyfin external subtitles', error);
diff --git a/src/main/runtime/linux-overlay-mode-runtime.test.ts b/src/main/runtime/linux-overlay-mode-runtime.test.ts
new file mode 100644
index 00000000..2ef3350d
--- /dev/null
+++ b/src/main/runtime/linux-overlay-mode-runtime.test.ts
@@ -0,0 +1,93 @@
+import assert from 'node:assert/strict';
+import { EventEmitter } from 'node:events';
+import { test } from 'node:test';
+import { createLinuxOverlayModeRuntime } from './linux-overlay-mode-runtime';
+
+class TestWindow extends EventEmitter {
+  destroyed = false;
+  hidden = false;
+  isDestroyed() {
+    return this.destroyed;
+  }
+  hide() {
+    this.hidden = true;
+  }
+  destroy() {
+    this.destroyed = true;
+  }
+  finishClose() {
+    this.emit('closed');
+  }
+}
+
+function fixture() {
+  const initial = new TestWindow();
+  const state: { window: TestWindow | null; visible: boolean; creates: number; refreshes: number } =
+    {
+      window: initial,
+      visible: true,
+      creates: 0,
+      refreshes: 0,
+    };
+  const runtime = createLinuxOverlayModeRuntime({
+    isEnabled: () => true,
+    isVisible: () => state.visible,
+    getWindow: () => state.window,
+    clearWindow: () => {
+      state.window = null;
+    },
+    createWindow: () => {
+      state.creates += 1;
+      state.window = new TestWindow();
+    },
+    refreshWindow: () => {
+      state.refreshes += 1;
+    },
+    now: () => 42,
+    logDebug: () => {},
+  });
+  return { initial, state, runtime };
+}
+
+test('Linux mode transition waits for close before replacing and refreshing the window', () => {
+  const { initial, state, runtime } = fixture();
+  runtime.ownerBindingKey = 'old-owner';
+  runtime.sync(true);
+  assert.equal(runtime.mode, 'fullscreen-override');
+  assert.equal(runtime.fullscreenChangedAtMs, 42);
+  assert.equal(runtime.ownerBindingKey, null);
+  assert.equal(initial.hidden, true);
+  assert.equal(state.creates, 0);
+  initial.finishClose();
+  assert.equal(state.creates, 1);
+  assert.equal(state.refreshes, 1);
+  runtime.sync(true);
+  assert.equal(state.creates, 1);
+});
+
+test('an older close callback cannot clear or replace a newer overlay', () => {
+  const { initial, state, runtime } = fixture();
+  runtime.sync(true);
+  runtime.sync(false);
+  const replacement = state.window;
+  assert.equal(state.creates, 1);
+  initial.finishClose();
+  assert.equal(state.window, replacement);
+  assert.equal(state.creates, 1);
+  assert.equal(runtime.mode, 'managed');
+});
+
+test('hiding or cancelling a transition prevents delayed window creation', () => {
+  for (const cancel of [false, true]) {
+    const { initial, state, runtime } = fixture();
+    runtime.sync(true);
+    if (cancel) runtime.cancelPendingTransition();
+    else state.visible = false;
+    initial.finishClose();
+    assert.equal(state.creates, 0);
+    assert.equal(state.window, null);
+    state.visible = true;
+    runtime.sync(true);
+    assert.equal(state.creates, 1);
+  }
+});
diff --git a/src/main/runtime/linux-overlay-mode-runtime.ts b/src/main/runtime/linux-overlay-mode-runtime.ts
new file mode 100644
index 00000000..d2bed651
--- /dev/null
+++ b/src/main/runtime/linux-overlay-mode-runtime.ts
@@ -0,0 +1,94 @@
+import type { BrowserWindow } from 'electron';
+import {
+  resolveLinuxVisibleOverlayWindowModeAction,
+  type LinuxVisibleOverlayWindowMode,
+} from './linux-visible-overlay-window-mode';
+
+type OverlayWindow = Pick<BrowserWindow, 'isDestroyed' | 'hide' | 'destroy'> & {
+  once: (event: 'closed', listener: () => void) => unknown;
+};
+
+export function createLinuxOverlayModeRuntime<Window extends OverlayWindow>(deps: {
+  isEnabled: () => boolean;
+  isVisible: () => boolean;
+  getWindow: () => Window | null;
+  clearWindow: () => void;
+  createWindow: () => void;
+  refreshWindow: () => void;
+  now: () => number;
+  logDebug: (message: string) => void;
+}) {
+  let mode: LinuxVisibleOverlayWindowMode = 'managed';
+  let fullscreen = false;
+  let fullscreenChangedAtMs = 0;
+  let ownerBindingKey: string | null = null;
+  let generation = 0;
+
+  function createWindowForMode(token: number, nextFullscreen: boolean): void {
+    if (token !== generation || !deps.isVisible()) return;
+    const existing = deps.getWindow();
+    if (existing && !existing.isDestroyed()) return;
+    deps.createWindow();
+    deps.refreshWindow();
+    deps.logDebug(
+      `Switched Linux visible overlay window mode to ${mode} for mpv fullscreen=${nextFullscreen}`,
+    );
+  }
+
+  function sync(nextFullscreen: boolean): void {
+    if (!deps.isEnabled()) return;
+    if (fullscreen !== nextFullscreen) fullscreenChangedAtMs = deps.now();
+    fullscreen = nextFullscreen;
+    const current = deps.getWindow();
+    const action = resolveLinuxVisibleOverlayWindowModeAction({
+      currentMode: mode,
+      fullscreen,
+      hasLiveWindow: Boolean(current && !current.isDestroyed()),
+      visibleOverlayVisible: deps.isVisible(),
+    });
+    mode = action.nextMode;
+    ownerBindingKey = null;
+    const token = ++generation;
+    if (!action.shouldCreateWindow && !action.shouldDestroyCurrentWindow) return;
+
+    if (action.shouldDestroyCurrentWindow && current && !current.isDestroyed()) {
+      current.once('closed', () => {
+        if (deps.getWindow() === current) deps.clearWindow();
+        if (action.createWindowTiming === 'after-current-destroyed') {
+          createWindowForMode(token, nextFullscreen);
+        }
+      });
+      current.hide();
+      current.destroy();
+    }
+    if (!action.shouldCreateWindow) {
+      deps.logDebug(
+        `Recorded Linux visible overlay window mode ${action.nextMode} for hidden mpv fullscreen=${fullscreen}`,
+      );
+      return;
+    }
+    if (action.createWindowTiming === 'now') createWindowForMode(token, nextFullscreen);
+  }
+
+  return {
+    get mode() {
+      return mode;
+    },
+    get fullscreen() {
+      return fullscreen;
+    },
+    get fullscreenChangedAtMs() {
+      return fullscreenChangedAtMs;
+    },
+    get ownerBindingKey() {
+      return ownerBindingKey;
+    },
+    set ownerBindingKey(key: string | null) {
+      ownerBindingKey = key;
+    },
+    sync,
+    cancelPendingTransition: () => {
+      generation += 1;
+    },
+  };
+}
diff --git a/src/main/runtime/linux-runtime-plugin-assets.test.ts b/src/main/runtime/linux-runtime-plugin-assets.test.ts
index 551d896b..9ad93fda 100644
--- a/src/main/runtime/linux-runtime-plugin-assets.test.ts
+++ b/src/main/runtime/linux-runtime-plugin-assets.test.ts
@@ -8,6 +8,18 @@ import {
   resolveManagedLinuxRuntimePluginPaths,
 } from './linux-runtime-plugin-assets';
 
+const THUMBNAILER_RELATIVE_PATH = path.join(
+  'thumbnailers',
+  'subminer-ffmpegthumbnailer.thumbnailer',
+);
+
+function writeThumbnailer(rootDir: string, content = '[Thumbnailer Entry]\n'): string {
+  const thumbnailerPath = path.join(rootDir, THUMBNAILER_RELATIVE_PATH);
+  fs.mkdirSync(path.dirname(thumbnailerPath), { recursive: true });
+  fs.writeFileSync(thumbnailerPath, content);
+  return thumbnailerPath;
+}
+
 async function withTempDir<T>(fn: (dir: string) => Promise<T> | T): Promise<T> {
   const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'subminer-linux-plugin-assets-test-'));
   try {
@@ -48,6 +60,7 @@ test('resolveManagedLinuxRuntimePluginPaths resolves XDG data target paths', ()
     pluginEntrypointPath: '/tmp/xdg-data/SubMiner/plugin/subminer/main.lua',
     pluginConfigPath: '/tmp/xdg-data/SubMiner/plugin/subminer.conf',
     themePath: '/tmp/xdg-data/SubMiner/themes/subminer.rasi',
+    thumbnailerPath: '/tmp/xdg-data/SubMiner/thumbnailers/subminer-ffmpegthumbnailer.thumbnailer',
   });
 });
 
@@ -79,6 +92,7 @@ test('ensureLinuxRuntimePluginAssets installs managed plugin dir, config, and ro
   await withTempDir(async (tempDir) => {
     const sourceRoot = path.join(tempDir, 'source', 'plugin');
     const themeSourcePath = path.join(tempDir, 'source', 'assets', 'themes', 'subminer.rasi');
+    const thumbnailerSourcePath = writeThumbnailer(path.join(tempDir, 'source', 'assets'));
     const targetRoot = path.join(tempDir, 'xdg-data', 'SubMiner', 'plugin');
     fs.mkdirSync(path.join(sourceRoot, 'subminer'), { recursive: true });
     fs.mkdirSync(path.dirname(themeSourcePath), { recursive: true });
@@ -94,6 +108,7 @@ test('ensureLinuxRuntimePluginAssets installs managed plugin dir, config, and ro
         pluginDirSource: path.join(sourceRoot, 'subminer'),
         pluginConfigSource: path.join(sourceRoot, 'subminer.conf'),
         themeSourcePath,
+        thumbnailerSourcePath,
       }),
     });
 
@@ -117,6 +132,19 @@ test('ensureLinuxRuntimePluginAssets installs managed plugin dir, config, and ro
       ),
       '/* theme */\n',
     );
+    assert.equal(
+      fs.readFileSync(
+        path.join(
+          tempDir,
+          'xdg-data',
+          'SubMiner',
+          'thumbnailers',
+          'subminer-ffmpegthumbnailer.thumbnailer',
+        ),
+        'utf8',
+      ),
+      '[Thumbnailer Entry]\n',
+    );
   });
 });
 
@@ -124,6 +152,7 @@ test('ensureLinuxRuntimePluginAssets installs managed theme when plugin assets a
   await withTempDir(async (tempDir) => {
     const sourceRoot = path.join(tempDir, 'source', 'plugin');
     const themeSourcePath = path.join(tempDir, 'source', 'assets', 'themes', 'subminer.rasi');
+    const thumbnailerSourcePath = writeThumbnailer(path.join(tempDir, 'source', 'assets'));
     const xdgDataHome = path.join(tempDir, 'xdg-data');
     const targetRoot = path.join(xdgDataHome, 'SubMiner', 'plugin');
     fs.mkdirSync(path.join(sourceRoot, 'subminer'), { recursive: true });
@@ -143,6 +172,7 @@ test('ensureLinuxRuntimePluginAssets installs managed theme when plugin assets a
         pluginDirSource: path.join(sourceRoot, 'subminer'),
         pluginConfigSource: path.join(sourceRoot, 'subminer.conf'),
         themeSourcePath,
+        thumbnailerSourcePath,
       }),
     });
 
@@ -169,6 +199,7 @@ test('ensureLinuxRuntimePluginAssets installs managed theme when plugin assets a
 test('ensureLinuxRuntimePluginAssets installs managed theme without resolving plugin sources when plugin assets already exist', async () => {
   await withTempDir(async (tempDir) => {
     const themeSourcePath = path.join(tempDir, 'source', 'assets', 'themes', 'subminer.rasi');
+    const thumbnailerSourcePath = writeThumbnailer(path.join(tempDir, 'source', 'assets'));
     const xdgDataHome = path.join(tempDir, 'xdg-data');
     const targetRoot = path.join(xdgDataHome, 'SubMiner', 'plugin');
     fs.mkdirSync(path.dirname(themeSourcePath), { recursive: true });
@@ -183,6 +214,7 @@ test('ensureLinuxRuntimePluginAssets installs managed theme without resolving pl
       xdgDataHome,
       resolveBundledAssets: () => ({
         themeSourcePath,
+        thumbnailerSourcePath,
       }),
     });
 
@@ -250,6 +282,7 @@ test('ensureLinuxRuntimePluginAssets installs managed plugin assets without reso
       path.join(xdgDataHome, 'SubMiner', 'themes', 'subminer.rasi'),
       '/* existing theme */\n',
     );
+    const thumbnailerSourcePath = writeThumbnailer(path.join(tempDir, 'source', 'assets'));
 
     const result = await ensureLinuxRuntimePluginAssets({
       platform: 'linux',
@@ -258,6 +291,7 @@ test('ensureLinuxRuntimePluginAssets installs managed plugin assets without reso
       resolveBundledAssets: () => ({
         pluginDirSource: path.join(sourceRoot, 'subminer'),
         pluginConfigSource: path.join(sourceRoot, 'subminer.conf'),
+        thumbnailerSourcePath,
       }),
     });
 
@@ -332,6 +366,7 @@ test('ensureLinuxRuntimePluginAssets returns already-present when managed assets
       path.join(xdgDataHome, 'SubMiner', 'themes', 'subminer.rasi'),
       '/* theme */\n',
     );
+    writeThumbnailer(path.join(xdgDataHome, 'SubMiner'));
 
     const result = await ensureLinuxRuntimePluginAssets({
       platform: 'linux',
@@ -369,6 +404,7 @@ test('ensureLinuxRuntimePluginAssets leaves no final target tree on failed insta
   await withTempDir(async (tempDir) => {
     const sourceRoot = path.join(tempDir, 'source', 'plugin');
     const themeSourcePath = path.join(tempDir, 'source', 'assets', 'themes', 'subminer.rasi');
+    const thumbnailerSourcePath = writeThumbnailer(path.join(tempDir, 'source', 'assets'));
     const xdgDataHome = path.join(tempDir, 'xdg-data');
     const targetRoot = path.join(xdgDataHome, 'SubMiner', 'plugin');
     fs.mkdirSync(path.join(sourceRoot, 'subminer'), { recursive: true });
@@ -385,6 +421,7 @@ test('ensureLinuxRuntimePluginAssets leaves no final target tree on failed insta
         pluginDirSource: path.join(sourceRoot, 'subminer'),
         pluginConfigSource: path.join(sourceRoot, 'subminer.conf'),
         themeSourcePath,
+        thumbnailerSourcePath,
       }),
       copyFile: async () => {
         throw new Error('copy failed');
diff --git a/src/main/runtime/linux-runtime-plugin-assets.ts b/src/main/runtime/linux-runtime-plugin-assets.ts
index 8a638081..48f398cd 100644
--- a/src/main/runtime/linux-runtime-plugin-assets.ts
+++ b/src/main/runtime/linux-runtime-plugin-assets.ts
@@ -10,6 +10,7 @@ export interface ManagedLinuxRuntimePluginPaths {
   pluginEntrypointPath: string;
   pluginConfigPath: string;
   themePath: string;
+  thumbnailerPath: string;
 }
 
 export interface EnsureLinuxRuntimePluginAssetsResult {
@@ -23,6 +24,7 @@ interface RuntimePluginAssetSources {
   pluginDirSource?: string;
   pluginConfigSource?: string;
   themeSourcePath?: string;
+  thumbnailerSourcePath?: string;
 }
 
 interface RuntimePluginDirentLike {
@@ -72,6 +74,11 @@ export function resolveManagedLinuxRuntimePluginPaths(options: {
     pluginEntrypointPath: pathModule.join(pluginDir, 'main.lua'),
     pluginConfigPath: pathModule.join(rootDir, 'subminer.conf'),
     themePath: pathModule.join(dataDir, 'themes', 'subminer.rasi'),
+    thumbnailerPath: pathModule.join(
+      dataDir,
+      'thumbnailers',
+      'subminer-ffmpegthumbnailer.thumbnailer',
+    ),
   };
 }
 
@@ -95,11 +102,12 @@ async function copyDirectoryRecursive(
   }
 }
 
-function resolveBundledThemePath(options: {
+function resolveBundledAssetPath(options: {
   dirname: string;
   appPath: string;
   resourcesPath: string;
   existsSync: (candidate: string) => boolean;
+  relativePath: string;
 }): string | null {
   const roots = [
     path.join(options.resourcesPath, 'assets'),
@@ -111,7 +119,7 @@ function resolveBundledThemePath(options: {
   ];
 
   for (const root of roots) {
-    const candidate = path.join(root, 'themes', 'subminer.rasi');
+    const candidate = path.join(root, options.relativePath);
     if (options.existsSync(candidate)) return candidate;
   }
 
@@ -129,16 +137,25 @@ function resolveBundledAssetsDefault(
     existsSync,
   });
 
-  const themeSourcePath = resolveBundledThemePath({
+  const themeSourcePath = resolveBundledAssetPath({
     dirname: __dirname,
     appPath: process.execPath,
     resourcesPath,
     existsSync,
+    relativePath: path.join('themes', 'subminer.rasi'),
+  });
+  const thumbnailerSourcePath = resolveBundledAssetPath({
+    dirname: __dirname,
+    appPath: process.execPath,
+    resourcesPath,
+    existsSync,
+    relativePath: path.join('thumbnailers', 'subminer-ffmpegthumbnailer.thumbnailer'),
   });
 
   return {
     ...(pluginAssets ?? {}),
     ...(themeSourcePath ? { themeSourcePath } : {}),
+    ...(thumbnailerSourcePath ? { thumbnailerSourcePath } : {}),
   };
 }
 
@@ -178,7 +195,8 @@ export async function ensureLinuxRuntimePluginAssets(
   const pluginAssetsExist =
     existsSync(managedPaths.pluginEntrypointPath) && existsSync(managedPaths.pluginConfigPath);
   const themeExists = existsSync(managedPaths.themePath);
-  if (pluginAssetsExist && themeExists) {
+  const thumbnailerExists = existsSync(managedPaths.thumbnailerPath);
+  if (pluginAssetsExist && themeExists && thumbnailerExists) {
     return {
       ok: true,
       status: 'already-present',
@@ -193,6 +211,7 @@ export async function ensureLinuxRuntimePluginAssets(
 
   const shouldInstallPluginAssets = !pluginAssetsExist;
   const shouldInstallTheme = !themeExists;
+  const shouldInstallThumbnailer = !thumbnailerExists;
   if (
     shouldInstallPluginAssets &&
     (!bundledAssets.pluginDirSource || !bundledAssets.pluginConfigSource)
@@ -210,6 +229,13 @@ export async function ensureLinuxRuntimePluginAssets(
       error: 'Bundled Linux runtime theme asset was not found.',
     };
   }
+  if (shouldInstallThumbnailer && !bundledAssets.thumbnailerSourcePath) {
+    return {
+      ok: false,
+      status: 'failed',
+      error: 'Bundled Linux rofi thumbnailer asset was not found.',
+    };
+  }
 
   const stagingSuffix = `${process.pid}-${Date.now()}`;
   const stagedPluginDir = pathModule.join(managedPaths.rootDir, `.subminer-stage-${stagingSuffix}`);
@@ -221,9 +247,14 @@ export async function ensureLinuxRuntimePluginAssets(
     pathModule.dirname(managedPaths.themePath),
     `.subminer.rasi-stage-${stagingSuffix}`,
   );
+  const stagedThumbnailerPath = pathModule.join(
+    pathModule.dirname(managedPaths.thumbnailerPath),
+    `.subminer-ffmpegthumbnailer.thumbnailer-stage-${stagingSuffix}`,
+  );
   let pluginDirInstalled = false;
   let pluginConfigInstalled = false;
   let themeInstalled = false;
+  let thumbnailerInstalled = false;
 
   try {
     if (shouldInstallPluginAssets) {
@@ -249,6 +280,14 @@ export async function ensureLinuxRuntimePluginAssets(
       await mkdir(pathModule.dirname(managedPaths.themePath), { recursive: true });
       await copyFile(themeSourcePath, stagedThemePath);
     }
+    if (shouldInstallThumbnailer) {
+      const thumbnailerSourcePath = bundledAssets.thumbnailerSourcePath;
+      if (!thumbnailerSourcePath) {
+        throw new Error('Bundled Linux rofi thumbnailer asset was not found.');
+      }
+      await mkdir(pathModule.dirname(managedPaths.thumbnailerPath), { recursive: true });
+      await copyFile(thumbnailerSourcePath, stagedThumbnailerPath);
+    }
     if (shouldInstallPluginAssets) {
       await rm(managedPaths.pluginDir, { recursive: true, force: true });
       await rm(managedPaths.pluginConfigPath, { force: true });
@@ -262,6 +301,11 @@ export async function ensureLinuxRuntimePluginAssets(
       await rename(stagedThemePath, managedPaths.themePath);
       themeInstalled = true;
     }
+    if (shouldInstallThumbnailer) {
+      await rm(managedPaths.thumbnailerPath, { force: true });
+      await rename(stagedThumbnailerPath, managedPaths.thumbnailerPath);
+      thumbnailerInstalled = true;
+    }
 
     return {
       ok: true,
@@ -278,9 +322,13 @@ export async function ensureLinuxRuntimePluginAssets(
     if (themeInstalled) {
       await rm(managedPaths.themePath, { force: true }).catch(() => {});
     }
+    if (thumbnailerInstalled) {
+      await rm(managedPaths.thumbnailerPath, { force: true }).catch(() => {});
+    }
     await rm(stagedPluginDir, { recursive: true, force: true }).catch(() => {});
     await rm(stagedPluginConfigPath, { force: true }).catch(() => {});
     await rm(stagedThemePath, { force: true }).catch(() => {});
+    await rm(stagedThumbnailerPath, { force: true }).catch(() => {});
     return {
       ok: false,
       status: 'failed',
diff --git a/src/main/runtime/managed-launcher.test.ts b/src/main/runtime/managed-launcher.test.ts
new file mode 100644
index 00000000..fa1af02d
--- /dev/null
+++ b/src/main/runtime/managed-launcher.test.ts
@@ -0,0 +1,412 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawn, spawnSync } from 'node:child_process';
+import test from 'node:test';
+import {
+  createUpdateStateStore,
+  takePendingLauncherMigrationPath,
+  type UpdateState,
+} from './update/update-service';
+import {
+  detectBun,
+  installBun,
+  installLauncher,
+  refreshManagedCommandLineLauncher,
+} from './command-line-launcher';
+import {
+  cleanupOldWindowsManagedRuntimes,
+  MANAGED_LAUNCHER_MARKER,
+  managedLauncherContent,
+  managedLauncherPaths,
+  stageManagedLauncher,
+  windowsManagedRuntimePaths,
+} from './managed-launcher';
+
+function workspace(t: test.TestContext) {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "subminer bundled bun's "));
+  t.after(() => fs.rmSync(root, { recursive: true, force: true }));
+  return root;
+}
+
+test('a missing packaged Bun never falls back to system Bun or runs an installer', async () => {
+  let calls = 0;
+  const options = {
+    bundledBunPath: '/missing/private/bun',
+    env: { PATH: path.dirname(process.execPath) },
+    existsSync: (candidate: string) => candidate === process.execPath,
+    runCommand: async () => {
+      calls += 1;
+      return { exitCode: 0, stdout: '1.3.5', stderr: '' };
+    },
+  };
+  for (const snapshot of [await detectBun(options), await installBun(options)]) {
+    assert.equal(snapshot.status, 'missing');
+    assert.equal(snapshot.installCommand, null);
+    assert.match(snapshot.message ?? '', /Reinstall SubMiner/);
+  }
+  assert.equal(calls, 0);
+});
+
+test('packaged POSIX launcher works without Bun on PATH and survives AppImage unmount', async (t) => {
+  if (process.platform !== 'linux') return;
+  const root = workspace(t);
+  const resources = path.join(root, 'mounted resources');
+  const bin = path.join(root, 'home', '.local', 'bin');
+  fs.mkdirSync(resources, { recursive: true });
+  fs.mkdirSync(bin, { recursive: true });
+  const launcherResourcePath = path.join(resources, 'subminer');
+  const bundledBunPath = path.join(resources, 'bun');
+  fs.symlinkSync(process.execPath, bundledBunPath);
+  fs.writeFileSync(
+    launcherResourcePath,
+    'console.log(JSON.stringify({args:process.argv.slice(2),app:process.env.SUBMINER_BINARY_PATH,managed:process.env.SUBMINER_MANAGED_LAUNCHER}));',
+  );
+  const appPath = path.join(root, 'SubMiner.AppImage');
+  fs.writeFileSync(appPath, '#!/bin/sh\nexit 73\n', { mode: 0o755 });
+  const options = {
+    platform: process.platform,
+    homeDir: path.join(root, 'home'),
+    env: {
+      HOME: path.join(root, 'home'),
+      PATH: bin,
+      XDG_DATA_HOME: path.join(root, 'data'),
+      APPIMAGE: appPath,
+    },
+    appExePath: path.join(resources, 'SubMiner'),
+    appVersion: '1.0.0',
+    bundledBunPath,
+    launcherResourcePath,
+  };
+  const installed = await installLauncher(options);
+  assert.equal(installed.status, 'ready', installed.message ?? 'install failed');
+  assert.match(fs.readFileSync(path.join(bin, 'subminer'), 'utf8'), /SubMiner managed launcher/);
+  fs.renameSync(resources, path.join(root, 'unmounted'));
+  const args = ['file with spaces.mkv', "single'quote", '$HOME', '$(touch nope)', '日本語'];
+  const result = spawnSync(path.join(bin, 'subminer'), args, {
+    env: options.env,
+    encoding: 'utf8',
+    timeout: 15000,
+  });
+  assert.equal(result.status, 0, result.stderr);
+  assert.deepEqual(JSON.parse(result.stdout), { args, app: appPath, managed: '1' });
+});
+
+test('setup can install into a new user bin despite an empty GUI PATH', async (t) => {
+  if (process.platform === 'win32') return;
+  const root = workspace(t);
+  const appPath = path.join(root, 'SubMiner.app', 'Contents', 'MacOS', 'SubMiner');
+  const resources = path.join(root, 'SubMiner.app', 'Contents', 'Resources');
+  fs.mkdirSync(path.dirname(appPath), { recursive: true });
+  fs.mkdirSync(path.join(resources, 'bun'), { recursive: true });
+  fs.mkdirSync(path.join(resources, 'launcher'), { recursive: true });
+  fs.writeFileSync(appPath, '#!/bin/sh\nexit 73\n', { mode: 0o755 });
+  fs.symlinkSync(process.execPath, path.join(resources, 'bun', 'bun'));
+  const script = path.join(resources, 'launcher', 'subminer.js');
+  fs.writeFileSync(script, 'console.log("help");');
+  const snapshot = await installLauncher({
+    platform: 'darwin',
+    homeDir: root,
+    env: { PATH: '' },
+    appExePath: appPath,
+    bundledBunPath: process.execPath,
+    launcherResourcePath: script,
+  });
+  assert.equal(snapshot.status, 'not_on_path', snapshot.message ?? 'install failed');
+  assert.equal(snapshot.installPath, path.join(root, '.local', 'bin', 'subminer'));
+  assert.match(snapshot.message ?? '', /export PATH=/);
+  const result = spawnSync(snapshot.installPath!, ['--help'], {
+    env: { PATH: '' },
+    encoding: 'utf8',
+  });
+  assert.equal(result.status, 0, result.stderr);
+});
+
+test('app upgrades refresh payloads, migrate legacy Bun launchers, and preserve custom scripts', async (t) => {
+  if (process.platform !== 'linux') return;
+  const root = workspace(t);
+  const bin = path.join(root, 'bin');
+  fs.mkdirSync(bin, { recursive: true });
+  const script = path.join(root, 'resource');
+  fs.writeFileSync(script, 'console.log("old");');
+  const appPath = path.join(root, 'SubMiner.AppImage');
+  fs.writeFileSync(appPath, '#!/bin/sh\nexit 73\n', { mode: 0o755 });
+  const options = {
+    platform: process.platform,
+    homeDir: root,
+    env: { HOME: root, PATH: bin },
+    appVersion: '1',
+    appExePath: appPath,
+    bundledBunPath: process.execPath,
+    launcherResourcePath: script,
+  };
+  assert.equal((await installLauncher(options)).status, 'ready');
+  fs.writeFileSync(script, 'console.log("new");');
+  await refreshManagedCommandLineLauncher({
+    ...options,
+    env: { HOME: root, PATH: '' },
+    appVersion: '2',
+  });
+  const payload = managedLauncherPaths(options);
+  assert.equal(fs.readFileSync(payload.scriptPath, 'utf8'), 'console.log("new");');
+  fs.writeFileSync(path.join(bin, 'subminer'), '#!/usr/bin/env bun\n// SubMiner launcher\n');
+  await refreshManagedCommandLineLauncher({ ...options, appVersion: '3' });
+  assert.match(fs.readFileSync(path.join(bin, 'subminer'), 'utf8'), /SubMiner managed launcher/);
+  const deferred = path.join(root, 'custom', 'subminer');
+  fs.mkdirSync(path.dirname(deferred));
+  fs.writeFileSync(deferred, '#!/usr/bin/env bun\n// SubMiner launcher\n');
+  const unreadable = path.join(root, 'unreadable');
+  fs.mkdirSync(unreadable);
+  const acknowledged = await refreshManagedCommandLineLauncher({
+    ...options,
+    appVersion: '3',
+    additionalLauncherPaths: [unreadable, deferred],
+  });
+  assert.ok(!acknowledged.includes(unreadable));
+  assert.ok(acknowledged.includes(deferred));
+  assert.match(fs.readFileSync(deferred, 'utf8'), /SubMiner managed launcher/);
+  fs.writeFileSync(path.join(bin, 'subminer'), '#!/bin/sh\necho standalone\n');
+  const customAcknowledged = await refreshManagedCommandLineLauncher({
+    ...options,
+    appVersion: '4',
+  });
+  assert.ok(customAcknowledged.includes(path.join(bin, 'subminer')));
+  assert.equal(fs.readFileSync(payload.versionPath, 'utf8'), '3');
+});
+
+test('Windows startup never rewrites the batch launcher that started the app', async () => {
+  const programs = 'C:\\Users\\tester\\AppData\\Local\\Programs\\SubMiner';
+  const installPath = 'C:\\Users\\tester\\AppData\\Local\\SubMiner\\bin\\subminer.cmd';
+  const writes: string[] = [];
+  let state: UpdateState = { pendingLauncherMigrationPath: installPath };
+  const store = createUpdateStateStore({
+    readState: async () => state,
+    writeState: async (nextState) => {
+      state = nextState;
+    },
+  });
+  const options = {
+    platform: 'win32' as const,
+    localAppData: 'C:\\Users\\tester\\AppData\\Local',
+    appVersion: '1.2.3',
+    appExePath: `${programs}\\SubMiner.exe`,
+    bundledBunPath: `${programs}\\resources\\bun\\bun.exe`,
+    launcherResourcePath: `${programs}\\resources\\launcher\\subminer.js`,
+    existsSync: (candidate: string) => !candidate.includes('licenses'),
+    accessSync: () => {},
+    mkdirSync: () => undefined,
+    copyFileSync: () => {},
+    readFileSync: () =>
+      managedLauncherContent({ platform: 'win32', appPath: 'D:\\Old\\SubMiner.exe' }),
+    writeFileSync: (candidate: string) => {
+      writes.push(candidate);
+    },
+  };
+
+  await takePendingLauncherMigrationPath(store, async (pendingPath) => {
+    const acknowledged = await refreshManagedCommandLineLauncher({
+      ...options,
+      additionalLauncherPaths: pendingPath ? [pendingPath] : [],
+      env: { SUBMINER_LAUNCHER_PATH: installPath.toUpperCase() },
+    });
+    return pendingPath !== undefined && acknowledged.includes(pendingPath);
+  });
+  assert.deepEqual(writes, []);
+  assert.equal(state.pendingLauncherMigrationPath, installPath);
+
+  await takePendingLauncherMigrationPath(store, async (pendingPath) => {
+    const acknowledged = await refreshManagedCommandLineLauncher({
+      ...options,
+      additionalLauncherPaths: pendingPath ? [pendingPath] : [],
+      env: {},
+    });
+    assert.equal(state.pendingLauncherMigrationPath, installPath);
+    return pendingPath !== undefined && acknowledged.includes(pendingPath);
+  });
+  assert.deepEqual(writes, [installPath]);
+  assert.equal(state.pendingLauncherMigrationPath, undefined);
+});
+
+test('Windows wrapper discovers the configured app and its versioned private runtime', () => {
+  const content = managedLauncherContent({
+    platform: 'win32',
+    appPath: 'C:\\Apps 100% !\\SubMiner.exe',
+  });
+  assert.ok(content.includes(MANAGED_LAUNCHER_MARKER));
+  assert.ok(content.includes('setlocal DisableDelayedExpansion'));
+  assert.ok(content.includes('set "SUBMINER_BINARY_PATH=C:\\Apps 100%% !\\SubMiner.exe"'));
+  assert.ok(content.includes('%SUBMINER_RESOURCES_PATH%\\launcher\\version'));
+  assert.ok(
+    content.includes(
+      'set "SUBMINER_BUN_PATH=%LOCALAPPDATA%\\SubMiner\\launcher-runtime\\%SUBMINER_APP_VERSION%\\bun.exe"',
+    ),
+  );
+  assert.ok(
+    content.includes('"%SUBMINER_BUN_PATH%" "%SUBMINER_RESOURCES_PATH%\\launcher\\subminer.js" %*'),
+  );
+  assert.ok(content.includes('exit /b %errorlevel%'));
+});
+
+test('Windows managed runtime path is absolute, versioned, and injectable', () => {
+  const paths = windowsManagedRuntimePaths({
+    platform: 'win32',
+    localAppData: 'D:\\Profiles\\テスト User\\AppData\\Local',
+    appVersion: '1.2.3-beta.4',
+  });
+  assert.equal(
+    paths.bunPath,
+    'D:\\Profiles\\テスト User\\AppData\\Local\\SubMiner\\launcher-runtime\\1.2.3-beta.4\\bun.exe',
+  );
+  assert.ok(path.win32.isAbsolute(paths.bunPath));
+  assert.throws(
+    () =>
+      windowsManagedRuntimePaths({
+        platform: 'win32',
+        localAppData: 'relative',
+        appVersion: '1.2.3',
+      }),
+    /must be an absolute Windows path/,
+  );
+  assert.throws(
+    () =>
+      windowsManagedRuntimePaths({
+        platform: 'win32',
+        localAppData: 'C:\\Users\\tester\\AppData\\Local',
+        appVersion: '1:2',
+      }),
+    /not a valid directory name/,
+  );
+});
+
+test('Windows managed launcher forwards arguments without a system Bun', async (t) => {
+  if (process.platform !== 'win32') return;
+  const root = workspace(t);
+  const appDirectory = path.join(root, 'Installed App');
+  const appPath = path.join(appDirectory, 'SubMiner.exe');
+  const launcherDirectory = path.join(appDirectory, 'resources', 'launcher');
+  const script = path.join(launcherDirectory, 'subminer.js');
+  fs.mkdirSync(launcherDirectory, { recursive: true });
+  fs.copyFileSync(process.execPath, appPath);
+  fs.writeFileSync(script, 'console.log(JSON.stringify(process.argv.slice(2)));');
+  fs.writeFileSync(path.join(launcherDirectory, 'version'), '1.0.0');
+  const options = {
+    platform: process.platform,
+    env: { ...process.env, PATH: '', LOCALAPPDATA: root },
+    bundledBunPath: process.execPath,
+    launcherResourcePath: script,
+    appExePath: appPath,
+    appVersion: '1.0.0',
+    localAppData: root,
+    getUserPath: () => '',
+    setUserPath: () => {},
+    broadcastEnvironmentChange: () => {},
+  };
+  const snapshot = await installLauncher(options);
+  assert.equal(snapshot.status, 'ready', snapshot.message ?? 'install failed');
+  const { getRunCommand } = await import('./command-line-launcher-deps');
+  const args = ['spaces here', 'a&b', 'p%TEMP%q', 'bang!z', 'say "hi"', '日本語'];
+  const result = await getRunCommand({})(snapshot.installPath!, args, { env: options.env });
+  assert.equal(result.exitCode, 0, result.stderr);
+  assert.deepEqual(JSON.parse(result.stdout), args);
+});
+
+test('Windows stages a new runtime version while the prior Bun executable is running', async (t) => {
+  if (process.platform !== 'win32') return;
+  const root = workspace(t);
+  const bundledDirectory = path.join(root, 'packaged', 'bun');
+  const bundledBunPath = path.join(bundledDirectory, 'bun.exe');
+  const launcherResourcePath = path.join(root, 'packaged', 'launcher', 'subminer');
+  fs.mkdirSync(path.join(bundledDirectory, 'licenses'), { recursive: true });
+  fs.mkdirSync(path.dirname(launcherResourcePath), { recursive: true });
+  fs.copyFileSync(process.execPath, bundledBunPath);
+  fs.writeFileSync(path.join(bundledDirectory, 'licenses', 'Bun-LICENSE.md'), 'license');
+  fs.writeFileSync(launcherResourcePath, 'console.log("launcher");');
+
+  const first = stageManagedLauncher({
+    platform: 'win32',
+    localAppData: root,
+    appVersion: '1.0.0',
+    bundledBunPath,
+    launcherResourcePath,
+  });
+  const running = spawn(first.bunPath, ['-e', 'setInterval(() => {}, 1000)']);
+  await new Promise<void>((resolve, reject) => {
+    running.once('spawn', resolve);
+    running.once('error', reject);
+  });
+
+  const expectedSecond = windowsManagedRuntimePaths({
+    platform: 'win32',
+    localAppData: root,
+    appVersion: '2.0.0',
+  });
+  try {
+    const second = stageManagedLauncher({
+      platform: 'win32',
+      localAppData: root,
+      appVersion: '2.0.0',
+      bundledBunPath,
+      launcherResourcePath,
+    });
+    assert.notEqual(second.bunPath, first.bunPath);
+    assert.ok(fs.existsSync(second.bunPath));
+    cleanupOldWindowsManagedRuntimes({
+      platform: 'win32',
+      localAppData: root,
+      appVersion: '2.0.0',
+    });
+    assert.ok(fs.existsSync(first.bunPath));
+    assert.ok(fs.existsSync(path.join(path.dirname(first.bunPath), 'licenses', 'Bun-LICENSE.md')));
+    assert.equal(
+      fs.readFileSync(
+        path.join(path.dirname(second.bunPath), 'licenses', 'Bun-LICENSE.md'),
+        'utf8',
+      ),
+      'license',
+    );
+  } finally {
+    if (running.exitCode === null) {
+      const exited = new Promise<void>((resolve) => running.once('exit', () => resolve()));
+      running.kill();
+      await exited;
+    }
+  }
+  cleanupOldWindowsManagedRuntimes({
+    platform: 'win32',
+    localAppData: root,
+    appVersion: '2.0.0',
+  });
+  assert.equal(fs.existsSync(path.dirname(first.bunPath)), false);
+  assert.ok(fs.existsSync(expectedSecond.bunPath));
+});
+
+test('Windows cleanup removes an obsolete runtime with no Bun executable', (t) => {
+  if (process.platform !== 'win32') return;
+  const root = workspace(t);
+  const current = windowsManagedRuntimePaths({
+    platform: 'win32',
+    localAppData: root,
+    appVersion: '2.0.0',
+  });
+  const obsolete = windowsManagedRuntimePaths({
+    platform: 'win32',
+    localAppData: root,
+    appVersion: '1.0.0',
+  });
+  fs.mkdirSync(path.join(path.dirname(obsolete.bunPath), 'licenses'), { recursive: true });
+  fs.writeFileSync(
+    path.join(path.dirname(obsolete.bunPath), 'licenses', 'Bun-LICENSE.md'),
+    'license',
+  );
+  fs.mkdirSync(path.dirname(current.bunPath), { recursive: true });
+
+  cleanupOldWindowsManagedRuntimes({
+    platform: 'win32',
+    localAppData: root,
+    appVersion: '2.0.0',
+  });
+
+  assert.equal(fs.existsSync(path.dirname(obsolete.bunPath)), false);
+  assert.ok(fs.existsSync(path.dirname(current.bunPath)));
+});
diff --git a/src/main/runtime/managed-launcher.ts b/src/main/runtime/managed-launcher.ts
new file mode 100644
index 00000000..0afa66d8
--- /dev/null
+++ b/src/main/runtime/managed-launcher.ts
@@ -0,0 +1,219 @@
+import { randomUUID } from 'node:crypto';
+import { execFileSync } from 'node:child_process';
+import { windowsLauncherBootstrapContent } from './windows-launcher-bootstrap';
+import { MANAGED_LAUNCHER_MARKER, posixLauncherBootstrapContent } from './posix-launcher-bootstrap';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import {
+  envOf,
+  existsSyncOf,
+  pathModuleFor,
+  platformOf,
+  type CommonOptions,
+  type WindowsPathOptions,
+} from './command-line-launcher-deps';
+
+export { MANAGED_LAUNCHER_MARKER, shellQuote } from './posix-launcher-bootstrap';
+
+export function isManagedLauncher(content: string): boolean {
+  const lines = content.split(/\r?\n/, 3);
+  return (
+    (lines[0] === '#!/bin/sh' && lines[1] === `# ${MANAGED_LAUNCHER_MARKER}`) ||
+    (lines[0] === '@echo off' && lines[1] === `rem ${MANAGED_LAUNCHER_MARKER}`)
+  );
+}
+
+export function managedLauncherContent(options: {
+  platform: NodeJS.Platform;
+  appPath: string;
+}): string {
+  if (options.platform === 'win32') return windowsLauncherBootstrapContent(options.appPath);
+  return posixLauncherBootstrapContent(options.appPath);
+}
+
+export function managedLauncherPaths(options: CommonOptions) {
+  const platform = platformOf(options);
+  const platformPath = pathModuleFor(platform);
+  const env = envOf(options);
+  const home = options.homeDir ?? os.homedir();
+  const dataHome = env.XDG_DATA_HOME;
+  const directory = platformPath.join(
+    dataHome && platformPath.isAbsolute(dataHome)
+      ? dataHome
+      : platformPath.join(home, '.local', 'share'),
+    'SubMiner',
+    'launcher',
+  );
+  return {
+    directory,
+    bunPath: platformPath.join(directory, 'bun'),
+    scriptPath: platformPath.join(directory, 'subminer'),
+    versionPath: platformPath.join(directory, 'version'),
+    fingerprintPath: platformPath.join(directory, 'fingerprint'),
+    appPathFile: platformPath.join(directory, 'app-path'),
+  };
+}
+
+function absoluteWindowsPath(candidate: string, label: string): string {
+  const normalized = path.win32.normalize(candidate);
+  if (!path.win32.isAbsolute(normalized)) {
+    throw new Error(`${label} must be an absolute Windows path: ${candidate}`);
+  }
+  return normalized;
+}
+
+export function windowsManagedRuntimePaths(options: CommonOptions & WindowsPathOptions) {
+  const env = envOf(options);
+  const userProfile = options.userProfile?.trim() || env.USERPROFILE?.trim() || os.homedir();
+  const localAppData =
+    options.localAppData?.trim() ||
+    env.LOCALAPPDATA?.trim() ||
+    path.win32.join(userProfile, 'AppData', 'Local');
+  const rootDirectory = path.win32.join(
+    absoluteWindowsPath(localAppData, 'Windows local app data directory'),
+    'SubMiner',
+    'launcher-runtime',
+  );
+  const version = options.appVersion?.trim() || 'development';
+  if (
+    version === '.' ||
+    version === '..' ||
+    /[<>:"/\\|?*\u0000-\u001f]/.test(version) ||
+    /[ .]$/.test(version)
+  ) {
+    throw new Error(`SubMiner version is not a valid directory name: ${version}`);
+  }
+  const directory = path.win32.join(rootDirectory, version);
+  return {
+    rootDirectory,
+    directory,
+    bunPath: path.win32.join(directory, 'bun.exe'),
+  };
+}
+
+export function cleanupOldWindowsManagedRuntimes(
+  options: CommonOptions & WindowsPathOptions,
+): void {
+  const paths = windowsManagedRuntimePaths(options);
+  try {
+    for (const entry of fs.readdirSync(paths.rootDirectory, { withFileTypes: true })) {
+      if (!entry.isDirectory() || entry.name === path.win32.basename(paths.directory)) continue;
+      const oldDirectory = path.win32.join(paths.rootDirectory, entry.name);
+      try {
+        fs.rmSync(path.win32.join(oldDirectory, 'bun.exe'), { force: true });
+      } catch {
+        continue;
+      }
+      try {
+        fs.rmSync(oldDirectory, { recursive: true, force: true });
+      } catch {
+        // Cleanup is best-effort after proving the old runtime is not locked.
+      }
+    }
+  } catch {
+    // The runtime root can be absent before the first managed launcher install.
+  }
+}
+
+function stageWindowsManagedRuntime(
+  options: CommonOptions &
+    WindowsPathOptions & {
+      bundledBunPath: string;
+      force?: boolean;
+    },
+): string {
+  const paths = windowsManagedRuntimePaths(options);
+  const exists = existsSyncOf(options);
+  const mkdir = options.mkdirSync ?? fs.mkdirSync;
+  const copy = options.copyFileSync ?? fs.copyFileSync;
+
+  mkdir(paths.directory, { recursive: true });
+  if (options.force || !exists(paths.bunPath)) {
+    const stagingPath = `${paths.bunPath}.${randomUUID()}.tmp`;
+    try {
+      copy(options.bundledBunPath, stagingPath);
+      if (exists(paths.bunPath)) fs.rmSync(paths.bunPath, { force: true });
+      fs.renameSync(stagingPath, paths.bunPath);
+    } finally {
+      fs.rmSync(stagingPath, { force: true });
+    }
+  }
+
+  const packagedLicenses = path.join(path.dirname(options.bundledBunPath), 'licenses');
+  const cachedLicenses = path.win32.join(paths.directory, 'licenses');
+  if (exists(packagedLicenses) && (options.force || !exists(cachedLicenses))) {
+    fs.cpSync(packagedLicenses, cachedLicenses, { recursive: true, force: true });
+  }
+
+  return paths.bunPath;
+}
+
+// Keep ephemeral or replaceable executables outside the installed app. Linux
+// also copies the script because AppImage resources disappear when the app exits.
+export function stageManagedLauncher(
+  options: CommonOptions &
+    WindowsPathOptions & {
+      bundledBunPath: string;
+      launcherResourcePath: string;
+      force?: boolean;
+    },
+) {
+  const platform = platformOf(options);
+  if (platform === 'win32') {
+    return {
+      bunPath: stageWindowsManagedRuntime(options),
+      scriptPath: options.launcherResourcePath,
+    };
+  }
+  if (platform !== 'linux') {
+    return { bunPath: options.bundledBunPath, scriptPath: options.launcherResourcePath };
+  }
+  const paths = managedLauncherPaths(options);
+  const exists = existsSyncOf(options);
+  const read = options.readFileSync ?? fs.readFileSync;
+  const write = options.writeFileSync ?? fs.writeFileSync;
+  const copy = options.copyFileSync ?? fs.copyFileSync;
+  const mkdir = options.mkdirSync ?? fs.mkdirSync;
+  const chmod = options.chmodSync ?? fs.chmodSync;
+  const version = options.appVersion ?? 'development';
+  const appPath = envOf(options).APPIMAGE ?? options.appExePath;
+  const fingerprint = appPath
+    ? execFileSync('stat', ['-Lc', '%d:%i:%s:%y:%z', '--', appPath], {
+        encoding: 'utf8',
+        env: { ...envOf(options), PATH: `/usr/bin:/bin:${envOf(options).PATH ?? ''}` },
+      }).trim()
+    : '';
+  if (
+    !options.force &&
+    exists(paths.versionPath) &&
+    read(paths.versionPath, 'utf8') === version &&
+    exists(paths.fingerprintPath) &&
+    read(paths.fingerprintPath, 'utf8') === `${fingerprint}\n` &&
+    exists(paths.appPathFile) &&
+    read(paths.appPathFile, 'utf8') === `${appPath ?? ''}\n` &&
+    exists(paths.bunPath) &&
+    exists(paths.scriptPath)
+  )
+    return paths;
+
+  mkdir(paths.directory, { recursive: true });
+  const staging = fs.mkdtempSync(path.join(paths.directory, '.stage-'));
+  try {
+    copy(options.bundledBunPath, path.join(staging, 'bun'));
+    chmod(path.join(staging, 'bun'), 0o755);
+    copy(options.launcherResourcePath, path.join(staging, 'subminer'));
+    const notices = path.join(path.dirname(options.bundledBunPath), 'licenses');
+    if (exists(notices))
+      fs.cpSync(notices, path.join(paths.directory, 'licenses'), { recursive: true });
+    write(path.join(staging, 'version'), version);
+    write(path.join(staging, 'app-path'), `${appPath ?? ''}\n`);
+    write(path.join(staging, 'fingerprint'), `${fingerprint}\n`);
+    for (const name of ['bun', 'subminer', 'version', 'app-path', 'fingerprint']) {
+      fs.renameSync(path.join(staging, name), path.join(paths.directory, name));
+    }
+  } finally {
+    fs.rmSync(staging, { recursive: true, force: true });
+  }
+  return paths;
+}
diff --git a/src/main/runtime/media-timing-review-frame.test.ts b/src/main/runtime/media-timing-review-frame.test.ts
new file mode 100644
index 00000000..9d7a9ddf
--- /dev/null
+++ b/src/main/runtime/media-timing-review-frame.test.ts
@@ -0,0 +1,161 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import type { MediaTimingReviewOpenPayload } from '../../types/anki';
+import type { MediaTimingFrameOptions } from '../../core/services/media-timing-frame';
+import {
+  createMediaTimingReviewRuntime,
+  type MediaTimingReviewRuntimeDeps,
+} from './media-timing-review';
+
+async function start(
+  options: Partial<MediaTimingReviewRuntimeDeps> = {},
+  screenshotEnabled = true,
+) {
+  let opened!: (payload: MediaTimingReviewOpenPayload) => void;
+  const payloadPromise = new Promise<MediaTimingReviewOpenPayload>((resolve) => {
+    opened = resolve;
+  });
+  const frames: MediaTimingFrameOptions[] = [];
+  const runtime = createMediaTimingReviewRuntime({
+    getMpvClient: () => ({
+      connected: true,
+      currentVideoPath: '/video.mkv',
+      send: () => {},
+      requestProperty: async (name) => (name === 'duration' ? 100 : true),
+    }),
+    getCurrentMediaPath: () => '/video.mkv',
+    getMpvExecutablePath: () => '',
+    createPreviewSession: () => ({
+      start: async () => {},
+      play: async () => {},
+      stop: async () => {},
+      onPlaybackEnded: () => {},
+      dispose: () => {},
+    }),
+    generateWaveform: async () => [0, 1],
+    resolveVideoSource: async () => ({ path: '/video.mkv' }),
+    generateFrame: async (options) => {
+      frames.push(options);
+      return { dataUrl: 'data:image/jpeg;base64,AA==', timestamp: options.timestamp };
+    },
+    openModal: async (payload) => {
+      opened(payload);
+      return true;
+    },
+    showStatus: () => {},
+    ...options,
+  });
+  const decision = runtime.requestReview({
+    kind: 'word',
+    text: '字幕',
+    startTime: 10,
+    endTime: 12,
+    audioPadding: 0,
+    maxMediaDuration: 30,
+    screenshotEnabled,
+  });
+  return { runtime, decision, payload: await payloadPromise, frames };
+}
+
+test('review accepts a screenshot outside the audio range and validates media bounds', async () => {
+  const { runtime, decision, payload, frames } = await start();
+  for (const timestamp of [NaN, Infinity, -1, 100]) {
+    assert.equal((await runtime.getFrame({ reviewId: payload.reviewId, timestamp })).ok, false);
+    assert.equal(
+      runtime.resolveReview({
+        reviewId: payload.reviewId,
+        decision: { action: 'confirm', startTime: 10, endTime: 11, screenshotTime: timestamp },
+      }).ok,
+      false,
+    );
+  }
+  assert.equal((await runtime.getFrame({ reviewId: payload.reviewId, timestamp: 13 })).ok, true);
+  assert.equal(frames[0]?.timestamp, 13);
+  assert.equal(
+    runtime.resolveReview({
+      reviewId: payload.reviewId,
+      decision: { action: 'confirm', startTime: 10, endTime: 11, screenshotTime: 13 },
+    }).ok,
+    true,
+  );
+  assert.deepEqual(await decision, {
+    action: 'confirm',
+    startTime: 10,
+    endTime: 11,
+    screenshotTime: 13,
+  });
+});
+
+test('screenshot preview reuses the remote audio window and its absolute timestamps', async () => {
+  let downloads = 0;
+  const remote = 'https://example.test/video';
+  const { runtime, payload, decision, frames } = await start({
+    resolveMediaSource: async () => ({ path: remote }),
+    resolveVideoSource: async () => ({ path: remote }),
+    acquireMediaWindow: async () => {
+      downloads += 1;
+      return {
+        path: '/window.mkv',
+        sourcePath: remote,
+        startTime: 7,
+        endTime: 15,
+        audioStreamIndex: null,
+        media: { path: '/window.mkv', absoluteTimestamps: true },
+      };
+    },
+  });
+  await runtime.getWaveform({ reviewId: payload.reviewId, startTime: 8, endTime: 14 });
+  assert.equal((await runtime.getFrame({ reviewId: payload.reviewId, timestamp: 11 })).ok, true);
+  assert.equal(downloads, 1);
+  assert.deepEqual(frames[0]?.media, { path: '/window.mkv', absoluteTimestamps: true });
+  await runtime.dispose();
+  await decision;
+});
+
+test('split video streams never read an audio-only cache as a video source', async () => {
+  const video = {
+    path: 'https://example.test/video',
+    inputOptions: { headers: { 'X-Test': 'value' } },
+  };
+  const { runtime, payload, decision, frames } = await start({
+    resolveMediaSource: async () => ({ path: 'https://example.test/audio' }),
+    resolveVideoSource: async () => video,
+  });
+  await runtime.getFrame({ reviewId: payload.reviewId, timestamp: 11 });
+  assert.deepEqual(frames[0]?.media, video);
+  await runtime.dispose();
+  await decision;
+});
+
+test('disabled screenshots and missing video inputs do not trigger extraction', async () => {
+  for (const [enabled, options] of [
+    [false, {}],
+    [true, { resolveVideoSource: async () => null }],
+  ] as const) {
+    const { runtime, payload, decision, frames } = await start(options, enabled);
+    assert.equal((await runtime.getFrame({ reviewId: payload.reviewId, timestamp: 11 })).ok, false);
+    assert.equal(frames.length, 0);
+    await runtime.dispose();
+    await decision;
+  }
+});
+
+test('closing a review invalidates in-flight frame results and clears the frame index', async () => {
+  let finish!: (value: { dataUrl: string; timestamp: number }) => void;
+  let clearCount = 0;
+  const { runtime, payload, decision } = await start({
+    generateFrame: () =>
+      new Promise((resolve) => {
+        finish = resolve;
+      }),
+    clearFrameCache: () => {
+      clearCount += 1;
+    },
+  });
+  const frame = runtime.getFrame({ reviewId: payload.reviewId, timestamp: 11 });
+  await runtime.dispose();
+  finish({ dataUrl: 'data:image/jpeg;base64,AA==', timestamp: 11 });
+  assert.equal((await frame).stale, true);
+  await decision;
+  assert.equal(clearCount, 1);
+});
diff --git a/src/main/runtime/media-timing-review-open.ts b/src/main/runtime/media-timing-review-open.ts
new file mode 100644
index 00000000..fa6655ea
--- /dev/null
+++ b/src/main/runtime/media-timing-review-open.ts
@@ -0,0 +1,44 @@
+import { IPC_CHANNELS, type OverlayHostedModal } from '../../shared/ipc/contracts';
+import type { MediaTimingReviewOpenPayload } from '../../types/anki';
+import { openOverlayHostedModal, retryOverlayModalOpen } from './overlay-hosted-modal-open';
+
+const MODAL: OverlayHostedModal = 'media-timing-review';
+
+export async function openMediaTimingReviewModal(
+  deps: {
+    ensureOverlayStartupPrereqs: () => void;
+    ensureOverlayWindowsReadyForVisibilityActions: () => void;
+    sendToActiveOverlayWindow: (
+      channel: string,
+      payload?: unknown,
+      runtimeOptions?: {
+        restoreOnModalClose?: OverlayHostedModal;
+        preferModalWindow?: boolean;
+      },
+    ) => boolean;
+    waitForModalOpen: (modal: OverlayHostedModal, timeoutMs: number) => Promise<boolean>;
+    logWarn: (message: string) => void;
+  },
+  payload: MediaTimingReviewOpenPayload,
+  signal?: AbortSignal,
+): Promise<boolean> {
+  return await retryOverlayModalOpen(
+    { waitForModalOpen: deps.waitForModalOpen, logWarn: deps.logWarn },
+    {
+      modal: MODAL,
+      signal,
+      // The review renderer regularly needs more than the 1.5 s the other modals allow; a
+      // premature retry re-sends the payload and reloads the waveform for nothing.
+      timeoutMs: 4_000,
+      retryWarning:
+        'Media timing review did not acknowledge modal open; retrying the dedicated modal window.',
+      sendOpen: () =>
+        openOverlayHostedModal(deps, {
+          channel: IPC_CHANNELS.event.mediaTimingReviewOpen,
+          modal: MODAL,
+          payload,
+          preferModalWindow: true,
+        }),
+    },
+  );
+}
diff --git a/src/main/runtime/media-timing-review.test.ts b/src/main/runtime/media-timing-review.test.ts
new file mode 100644
index 00000000..85718b14
--- /dev/null
+++ b/src/main/runtime/media-timing-review.test.ts
@@ -0,0 +1,1074 @@
+import assert from 'node:assert/strict';
+import { describe, test } from 'node:test';
+import type { MediaTimingReviewOpenPayload } from '../../types/anki';
+import type { SpeechWaveformOptions } from '../../core/services/media-timing-waveform';
+import type {
+  RemoteMediaWindow,
+  RemoteMediaWindowRange,
+  RemoteMediaWindowSource,
+} from '../../core/services/remote-media-window-cache';
+import type { MediaTimingPreviewSession } from '../../core/services/media-timing-preview';
+import { openMediaTimingReviewModal } from './media-timing-review-open';
+
+type MediaTimingPreviewSessionLike = Pick<MediaTimingPreviewSession, 'start'>;
+import {
+  buildMediaTimingReviewPayload,
+  collectMediaTimingContextLines,
+  createMediaTimingReviewRuntime,
+} from './media-timing-review';
+
+function createDeferred<T>() {
+  let settle: ((value: T) => void) | null = null;
+  const promise = new Promise<T>((resolve) => {
+    settle = resolve;
+  });
+  return {
+    promise,
+    resolve(value: T): void {
+      if (!settle) throw new Error('deferred promise is unavailable');
+      settle(value);
+    },
+  };
+}
+
+describe('buildMediaTimingReviewPayload', () => {
+  test('starts from the padded range and leaves two seconds to drag on each side', () => {
+    const payload = buildMediaTimingReviewPayload(
+      {
+        kind: 'sentence',
+        text: '字幕',
+        startTime: 10,
+        endTime: 12,
+        audioPadding: 0.5,
+        maxMediaDuration: 30,
+      },
+      { reviewId: 'review-1', mediaDuration: 100 },
+    );
+
+    assert.equal(payload.selectionStartTime, 9.5);
+    assert.equal(payload.selectionEndTime, 12.5);
+    assert.equal(payload.timelineStartTime, 7.5);
+    assert.equal(payload.timelineEndTime, 14.5);
+  });
+
+  test('clamps the padded selection and timeline to media bounds', () => {
+    const payload = buildMediaTimingReviewPayload(
+      {
+        kind: 'word',
+        text: '字幕',
+        startTime: 0.2,
+        endTime: 9.8,
+        audioPadding: 1,
+        maxMediaDuration: 30,
+      },
+      { reviewId: 'review-2', mediaDuration: 10 },
+    );
+
+    assert.equal(payload.selectionStartTime, 0);
+    assert.equal(payload.selectionEndTime, 10);
+    assert.equal(payload.timelineStartTime, 0);
+    assert.equal(payload.timelineEndTime, 10);
+  });
+
+  test('keeps an uncapped selection when max media duration is disabled', () => {
+    const payload = buildMediaTimingReviewPayload(
+      {
+        kind: 'sentence',
+        text: '字幕',
+        startTime: 10,
+        endTime: 55,
+        audioPadding: 1,
+        maxMediaDuration: 0,
+      },
+      { reviewId: 'review-unlimited', mediaDuration: 100 },
+    );
+
+    assert.equal(payload.selectionStartTime, 9);
+    assert.equal(payload.selectionEndTime, 56);
+    assert.equal(payload.maxMediaDuration, 0);
+  });
+});
+
+async function startActiveMediaTimingReview(
+  options: {
+    maxMediaDuration?: number;
+    decisionTimeoutMs?: number;
+    generateWaveform?: () => Promise<number[]>;
+    play?: () => Promise<void>;
+  } = {},
+) {
+  const previewCalls: Array<[number, number]> = [];
+  let publishPayload!: (payload: MediaTimingReviewOpenPayload) => void;
+  const openedPayload = new Promise<MediaTimingReviewOpenPayload>((resolve) => {
+    publishPayload = resolve;
+  });
+  const runtime = createMediaTimingReviewRuntime({
+    getMpvClient: () => ({
+      connected: true,
+      currentVideoPath: '/video/show.mkv',
+      requestProperty: async (name) => (name === 'duration' ? 100 : name === 'pause' ? true : null),
+      send: () => undefined,
+    }),
+    getCurrentMediaPath: () => '/video/show.mkv',
+    getMpvExecutablePath: () => 'mpv',
+    generateWaveform: options.generateWaveform ?? (async () => []),
+    decisionTimeoutMs: options.decisionTimeoutMs,
+    createPreviewSession: () => ({
+      start: async () => undefined,
+      play: async (startTime, endTime) => {
+        previewCalls.push([startTime, endTime]);
+        await options.play?.();
+      },
+      stop: async () => undefined,
+      onPlaybackEnded: () => undefined,
+      dispose: () => undefined,
+    }),
+    openModal: async (payload) => {
+      publishPayload(payload);
+      return true;
+    },
+    showStatus: () => undefined,
+  });
+  const pendingDecision = runtime.requestReview({
+    kind: 'sentence',
+    text: '字幕',
+    startTime: 10,
+    endTime: 12,
+    audioPadding: 0,
+    maxMediaDuration: options.maxMediaDuration ?? 30,
+  });
+
+  return { runtime, payload: await openedPayload, pendingDecision, previewCalls };
+}
+
+test('media timing review pauses playback, resolves exact timing, and restores playing state', async () => {
+  const commands: Array<Array<string | number>> = [];
+  const previewCalls: Array<[number, number]> = [];
+  let runtime: ReturnType<typeof createMediaTimingReviewRuntime>;
+  runtime = createMediaTimingReviewRuntime({
+    getMpvClient: () => ({
+      connected: true,
+      currentVideoPath: '/video/show.mkv',
+      requestProperty: async (name) =>
+        ({ pause: false, duration: 100, aid: 2, volume: 60 })[
+          name as 'pause' | 'duration' | 'aid' | 'volume'
+        ],
+      send: ({ command }) => commands.push(command),
+    }),
+    getCurrentMediaPath: () => '/video/show.mkv',
+    getMpvExecutablePath: () => 'mpv',
+    generateWaveform: async () => [],
+    createPreviewSession: () => ({
+      start: async () => undefined,
+      play: async (startTime, endTime) => {
+        previewCalls.push([startTime, endTime]);
+      },
+      stop: async () => undefined,
+      onPlaybackEnded: () => undefined,
+      dispose: () => undefined,
+    }),
+    openModal: async (payload) => {
+      queueMicrotask(() => {
+        void runtime
+          .previewRange({
+            reviewId: payload.reviewId,
+            startTime: 9.5,
+            endTime: 12.5,
+          })
+          .then(() => {
+            runtime.resolveReview({
+              reviewId: payload.reviewId,
+              decision: { action: 'confirm', startTime: 9.5, endTime: 12.5 },
+            });
+          });
+      });
+      return true;
+    },
+    showStatus: () => undefined,
+  });
+
+  const decision = await runtime.requestReview({
+    kind: 'word',
+    text: '字幕',
+    startTime: 10,
+    endTime: 12,
+    noteId: 42,
+    audioPadding: 0.5,
+    maxMediaDuration: 30,
+  });
+
+  assert.deepEqual(decision, { action: 'confirm', startTime: 9.5, endTime: 12.5 });
+  assert.deepEqual(commands, [
+    ['set_property', 'pause', 'yes'],
+    ['set_property', 'pause', 'no'],
+  ]);
+  assert.deepEqual(previewCalls, [[9.5, 12.5]]);
+});
+
+test('media timing review analyzes the visible range on the selected audio stream', async () => {
+  const waveformCalls: SpeechWaveformOptions[] = [];
+  let runtime: ReturnType<typeof createMediaTimingReviewRuntime>;
+  runtime = createMediaTimingReviewRuntime({
+    getMpvClient: () => ({
+      connected: true,
+      currentVideoPath: '/video/show.mkv',
+      currentAudioStreamIndex: 4,
+      requestProperty: async (name) => (name === 'duration' ? 100 : name === 'pause' ? true : null),
+      send: () => undefined,
+    }),
+    getCurrentMediaPath: () => '/video/show.mkv',
+    getMpvExecutablePath: () => 'mpv',
+    generateWaveform: async (options) => {
+      waveformCalls.push(options);
+      return [0.1, 0.8, 0.2];
+    },
+    createPreviewSession: () => ({
+      start: async () => undefined,
+      play: async () => undefined,
+      stop: async () => undefined,
+      onPlaybackEnded: () => undefined,
+      dispose: () => undefined,
+    }),
+    openModal: async (payload) => {
+      const waveform = await runtime.getWaveform({
+        reviewId: payload.reviewId,
+        startTime: payload.timelineStartTime,
+        endTime: payload.timelineEndTime,
+      });
+      assert.deepEqual(waveform, { ok: true, peaks: [0.1, 0.8, 0.2] });
+      runtime.resolveReview({
+        reviewId: payload.reviewId,
+        decision: { action: 'use-original' },
+      });
+      return true;
+    },
+    showStatus: () => undefined,
+  });
+
+  await runtime.requestReview({
+    kind: 'sentence',
+    text: '字幕',
+    startTime: 10,
+    endTime: 12,
+    audioPadding: 0.5,
+    maxMediaDuration: 30,
+  });
+
+  assert.deepEqual(waveformCalls, [
+    {
+      mediaPath: '/video/show.mkv',
+      startTime: 7.5,
+      endTime: 14.5,
+      audioStreamIndex: 4,
+    },
+  ]);
+});
+
+const REMOTE_STREAM_URL = 'https://jellyfin.example/Videos/abc/stream?static=true';
+
+function createWindowStub(options: { fail?: boolean } = {}) {
+  const calls: Array<{ source: RemoteMediaWindowSource; range: RemoteMediaWindowRange }> = [];
+  const acquireMediaWindow = async (
+    source: RemoteMediaWindowSource,
+    range: RemoteMediaWindowRange,
+  ): Promise<RemoteMediaWindow> => {
+    calls.push({ source, range });
+    if (options.fail) throw new Error('offline');
+    const windowPath = `/tmp/window-${range.startTime}-${range.endTime}.mkv`;
+    return {
+      path: windowPath,
+      startTime: range.startTime,
+      endTime: range.endTime,
+      sourcePath: source.path,
+      audioStreamIndex: source.audioStreamIndex ?? null,
+      media: {
+        path: windowPath,
+        source: 'remote-window',
+        singleResolvedStream: true,
+        absoluteTimestamps: true,
+      },
+    };
+  };
+  return { calls, acquireMediaWindow };
+}
+
+function createRemoteReviewRuntime(options: {
+  windowStub: ReturnType<typeof createWindowStub>;
+  waveformCalls: SpeechWaveformOptions[];
+  previewStarts: Array<Parameters<MediaTimingPreviewSessionLike['start']>[0]>;
+  previewPlays: Array<[string, number, number]>;
+  disposed: string[];
+  openModal: (
+    runtime: ReturnType<typeof createMediaTimingReviewRuntime>,
+    payload: MediaTimingReviewOpenPayload,
+  ) => Promise<void>;
+}) {
+  let runtime!: ReturnType<typeof createMediaTimingReviewRuntime>;
+  runtime = createMediaTimingReviewRuntime({
+    getMpvClient: () => ({
+      connected: true,
+      currentVideoPath: REMOTE_STREAM_URL,
+      currentAudioStreamIndex: 2,
+      requestProperty: async (name) =>
+        ({ pause: true, duration: 100, aid: 3, volume: 60 })[
+          name as 'pause' | 'duration' | 'aid' | 'volume'
+        ] ?? null,
+      send: () => undefined,
+    }),
+    getCurrentMediaPath: () => REMOTE_STREAM_URL,
+    getMpvExecutablePath: () => 'mpv',
+    resolveMediaSource: async () => ({
+      path: REMOTE_STREAM_URL,
+      inputOptions: { reconnect: true },
+    }),
+    acquireMediaWindow: options.windowStub.acquireMediaWindow,
+    generateWaveform: async (waveformOptions) => {
+      options.waveformCalls.push(waveformOptions);
+      return [0.1, 0.8, 0.2];
+    },
+    createPreviewSession: () => {
+      let mediaPath = '';
+      return {
+        start: async (startOptions) => {
+          mediaPath = startOptions.mediaPath;
+          options.previewStarts.push(startOptions);
+        },
+        play: async (startTime, endTime) => {
+          options.previewPlays.push([mediaPath, startTime, endTime]);
+        },
+        stop: async () => undefined,
+        onPlaybackEnded: () => undefined,
+        dispose: () => {
+          options.disposed.push(mediaPath);
+        },
+      };
+    },
+    openModal: async (payload) => {
+      await options.openModal(runtime, payload);
+      return true;
+    },
+    showStatus: () => undefined,
+  });
+  return runtime;
+}
+
+test('media timing review downloads one window of a remote stream for the waveform and preview', async () => {
+  const windowStub = createWindowStub();
+  const waveformCalls: SpeechWaveformOptions[] = [];
+  const previewStarts: Array<Parameters<MediaTimingPreviewSessionLike['start']>[0]> = [];
+  const previewPlays: Array<[string, number, number]> = [];
+  const disposed: string[] = [];
+  const runtime = createRemoteReviewRuntime({
+    windowStub,
+    waveformCalls,
+    previewStarts,
+    previewPlays,
+    disposed,
+    openModal: async (active, payload) => {
+      const waveform = await active.getWaveform({
+        reviewId: payload.reviewId,
+        startTime: payload.timelineStartTime,
+        endTime: payload.timelineEndTime,
+      });
+      assert.deepEqual(waveform, { ok: true, peaks: [0.1, 0.8, 0.2] });
+      assert.deepEqual(
+        await active.previewRange({ reviewId: payload.reviewId, startTime: 9.5, endTime: 12.5 }),
+        { ok: true },
+      );
+      active.resolveReview({
+        reviewId: payload.reviewId,
+        decision: { action: 'confirm', startTime: 9.5, endTime: 12.5 },
+      });
+    },
+  });
+
+  const decision = await runtime.requestReview({
+    kind: 'word',
+    text: '字幕',
+    startTime: 10,
+    endTime: 12,
+    audioPadding: 0.5,
+    maxMediaDuration: 30,
+  });
+
+  assert.deepEqual(decision, { action: 'confirm', startTime: 9.5, endTime: 12.5 });
+  assert.deepEqual(windowStub.calls, [
+    {
+      source: { path: REMOTE_STREAM_URL, inputOptions: { reconnect: true }, audioStreamIndex: 2 },
+      range: { startTime: 7.5, endTime: 14.5 },
+    },
+  ]);
+  assert.deepEqual(waveformCalls, [
+    {
+      mediaPath: {
+        path: '/tmp/window-7.5-14.5.mkv',
+        source: 'remote-window',
+        singleResolvedStream: true,
+        absoluteTimestamps: true,
+      },
+      startTime: 7.5,
+      endTime: 14.5,
+    },
+  ]);
+  assert.deepEqual(previewStarts, [
+    {
+      mediaPath: '/tmp/window-7.5-14.5.mkv',
+      executablePath: 'mpv',
+      volume: 60,
+      absoluteTimestamps: true,
+    },
+  ]);
+  assert.deepEqual(previewPlays, [['/tmp/window-7.5-14.5.mkv', 9.5, 12.5]]);
+  assert.deepEqual(disposed, ['/tmp/window-7.5-14.5.mkv']);
+});
+
+test('media timing review restarts the preview on a wider window when the timeline grows', async () => {
+  const windowStub = createWindowStub();
+  const waveformCalls: SpeechWaveformOptions[] = [];
+  const previewStarts: Array<Parameters<MediaTimingPreviewSessionLike['start']>[0]> = [];
+  const previewPlays: Array<[string, number, number]> = [];
+  const disposed: string[] = [];
+  const runtime = createRemoteReviewRuntime({
+    windowStub,
+    waveformCalls,
+    previewStarts,
+    previewPlays,
+    disposed,
+    openModal: async (active, payload) => {
+      await active.previewRange({ reviewId: payload.reviewId, startTime: 9.5, endTime: 12.5 });
+      // The user revealed two more seconds before the clip.
+      await active.getWaveform({ reviewId: payload.reviewId, startTime: 5.5, endTime: 14.5 });
+      await active.previewRange({ reviewId: payload.reviewId, startTime: 6, endTime: 12.5 });
+      active.resolveReview({ reviewId: payload.reviewId, decision: { action: 'use-original' } });
+    },
+  });
+
+  await runtime.requestReview({
+    kind: 'sentence',
+    text: '字幕',
+    startTime: 10,
+    endTime: 12,
+    audioPadding: 0.5,
+    maxMediaDuration: 30,
+  });
+
+  assert.deepEqual(
+    windowStub.calls.map((call) => call.range),
+    [
+      { startTime: 7.5, endTime: 14.5 },
+      { startTime: 5.5, endTime: 14.5 },
+    ],
+  );
+  assert.deepEqual(
+    previewStarts.map((start) => start.mediaPath),
+    ['/tmp/window-7.5-14.5.mkv', '/tmp/window-5.5-14.5.mkv'],
+  );
+  assert.deepEqual(previewPlays, [
+    ['/tmp/window-7.5-14.5.mkv', 9.5, 12.5],
+    ['/tmp/window-5.5-14.5.mkv', 6, 12.5],
+  ]);
+  assert.deepEqual(disposed, ['/tmp/window-7.5-14.5.mkv', '/tmp/window-5.5-14.5.mkv']);
+  assert.equal(waveformCalls[0]?.startTime, 5.5);
+});
+
+test('media timing review falls back to the remote stream after one failed window download', async () => {
+  const windowStub = createWindowStub({ fail: true });
+  const waveformCalls: SpeechWaveformOptions[] = [];
+  const previewStarts: Array<Parameters<MediaTimingPreviewSessionLike['start']>[0]> = [];
+  const previewPlays: Array<[string, number, number]> = [];
+  const disposed: string[] = [];
+  const runtime = createRemoteReviewRuntime({
+    windowStub,
+    waveformCalls,
+    previewStarts,
+    previewPlays,
+    disposed,
+    openModal: async (active, payload) => {
+      await active.getWaveform({
+        reviewId: payload.reviewId,
+        startTime: payload.timelineStartTime,
+        endTime: payload.timelineEndTime,
+      });
+      await active.previewRange({ reviewId: payload.reviewId, startTime: 9.5, endTime: 12.5 });
+      active.resolveReview({ reviewId: payload.reviewId, decision: { action: 'use-original' } });
+    },
+  });
+
+  await runtime.requestReview({
+    kind: 'word',
+    text: '字幕',
+    startTime: 10,
+    endTime: 12,
+    audioPadding: 0.5,
+    maxMediaDuration: 30,
+  });
+
+  assert.equal(windowStub.calls.length, 1);
+  assert.deepEqual(waveformCalls, [
+    {
+      mediaPath: { path: REMOTE_STREAM_URL, inputOptions: { reconnect: true } },
+      startTime: 7.5,
+      endTime: 14.5,
+      audioStreamIndex: 2,
+    },
+  ]);
+  assert.deepEqual(previewStarts, [
+    { mediaPath: REMOTE_STREAM_URL, executablePath: 'mpv', volume: 60, audioTrackId: 3 },
+  ]);
+  assert.deepEqual(previewPlays, [[REMOTE_STREAM_URL, 9.5, 12.5]]);
+});
+
+test('media timing review never downloads windows for local media', async () => {
+  const windowStub = createWindowStub();
+  let runtime!: ReturnType<typeof createMediaTimingReviewRuntime>;
+  runtime = createMediaTimingReviewRuntime({
+    getMpvClient: () => ({
+      connected: true,
+      currentVideoPath: '/video/show.mkv',
+      requestProperty: async (name) => (name === 'duration' ? 100 : name === 'pause' ? true : null),
+      send: () => undefined,
+    }),
+    getCurrentMediaPath: () => '/video/show.mkv',
+    getMpvExecutablePath: () => 'mpv',
+    resolveMediaSource: async () => ({ path: '/video/show.mkv' }),
+    acquireMediaWindow: windowStub.acquireMediaWindow,
+    generateWaveform: async () => [0.1, 0.8, 0.2],
+    createPreviewSession: () => ({
+      start: async () => undefined,
+      play: async () => undefined,
+      stop: async () => undefined,
+      onPlaybackEnded: () => undefined,
+      dispose: () => undefined,
+    }),
+    openModal: async (payload) => {
+      await runtime.getWaveform({ reviewId: payload.reviewId, startTime: 7.5, endTime: 14.5 });
+      runtime.resolveReview({ reviewId: payload.reviewId, decision: { action: 'use-original' } });
+      return true;
+    },
+    showStatus: () => undefined,
+  });
+
+  await runtime.requestReview({
+    kind: 'sentence',
+    text: '字幕',
+    startTime: 10,
+    endTime: 12,
+    audioPadding: 0.5,
+    maxMediaDuration: 30,
+  });
+
+  assert.equal(windowStub.calls.length, 0);
+});
+
+test('media timing review rejects stale and out-of-range actions before allowing discard', async () => {
+  const { runtime, payload, pendingDecision, previewCalls } = await startActiveMediaTimingReview({
+    maxMediaDuration: 3,
+  });
+
+  assert.deepEqual(
+    await runtime.previewRange({ reviewId: 'stale-review', startTime: 10, endTime: 12 }),
+    { ok: false, stale: true, message: 'This timing review is no longer active.' },
+  );
+  assert.deepEqual(
+    runtime.resolveReview({
+      reviewId: 'stale-review',
+      decision: { action: 'confirm', startTime: 10, endTime: 12 },
+    }),
+    { ok: false, stale: true, message: 'This timing review is no longer active.' },
+  );
+  assert.deepEqual(
+    runtime.resolveReview({
+      reviewId: payload.reviewId,
+      decision: { action: 'confirm', startTime: 10, endTime: 14 },
+    }),
+    { ok: false, message: 'The selected timing range is invalid.' },
+  );
+  assert.deepEqual(
+    runtime.resolveReview({
+      reviewId: payload.reviewId,
+      decision: { action: 'confirm', startTime: 99, endTime: 100.5 },
+    }),
+    { ok: false, message: 'The selected timing range is invalid.' },
+  );
+  assert.deepEqual(
+    runtime.resolveReview({
+      reviewId: payload.reviewId,
+      decision: { action: 'confirm', startTime: 10, endTime: 12, text: '   ' },
+    }),
+    { ok: false, message: 'The combined sentence text is invalid.' },
+  );
+  assert.deepEqual(
+    runtime.resolveReview({ reviewId: payload.reviewId, decision: { action: 'discard' } }),
+    { ok: true },
+  );
+  assert.deepEqual(await pendingDecision, { action: 'discard' });
+  assert.deepEqual(previewCalls, []);
+});
+
+test('collectMediaTimingContextLines splits cues around the mined range', () => {
+  const cues = [
+    { text: '一行目', startTime: 0, endTime: 2 },
+    { text: '二行目', startTime: 2.5, endTime: 4 },
+    { text: '', startTime: 4.2, endTime: 4.4 },
+    { text: '採掘行', startTime: 5, endTime: 7 },
+    { text: '四行目', startTime: 7.5, endTime: 9 },
+    { text: '五行目', startTime: 9.5, endTime: 11 },
+  ];
+
+  const context = collectMediaTimingContextLines({ cues, startTime: 5, endTime: 7 });
+
+  assert.deepEqual(context.previous, [
+    { text: '一行目', startTime: 0, endTime: 2 },
+    { text: '二行目', startTime: 2.5, endTime: 4 },
+  ]);
+  assert.deepEqual(context.next, [
+    { text: '四行目', startTime: 7.5, endTime: 9 },
+    { text: '五行目', startTime: 9.5, endTime: 11 },
+  ]);
+});
+
+test('collectMediaTimingContextLines falls back to played history when no cues are loaded', () => {
+  const context = collectMediaTimingContextLines({
+    cues: [],
+    fallbackPrevious: [
+      { displayText: '前の行', startTime: 1, endTime: 2 },
+      { displayText: '採掘行', startTime: 5, endTime: 7 },
+    ],
+    startTime: 5,
+    endTime: 7,
+  });
+
+  assert.deepEqual(context.previous, [{ text: '前の行', startTime: 1, endTime: 2 }]);
+  assert.deepEqual(context.next, []);
+});
+
+test('media timing review watchdog falls back when the renderer stops responding', async () => {
+  const { pendingDecision } = await startActiveMediaTimingReview({ decisionTimeoutMs: 0 });
+
+  assert.deepEqual(await pendingDecision, { action: 'use-original' });
+});
+
+test('media timing review does not resume playback when the prior state is unavailable', async () => {
+  const commands: Array<Array<string | number>> = [];
+  let runtime: ReturnType<typeof createMediaTimingReviewRuntime>;
+  runtime = createMediaTimingReviewRuntime({
+    getMpvClient: () => ({
+      connected: true,
+      currentVideoPath: '/video/show.mkv',
+      requestProperty: async () => null,
+      send: ({ command }) => commands.push(command),
+    }),
+    getCurrentMediaPath: () => '/video/show.mkv',
+    getMpvExecutablePath: () => '',
+    generateWaveform: async () => [],
+    createPreviewSession: () => ({
+      start: async () => {
+        throw new Error('preview unavailable');
+      },
+      play: async () => undefined,
+      stop: async () => undefined,
+      onPlaybackEnded: () => undefined,
+      dispose: () => undefined,
+    }),
+    openModal: async (payload) => {
+      queueMicrotask(() => {
+        runtime.resolveReview({
+          reviewId: payload.reviewId,
+          decision: { action: 'use-original' },
+        });
+      });
+      return true;
+    },
+    showStatus: () => undefined,
+  });
+
+  assert.deepEqual(
+    await runtime.requestReview({
+      kind: 'sentence',
+      text: '字幕',
+      startTime: 10,
+      endTime: 12,
+      audioPadding: 0,
+      maxMediaDuration: 30,
+    }),
+    { action: 'use-original' },
+  );
+  assert.deepEqual(commands, [['set_property', 'pause', 'yes']]);
+});
+
+test('media timing review restores playback when setup fails after pausing', async () => {
+  const commands: Array<Array<string | number>> = [];
+  const runtime = createMediaTimingReviewRuntime({
+    getMpvClient: () => ({
+      connected: true,
+      currentVideoPath: '/video/show.mkv',
+      requestProperty: async (name) => (name === 'pause' ? false : null),
+      send: ({ command }) => commands.push(command),
+    }),
+    getCurrentMediaPath: () => '/video/show.mkv',
+    getMpvExecutablePath: () => {
+      throw new Error('preview setup failed');
+    },
+    generateWaveform: async () => [],
+    createPreviewSession: () => ({
+      start: async () => undefined,
+      play: async () => undefined,
+      stop: async () => undefined,
+      onPlaybackEnded: () => undefined,
+      dispose: () => undefined,
+    }),
+    openModal: async () => true,
+    showStatus: () => undefined,
+  });
+
+  assert.deepEqual(
+    await runtime.requestReview({
+      kind: 'word',
+      text: '字幕',
+      startTime: 10,
+      endTime: 12,
+      audioPadding: 0,
+      maxMediaDuration: 30,
+    }),
+    { action: 'use-original' },
+  );
+  assert.deepEqual(commands, [
+    ['set_property', 'pause', 'yes'],
+    ['set_property', 'pause', 'no'],
+  ]);
+});
+
+test('disposing an open review settles it with original timing and restores playback', async () => {
+  const commands: Array<Array<string | number>> = [];
+  const runtime = createMediaTimingReviewRuntime({
+    getMpvClient: () => ({
+      connected: true,
+      currentVideoPath: '/video/show.mkv',
+      requestProperty: async (name) => (name === 'pause' ? false : null),
+      send: ({ command }) => commands.push(command),
+    }),
+    getCurrentMediaPath: () => '/video/show.mkv',
+    getMpvExecutablePath: () => 'mpv',
+    generateWaveform: async () => [],
+    createPreviewSession: () => ({
+      start: async () => undefined,
+      play: async () => undefined,
+      stop: async () => undefined,
+      onPlaybackEnded: () => undefined,
+      dispose: () => undefined,
+    }),
+    openModal: async () => true,
+    showStatus: () => undefined,
+  });
+
+  const pending = runtime.requestReview({
+    kind: 'word',
+    text: '字幕',
+    startTime: 10,
+    endTime: 12,
+    audioPadding: 0,
+    maxMediaDuration: 30,
+  });
+  await new Promise<void>((resolve) => setImmediate(resolve));
+  await runtime.dispose();
+
+  assert.deepEqual(await pending, { action: 'use-original' });
+  assert.deepEqual(commands, [
+    ['set_property', 'pause', 'yes'],
+    ['set_property', 'pause', 'no'],
+  ]);
+});
+
+for (const pendingSetup of ['properties', 'video-source'] as const) {
+  test(`disposing pending ${pendingSetup} cancels side effects and permits a fresh review`, async () => {
+    const setupGate = createDeferred<void>();
+    const commands: Array<Array<string | number>> = [];
+    let blockSetup = true;
+    let modalOpenCalls = 0;
+    let previewCreateCalls = 0;
+    let runtime: ReturnType<typeof createMediaTimingReviewRuntime>;
+    runtime = createMediaTimingReviewRuntime({
+      getMpvClient: () => ({
+        connected: true,
+        currentVideoPath: '/video/show.mkv',
+        requestProperty: async (name) => {
+          if (blockSetup && pendingSetup === 'properties') await setupGate.promise;
+          return name === 'pause' ? false : name === 'duration' ? 100 : null;
+        },
+        send: ({ command }) => commands.push(command),
+      }),
+      resolveVideoSource: async () => {
+        if (blockSetup && pendingSetup === 'video-source') await setupGate.promise;
+        return { path: '/video/show.mkv' };
+      },
+      getCurrentMediaPath: () => '/video/show.mkv',
+      getMpvExecutablePath: () => 'mpv',
+      generateWaveform: async () => [],
+      createPreviewSession: () => {
+        previewCreateCalls += 1;
+        return {
+          start: async () => undefined,
+          play: async () => undefined,
+          stop: async () => undefined,
+          onPlaybackEnded: () => undefined,
+          dispose: () => undefined,
+        };
+      },
+      openModal: async (payload) => {
+        modalOpenCalls += 1;
+        runtime.resolveReview({ reviewId: payload.reviewId, decision: { action: 'use-original' } });
+        return true;
+      },
+      showStatus: () => undefined,
+    });
+    const request = {
+      kind: 'word' as const,
+      text: '字幕',
+      startTime: 10,
+      endTime: 12,
+      audioPadding: 0,
+      maxMediaDuration: 30,
+      screenshotEnabled: true,
+    };
+
+    const pending = runtime.requestReview(request);
+    let pendingSettled = false;
+    void pending.finally(() => {
+      pendingSettled = true;
+    });
+    await Promise.resolve();
+    await runtime.dispose();
+
+    assert.equal(pendingSettled, true);
+    assert.deepEqual(await pending, { action: 'use-original' });
+    assert.deepEqual(commands, []);
+    assert.equal(modalOpenCalls, 0);
+    assert.equal(previewCreateCalls, 0);
+
+    setupGate.resolve();
+    await Promise.resolve();
+
+    blockSetup = false;
+    assert.deepEqual(await runtime.requestReview(request), { action: 'use-original' });
+    assert.equal(modalOpenCalls, 1);
+    assert.equal(previewCreateCalls, 1);
+  });
+}
+
+test('disposing during modal acknowledgement prevents the real opener from retrying', async () => {
+  const waiting = createDeferred<void>();
+  const acknowledgement = createDeferred<boolean>();
+  const commands: Array<Array<string | number>> = [];
+  let sendCalls = 0;
+  let previewDisposeCalls = 0;
+  let opening: Promise<boolean> | undefined;
+  const runtime = createMediaTimingReviewRuntime({
+    getMpvClient: () => ({
+      connected: true,
+      currentVideoPath: '/video/show.mkv',
+      requestProperty: async (name) => (name === 'pause' ? false : null),
+      send: ({ command }) => commands.push(command),
+    }),
+    getCurrentMediaPath: () => '/video/show.mkv',
+    getMpvExecutablePath: () => 'mpv',
+    generateWaveform: async () => [],
+    createPreviewSession: () => ({
+      start: async () => undefined,
+      play: async () => undefined,
+      stop: async () => undefined,
+      onPlaybackEnded: () => undefined,
+      dispose: () => {
+        previewDisposeCalls += 1;
+      },
+    }),
+    openModal: (payload, signal) => {
+      opening = openMediaTimingReviewModal(
+        {
+          ensureOverlayStartupPrereqs: () => {},
+          ensureOverlayWindowsReadyForVisibilityActions: () => {},
+          sendToActiveOverlayWindow: () => {
+            sendCalls += 1;
+            return true;
+          },
+          waitForModalOpen: () => {
+            waiting.resolve();
+            return acknowledgement.promise;
+          },
+          logWarn: () => {},
+        },
+        payload,
+        signal,
+      );
+      return opening;
+    },
+    showStatus: () => {},
+  });
+  const pending = runtime.requestReview({
+    kind: 'sentence',
+    text: '字幕',
+    startTime: 10,
+    endTime: 12,
+    audioPadding: 0,
+    maxMediaDuration: 30,
+  });
+  await waiting.promise;
+  await runtime.dispose();
+  assert.deepEqual(await pending, { action: 'use-original' });
+
+  acknowledgement.resolve(false);
+  assert.equal(await opening, false);
+  assert.equal(sendCalls, 1);
+  assert.equal(previewDisposeCalls, 1);
+  assert.deepEqual(commands, [
+    ['set_property', 'pause', 'yes'],
+    ['set_property', 'pause', 'no'],
+  ]);
+});
+
+test('disposing owns a preview session whose startup is still pending', async () => {
+  const openedPayload = createDeferred<MediaTimingReviewOpenPayload>();
+  const previewStarted = createDeferred<void>();
+  const previewStartGate = createDeferred<void>();
+  let previewDisposeCalls = 0;
+  const runtime = createMediaTimingReviewRuntime({
+    getMpvClient: () => ({
+      connected: true,
+      currentVideoPath: '/video/show.mkv',
+      requestProperty: async (name) => (name === 'duration' ? 100 : null),
+      send: () => undefined,
+    }),
+    getCurrentMediaPath: () => '/video/show.mkv',
+    getMpvExecutablePath: () => 'mpv',
+    generateWaveform: async () => [],
+    createPreviewSession: () => ({
+      start: async () => {
+        previewStarted.resolve();
+        await previewStartGate.promise;
+      },
+      play: async () => undefined,
+      stop: async () => undefined,
+      onPlaybackEnded: () => undefined,
+      dispose: () => {
+        previewDisposeCalls += 1;
+      },
+    }),
+    openModal: async (payload) => {
+      openedPayload.resolve(payload);
+      return true;
+    },
+    showStatus: () => undefined,
+  });
+
+  const pending = runtime.requestReview({
+    kind: 'sentence',
+    text: '字幕',
+    startTime: 10,
+    endTime: 12,
+    audioPadding: 0,
+    maxMediaDuration: 30,
+  });
+  await openedPayload.promise;
+  await previewStarted.promise;
+
+  await runtime.dispose();
+  assert.deepEqual(await pending, { action: 'use-original' });
+  assert.equal(previewDisposeCalls, 0);
+
+  previewStartGate.resolve();
+  await new Promise<void>((resolve) => setImmediate(resolve));
+  assert.equal(previewDisposeCalls, 1);
+});
+
+test('media timing review forwards the hidden player finishing a preview to the modal', async () => {
+  const endedReviewIds: string[] = [];
+  const playback: { ended?: () => void } = {};
+  let publishPayload!: (payload: MediaTimingReviewOpenPayload) => void;
+  const openedPayload = new Promise<MediaTimingReviewOpenPayload>((resolve) => {
+    publishPayload = resolve;
+  });
+  const runtime = createMediaTimingReviewRuntime({
+    getMpvClient: () => ({
+      connected: true,
+      currentVideoPath: '/video/show.mkv',
+      requestProperty: async (name) => (name === 'duration' ? 100 : null),
+      send: () => undefined,
+    }),
+    getCurrentMediaPath: () => '/video/show.mkv',
+    getMpvExecutablePath: () => 'mpv',
+    generateWaveform: async () => [],
+    createPreviewSession: () => ({
+      start: async () => undefined,
+      play: async () => undefined,
+      stop: async () => undefined,
+      onPlaybackEnded: (listener) => {
+        playback.ended = listener;
+      },
+      dispose: () => undefined,
+    }),
+    openModal: async (payload) => {
+      publishPayload(payload);
+      return true;
+    },
+    onPreviewEnded: (reviewId) => {
+      endedReviewIds.push(reviewId);
+    },
+    showStatus: () => undefined,
+  });
+  const pendingDecision = runtime.requestReview({
+    kind: 'sentence',
+    text: '字幕',
+    startTime: 10,
+    endTime: 12,
+    audioPadding: 0,
+    maxMediaDuration: 30,
+  });
+  const payload = await openedPayload;
+
+  assert.deepEqual(
+    await runtime.previewRange({ reviewId: payload.reviewId, startTime: 10, endTime: 12 }),
+    {
+      ok: true,
+    },
+  );
+  assert.ok(playback.ended);
+  playback.ended();
+  assert.deepEqual(endedReviewIds, [payload.reviewId]);
+
+  runtime.resolveReview({ reviewId: payload.reviewId, decision: { action: 'use-original' } });
+  await pendingDecision;
+  playback.ended();
+  assert.deepEqual(endedReviewIds, [payload.reviewId]);
+});
+
+test('preview reports a stale review when the review ends during playback', async () => {
+  let endReview: (() => Promise<void>) | null = null;
+  const { runtime, payload, pendingDecision } = await startActiveMediaTimingReview({
+    play: async () => {
+      await endReview?.();
+    },
+  });
+  endReview = () => runtime.dispose();
+
+  assert.deepEqual(
+    await runtime.previewRange({ reviewId: payload.reviewId, startTime: 10, endTime: 12 }),
+    { ok: false, stale: true, message: 'This timing review is no longer active.' },
+  );
+  await pendingDecision;
+});
+
+test('waveform reports a stale review when the review ends during analysis', async () => {
+  let endReview: (() => Promise<void>) | null = null;
+  const { runtime, payload, pendingDecision } = await startActiveMediaTimingReview({
+    generateWaveform: async () => {
+      await endReview?.();
+      return [0.1, 0.9, 0.2];
+    },
+  });
+  endReview = () => runtime.dispose();
+
+  assert.deepEqual(
+    await runtime.getWaveform({ reviewId: payload.reviewId, startTime: 8, endTime: 14 }),
+    { ok: false, stale: true, message: 'This timing review is no longer active.' },
+  );
+  await pendingDecision;
+});
diff --git a/src/main/runtime/media-timing-review.ts b/src/main/runtime/media-timing-review.ts
new file mode 100644
index 00000000..abb3258d
--- /dev/null
+++ b/src/main/runtime/media-timing-review.ts
@@ -0,0 +1,763 @@
+import { randomUUID } from 'crypto';
+import type {
+  MediaTimingReviewActionResult,
+  MediaTimingReviewContextLine,
+  MediaTimingReviewDecision,
+  MediaTimingReviewOpenPayload,
+  MediaTimingReviewPreviewRequest,
+  MediaTimingReviewRequest,
+  MediaTimingReviewResolveRequest,
+  MediaTimingReviewFrameRequest,
+  MediaTimingReviewFrameResult,
+  MediaTimingReviewWaveformRequest,
+  MediaTimingReviewWaveformResult,
+} from '../../types/anki';
+import type { SpeechWaveformOptions } from '../../core/services/media-timing-waveform';
+import type { MediaTimingFrameOptions } from '../../core/services/media-timing-frame';
+import {
+  isRemoteMediaWindowSourcePath,
+  type RemoteMediaWindow,
+  type RemoteMediaWindowRange,
+  type RemoteMediaWindowSource,
+} from '../../core/services/remote-media-window-cache';
+import type { MediaInput, MediaInputOptions } from '../../media-input';
+
+const INITIAL_TIMELINE_MARGIN_SECONDS = 2;
+const REVIEW_DECISION_TIMEOUT_MS = 5 * 60_000;
+const CONTEXT_LINE_LIMIT = 12;
+const CONTEXT_LINE_EPSILON_SECONDS = 0.05;
+
+interface ReviewMpvClient {
+  connected: boolean;
+  currentVideoPath: string;
+  currentAudioStreamIndex?: number | null;
+  requestProperty?: (name: string) => Promise<unknown>;
+  send: (payload: { command: Array<string | number> }) => void;
+}
+
+interface PreviewSession {
+  start(options: {
+    mediaPath: string;
+    executablePath?: string;
+    audioTrackId?: number;
+    volume?: number;
+    absoluteTimestamps?: boolean;
+  }): Promise<void>;
+  play(startTime: number, endTime: number): Promise<void>;
+  stop(): Promise<void>;
+  /** Fires when the player reaches the end of the clip started by play(). */
+  onPlaybackEnded(listener: () => void): void;
+  dispose(): void;
+}
+
+interface ReviewMediaSource {
+  path: string;
+  inputOptions?: MediaInputOptions;
+  singleResolvedStream?: boolean;
+}
+
+interface ActiveReview {
+  payload: MediaTimingReviewOpenPayload;
+  /** What the hidden mpv preview plays when no cached window is available. */
+  mediaPath: string;
+  /** What the waveform reads when no cached window is available. */
+  waveformMedia: MediaInput;
+  videoSource: ReviewMediaSource | null;
+  frameInFlight: boolean;
+  audioStreamIndex?: number;
+  /** Remote source to download windows of; null for local media or without a cache. */
+  windowSource: RemoteMediaWindowSource | null;
+  /** Latest window returned for this review; reused while it still covers the request. */
+  window: RemoteMediaWindow | null;
+  windowRequest: (RemoteMediaWindowRange & { promise: Promise<RemoteMediaWindow | null> }) | null;
+  windowFailed: boolean;
+  previewOptions: { executablePath?: string; audioTrackId?: number; volume?: number };
+  preview: { path: string; session: Promise<PreviewSession> } | null;
+  mpvClient: ReviewMpvClient;
+  restorePlayback: boolean;
+  resolve: (decision: MediaTimingReviewDecision) => void;
+}
+
+interface ReviewRequestLifecycle {
+  signal: AbortSignal;
+  cancelled: Promise<void>;
+  settled: Promise<void>;
+  isCancelled(): boolean;
+  cancel(): void;
+  markSettled(): void;
+}
+
+export interface MediaTimingReviewRuntimeDeps {
+  getMpvClient: () => ReviewMpvClient | null;
+  getCurrentMediaPath: () => string | null;
+  getMpvExecutablePath: () => string;
+  createPreviewSession: () => PreviewSession;
+  generateWaveform: (options: SpeechWaveformOptions) => Promise<number[]>;
+  /** Resolves the FFmpeg-readable stream URL and headers behind the current media path. */
+  resolveMediaSource?: () => Promise<ReviewMediaSource | null>;
+  resolveVideoSource?: () => Promise<ReviewMediaSource | null>;
+  generateFrame?: (
+    options: MediaTimingFrameOptions,
+  ) => Promise<{ dataUrl: string; timestamp: number }>;
+  clearFrameCache?: () => void;
+  /** Downloads (or reuses) a local window of a remote source covering the range. */
+  acquireMediaWindow?: (
+    source: RemoteMediaWindowSource,
+    range: RemoteMediaWindowRange,
+  ) => Promise<RemoteMediaWindow>;
+  getSubtitleContextLines?: (range: { startTime: number; endTime: number }) => {
+    previous: MediaTimingReviewContextLine[];
+    next: MediaTimingReviewContextLine[];
+  };
+  decisionTimeoutMs?: number;
+  openModal: (payload: MediaTimingReviewOpenPayload, signal: AbortSignal) => Promise<boolean>;
+  /** Tells the modal that the hidden player finished the previewed clip. */
+  onPreviewEnded?: (reviewId: string) => void;
+  showStatus: (message: string) => void;
+}
+
+function finiteNumber(value: unknown): number | null {
+  return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+
+function booleanProperty(value: unknown): boolean | null {
+  if (typeof value === 'boolean') return value;
+  if (value === 'yes' || value === 1) return true;
+  if (value === 'no' || value === 0) return false;
+  return null;
+}
+
+function createReviewRequestLifecycle(): ReviewRequestLifecycle {
+  const controller = new AbortController();
+  let resolveCancellation: (() => void) | null = null;
+  let resolveSettled: (() => void) | null = null;
+  const cancellation = new Promise<void>((resolve) => {
+    resolveCancellation = resolve;
+  });
+  const settled = new Promise<void>((resolve) => {
+    resolveSettled = resolve;
+  });
+  return {
+    signal: controller.signal,
+    cancelled: cancellation,
+    settled,
+    isCancelled: () => controller.signal.aborted,
+    cancel: () => {
+      if (controller.signal.aborted) return;
+      controller.abort();
+      resolveCancellation?.();
+    },
+    markSettled: () => {
+      resolveSettled?.();
+      resolveSettled = null;
+    },
+  };
+}
+
+/**
+ * Picks the subtitle lines adjacent to the mined range that the review modal can pull
+ * onto the card. Parsed cues cover both directions; when none are loaded (e.g. the
+ * active track was never parsed) the timing tracker's history still provides the
+ * lines that already played, so only "next" is unavailable.
+ */
+export function collectMediaTimingContextLines(options: {
+  cues: readonly { text: string; startTime: number; endTime: number }[];
+  fallbackPrevious?: readonly { displayText: string; startTime: number; endTime: number }[];
+  startTime: number;
+  endTime: number;
+}): { previous: MediaTimingReviewContextLine[]; next: MediaTimingReviewContextLine[] } {
+  const usable = options.cues
+    .filter(
+      (cue) =>
+        cue.text.trim().length > 0 &&
+        Number.isFinite(cue.startTime) &&
+        Number.isFinite(cue.endTime) &&
+        cue.endTime > cue.startTime,
+    )
+    .sort((a, b) => a.startTime - b.startTime || a.endTime - b.endTime);
+
+  let previous = usable
+    .filter((cue) => cue.endTime <= options.startTime + CONTEXT_LINE_EPSILON_SECONDS)
+    .slice(-CONTEXT_LINE_LIMIT)
+    .map(({ text, startTime, endTime }) => ({ text: text.trim(), startTime, endTime }));
+  const next = usable
+    .filter((cue) => cue.startTime >= options.endTime - CONTEXT_LINE_EPSILON_SECONDS)
+    .slice(0, CONTEXT_LINE_LIMIT)
+    .map(({ text, startTime, endTime }) => ({ text: text.trim(), startTime, endTime }));
+
+  if (previous.length === 0 && options.fallbackPrevious) {
+    previous = options.fallbackPrevious
+      .filter(
+        (entry) =>
+          entry.displayText.trim().length > 0 &&
+          Number.isFinite(entry.startTime) &&
+          Number.isFinite(entry.endTime) &&
+          entry.endTime > entry.startTime &&
+          entry.endTime <= options.startTime + CONTEXT_LINE_EPSILON_SECONDS,
+      )
+      .slice(-CONTEXT_LINE_LIMIT)
+      .map((entry) => ({
+        text: entry.displayText.trim(),
+        startTime: entry.startTime,
+        endTime: entry.endTime,
+      }));
+  }
+  return { previous, next };
+}
+
+/**
+ * Result for requests that name a review main has already resolved or disposed (decision
+ * watchdog, overlay teardown, duplicate modal). The renderer closes on it instead of
+ * leaving the user with controls that can never succeed.
+ */
+function staleReviewResult(): MediaTimingReviewActionResult {
+  return { ok: false, stale: true, message: 'This timing review is no longer active.' };
+}
+
+function isValidMediaTimingRange(
+  payload: MediaTimingReviewOpenPayload,
+  startTime: number,
+  endTime: number,
+): boolean {
+  return (
+    Number.isFinite(startTime) &&
+    Number.isFinite(endTime) &&
+    startTime >= 0 &&
+    endTime > startTime &&
+    (payload.maxMediaDuration <= 0 || endTime - startTime <= payload.maxMediaDuration + 0.001) &&
+    (payload.mediaDuration === undefined || endTime <= payload.mediaDuration + 0.001)
+  );
+}
+
+export function buildMediaTimingReviewPayload(
+  request: MediaTimingReviewRequest,
+  options: {
+    reviewId: string;
+    mediaDuration?: number;
+    contextLines?: {
+      previous: MediaTimingReviewContextLine[];
+      next: MediaTimingReviewContextLine[];
+    };
+  },
+): MediaTimingReviewOpenPayload {
+  const duration = finiteNumber(options.mediaDuration);
+  const maxTime = duration !== null && duration > 0 ? duration : Number.POSITIVE_INFINITY;
+  const paddedStart = Math.max(0, request.startTime - request.audioPadding);
+  let paddedEnd = Math.min(maxTime, request.endTime + request.audioPadding);
+  const maxMediaDuration = Math.max(0, request.maxMediaDuration);
+  if (maxMediaDuration > 0 && paddedEnd - paddedStart > maxMediaDuration) {
+    paddedEnd = paddedStart + maxMediaDuration;
+  }
+  if (paddedEnd <= paddedStart) {
+    paddedEnd = Math.min(maxTime, paddedStart + 0.1);
+  }
+
+  const timelineStartTime = Math.max(0, paddedStart - INITIAL_TIMELINE_MARGIN_SECONDS);
+  const timelineEndTime = Math.max(
+    paddedEnd,
+    Math.min(maxTime, paddedEnd + INITIAL_TIMELINE_MARGIN_SECONDS),
+  );
+
+  return {
+    reviewId: options.reviewId,
+    kind: request.kind,
+    text: request.text,
+    previousLines: options.contextLines?.previous ?? [],
+    nextLines: options.contextLines?.next ?? [],
+    ...(request.noteId !== undefined ? { noteId: request.noteId } : {}),
+    originalStartTime: request.startTime,
+    originalEndTime: request.endTime,
+    selectionStartTime: paddedStart,
+    selectionEndTime: paddedEnd,
+    timelineStartTime,
+    timelineEndTime,
+    ...(duration !== null && duration > 0 ? { mediaDuration: duration } : {}),
+    maxMediaDuration,
+    ...(request.screenshotEnabled !== undefined
+      ? { screenshotEnabled: request.screenshotEnabled }
+      : {}),
+  };
+}
+
+export function createMediaTimingReviewRuntime(deps: MediaTimingReviewRuntimeDeps) {
+  let active: ActiveReview | null = null;
+  let currentRequest: ReviewRequestLifecycle | null = null;
+  let pendingPauseRestore: ReviewMpvClient | null = null;
+
+  function restorePendingPlayback(): void {
+    const mpvClient = pendingPauseRestore;
+    pendingPauseRestore = null;
+    if (mpvClient?.connected) {
+      mpvClient.send({ command: ['set_property', 'pause', 'no'] });
+    }
+  }
+
+  function ensureWindow(
+    review: ActiveReview,
+    range: RemoteMediaWindowRange,
+  ): Promise<RemoteMediaWindow | null> {
+    const { windowSource } = review;
+    if (!windowSource || review.windowFailed || !deps.acquireMediaWindow) {
+      return Promise.resolve(null);
+    }
+    const coversRange = (candidate: RemoteMediaWindowRange): boolean =>
+      candidate.startTime <= range.startTime && candidate.endTime >= range.endTime;
+    if (review.window && coversRange(review.window)) return Promise.resolve(review.window);
+    const inFlight = review.windowRequest;
+    if (inFlight && coversRange(inFlight)) return inFlight.promise;
+
+    const request = {
+      startTime: range.startTime,
+      endTime: range.endTime,
+      promise: Promise.resolve<RemoteMediaWindow | null>(null),
+    };
+    request.promise = deps
+      .acquireMediaWindow(windowSource, { startTime: range.startTime, endTime: range.endTime })
+      .then((window) => {
+        review.window = window;
+        return window;
+      })
+      .catch(() => {
+        // Fall back to the remote source for the rest of this review instead of retrying.
+        review.windowFailed = true;
+        return null;
+      })
+      .finally(() => {
+        if (review.windowRequest === request) review.windowRequest = null;
+      });
+    review.windowRequest = request;
+    return request.promise;
+  }
+
+  /**
+   * Returns the preview player for the range, restarting it when the range needs a
+   * different file (the first cached window, or a wider one after the timeline grew).
+   */
+  async function previewFor(
+    review: ActiveReview,
+    range: RemoteMediaWindowRange,
+  ): Promise<PreviewSession> {
+    const window = await ensureWindow(review, range);
+    if (active !== review) {
+      // The review ended during the download; do not start a player nobody will dispose.
+      throw new Error('This timing review is no longer active.');
+    }
+    const mediaPath = window?.path ?? review.mediaPath;
+    if (review.preview?.path === mediaPath) return review.preview.session;
+
+    const previous = review.preview;
+    const session = deps.createPreviewSession();
+    const { audioTrackId, ...previewOptions } = review.previewOptions;
+    const startSession = async (): Promise<PreviewSession> => {
+      if (active !== review) {
+        throw new Error('This timing review is no longer active.');
+      }
+      await session.start({
+        mediaPath,
+        ...previewOptions,
+        // A cached window keeps one audio stream, so mpv's track id from the source no longer applies.
+        ...(window
+          ? { absoluteTimestamps: true }
+          : audioTrackId !== undefined
+            ? { audioTrackId }
+            : {}),
+      });
+      return session;
+    };
+    const started = Promise.resolve()
+      .then(startSession)
+      .catch((error: unknown) => {
+        session.dispose();
+        throw error;
+      });
+    review.preview = { path: mediaPath, session: started };
+    session.onPlaybackEnded(() => {
+      if (active === review && review.preview?.session === started) {
+        deps.onPreviewEnded?.(review.payload.reviewId);
+      }
+    });
+    void started.catch(() => {});
+    if (previous) void previous.session.then((old) => old.dispose()).catch(() => {});
+    return started;
+  }
+
+  async function runReview(
+    request: MediaTimingReviewRequest,
+    lifecycle: ReviewRequestLifecycle,
+  ): Promise<MediaTimingReviewDecision> {
+    const mpvClient = deps.getMpvClient();
+    const mediaPath =
+      deps.getCurrentMediaPath()?.trim() || mpvClient?.currentVideoPath?.trim() || '';
+    if (!mpvClient?.connected || !mediaPath) {
+      deps.showStatus('Timing review unavailable. Using the original subtitle timing.');
+      return { action: 'use-original' };
+    }
+
+    const setupPromise = Promise.all([
+      mpvClient.requestProperty?.('pause').catch(() => null) ?? null,
+      mpvClient.requestProperty?.('duration').catch(() => null) ?? null,
+      mpvClient.requestProperty?.('aid').catch(() => null) ?? null,
+      mpvClient.requestProperty?.('volume').catch(() => null) ?? null,
+      deps.resolveMediaSource?.().catch(() => null) ?? null,
+      request.screenshotEnabled ? (deps.resolveVideoSource?.().catch(() => null) ?? null) : null,
+    ]);
+    const setup = await Promise.race([
+      setupPromise.then((values) => ({ kind: 'ready' as const, values })),
+      lifecycle.cancelled.then(() => ({ kind: 'cancelled' as const })),
+    ]);
+    if (setup.kind === 'cancelled' || lifecycle.isCancelled()) {
+      return { action: 'use-original' };
+    }
+    const [pauseRaw, durationRaw, audioTrackRaw, volumeRaw, resolvedSource, videoSource] =
+      setup.values;
+    const pauseState = booleanProperty(pauseRaw);
+    pendingPauseRestore = pauseState === false ? mpvClient : null;
+    mpvClient.send({ command: ['set_property', 'pause', 'yes'] });
+    if (lifecycle.isCancelled()) {
+      restorePendingPlayback();
+      return { action: 'use-original' };
+    }
+
+    let contextLines: ReturnType<NonNullable<typeof deps.getSubtitleContextLines>> | undefined;
+    try {
+      contextLines = deps.getSubtitleContextLines?.({
+        startTime: request.startTime,
+        endTime: request.endTime,
+      });
+    } catch {
+      contextLines = undefined;
+    }
+    const payload = buildMediaTimingReviewPayload(request, {
+      reviewId: randomUUID(),
+      mediaDuration: finiteNumber(durationRaw) ?? undefined,
+      ...(contextLines ? { contextLines } : {}),
+    });
+    const sourcePath = resolvedSource?.path.trim() || mediaPath;
+    const inputOptions = resolvedSource?.inputOptions;
+    const audioStreamIndex =
+      resolvedSource?.singleResolvedStream || mpvClient.currentAudioStreamIndex == null
+        ? undefined
+        : mpvClient.currentAudioStreamIndex;
+    const windowSource: RemoteMediaWindowSource | null =
+      deps.acquireMediaWindow && isRemoteMediaWindowSourcePath(sourcePath)
+        ? {
+            path: sourcePath,
+            ...(inputOptions ? { inputOptions } : {}),
+            audioStreamIndex: audioStreamIndex ?? null,
+          }
+        : null;
+
+    let resolveDecision!: (decision: MediaTimingReviewDecision) => void;
+    const decisionPromise = new Promise<MediaTimingReviewDecision>((resolve) => {
+      resolveDecision = resolve;
+    });
+    const review: ActiveReview = {
+      payload,
+      mediaPath,
+      waveformMedia: inputOptions ? { path: sourcePath, inputOptions } : sourcePath,
+      videoSource,
+      frameInFlight: false,
+      ...(audioStreamIndex !== undefined ? { audioStreamIndex } : {}),
+      windowSource,
+      window: null,
+      windowRequest: null,
+      windowFailed: false,
+      previewOptions: {
+        executablePath: deps.getMpvExecutablePath(),
+        audioTrackId: finiteNumber(audioTrackRaw) ?? undefined,
+        volume: finiteNumber(volumeRaw) ?? undefined,
+      },
+      preview: null,
+      mpvClient,
+      restorePlayback: pendingPauseRestore === mpvClient,
+      resolve: resolveDecision,
+    };
+    active = review;
+    pendingPauseRestore = null;
+    // Download the visible timeline once now; the waveform and preview both wait on it.
+    void previewFor(review, {
+      startTime: payload.timelineStartTime,
+      endTime: payload.timelineEndTime,
+    }).catch(() => {});
+
+    if (lifecycle.isCancelled() || active !== review) {
+      await cleanupActiveReview(review);
+      return { action: 'use-original' };
+    }
+    const openModal = deps.openModal(payload, lifecycle.signal).catch(() => false);
+    const openResult = await Promise.race([
+      openModal.then((opened) => ({ kind: 'opened' as const, opened })),
+      lifecycle.cancelled.then(() => ({ kind: 'cancelled' as const })),
+    ]);
+    if (openResult.kind === 'cancelled' || lifecycle.isCancelled() || active !== review) {
+      await cleanupActiveReview(review);
+      return { action: 'use-original' };
+    }
+    const { opened } = openResult;
+    if (!opened) {
+      await cleanupActiveReview(review);
+      deps.showStatus('Timing review could not open. Using the original subtitle timing.');
+      return { action: 'use-original' };
+    }
+
+    const decisionWatchdog = setTimeout(
+      () => resolveDecision({ action: 'use-original' }),
+      Math.max(0, deps.decisionTimeoutMs ?? REVIEW_DECISION_TIMEOUT_MS),
+    );
+    let decision: MediaTimingReviewDecision = { action: 'use-original' };
+    try {
+      const decisionResult = await Promise.race([
+        decisionPromise.then((value) => ({ kind: 'decided' as const, value })),
+        lifecycle.cancelled.then(() => ({ kind: 'cancelled' as const })),
+      ]);
+      if (decisionResult.kind === 'decided') {
+        decision = decisionResult.value;
+      }
+    } finally {
+      clearTimeout(decisionWatchdog);
+    }
+    await cleanupActiveReview(review);
+    return decision;
+  }
+
+  async function requestReview(
+    request: MediaTimingReviewRequest,
+  ): Promise<MediaTimingReviewDecision> {
+    if (active || currentRequest) {
+      deps.showStatus('Finish the current timing review before mining another card.');
+      return { action: 'use-original' };
+    }
+    const lifecycle = createReviewRequestLifecycle();
+    currentRequest = lifecycle;
+    try {
+      return await runReview(request, lifecycle);
+    } catch {
+      await cleanupActiveReview();
+      restorePendingPlayback();
+      deps.showStatus('Timing review failed. Using the original subtitle timing.');
+      return { action: 'use-original' };
+    } finally {
+      if (currentRequest === lifecycle) {
+        currentRequest = null;
+      }
+      lifecycle.markSettled();
+    }
+  }
+
+  async function previewRange(
+    request: MediaTimingReviewPreviewRequest,
+  ): Promise<MediaTimingReviewActionResult> {
+    const current = active;
+    if (!current || request.reviewId !== current.payload.reviewId) {
+      return staleReviewResult();
+    }
+    if (!isValidMediaTimingRange(current.payload, request.startTime, request.endTime)) {
+      return { ok: false, message: 'The selected preview range is invalid.' };
+    }
+    try {
+      const previewSession = await previewFor(current, request);
+      if (active !== current) {
+        return staleReviewResult();
+      }
+      await previewSession.play(request.startTime, request.endTime);
+      // Playback spans the whole clip, so the review can end (watchdog, teardown) while
+      // it runs; reporting success would leave the modal open on a dead review.
+      if (active !== current) {
+        return staleReviewResult();
+      }
+      return { ok: true };
+    } catch (error) {
+      if (active !== current) {
+        return staleReviewResult();
+      }
+      return {
+        ok: false,
+        message: `Audio preview unavailable: ${error instanceof Error ? error.message : String(error)}`,
+      };
+    }
+  }
+
+  async function getWaveform(
+    request: MediaTimingReviewWaveformRequest,
+  ): Promise<MediaTimingReviewWaveformResult> {
+    const current = active;
+    if (!current || request.reviewId !== current.payload.reviewId) {
+      return staleReviewResult();
+    }
+    if (
+      !Number.isFinite(request.startTime) ||
+      !Number.isFinite(request.endTime) ||
+      request.startTime < 0 ||
+      request.endTime <= request.startTime ||
+      (current.payload.mediaDuration !== undefined &&
+        request.endTime > current.payload.mediaDuration + 0.001)
+    ) {
+      return { ok: false, message: 'The waveform range is invalid.' };
+    }
+
+    try {
+      const window = await ensureWindow(current, request);
+      if (active !== current) {
+        return staleReviewResult();
+      }
+      const peaks = await deps.generateWaveform({
+        mediaPath: window?.media ?? current.waveformMedia,
+        startTime: request.startTime,
+        endTime: request.endTime,
+        ...(!window && current.audioStreamIndex !== undefined
+          ? { audioStreamIndex: current.audioStreamIndex }
+          : {}),
+      });
+      // ffmpeg decoding runs long enough for the review to end underneath it.
+      if (active !== current) {
+        return staleReviewResult();
+      }
+      if (peaks.length < 2 || peaks.some((peak) => !Number.isFinite(peak))) {
+        return { ok: false, message: 'Timing waveform is unavailable.' };
+      }
+      return { ok: true, peaks };
+    } catch {
+      if (active !== current) {
+        return staleReviewResult();
+      }
+      return { ok: false, message: 'Timing waveform is unavailable.' };
+    }
+  }
+
+  async function getFrame(
+    request: MediaTimingReviewFrameRequest,
+  ): Promise<MediaTimingReviewFrameResult> {
+    const current = active;
+    if (!current || request.reviewId !== current.payload.reviewId) return staleReviewResult();
+    if (!current.payload.screenshotEnabled || !deps.generateFrame || !current.videoSource) {
+      return { ok: false, message: 'Screenshot preview is unavailable for this media.' };
+    }
+    if (
+      !Number.isFinite(request.timestamp) ||
+      request.timestamp < 0 ||
+      (current.payload.mediaDuration !== undefined &&
+        request.timestamp >= current.payload.mediaDuration) ||
+      (request.direction !== undefined && request.direction !== -1 && request.direction !== 1)
+    ) {
+      return { ok: false, message: 'The screenshot time is invalid.' };
+    }
+    if (current.frameInFlight)
+      return { ok: false, message: 'A screenshot preview is already loading.' };
+    current.frameInFlight = true;
+    try {
+      // Reuse the audio window only when it contains this same video source (not split streams).
+      const range = {
+        startTime: Math.max(0, Math.min(current.payload.timelineStartTime, request.timestamp - 2)),
+        endTime: Math.min(
+          current.payload.mediaDuration ?? Infinity,
+          Math.max(current.payload.timelineEndTime, request.timestamp + 2),
+        ),
+      };
+      const window =
+        current.windowSource?.path === current.videoSource.path
+          ? await ensureWindow(current, range)
+          : null;
+      if (active !== current) return staleReviewResult();
+      const frame = await deps.generateFrame({
+        media: window?.media ?? current.videoSource,
+        timestamp: request.timestamp,
+        ...(request.direction !== undefined ? { direction: request.direction } : {}),
+      });
+      if (active !== current) return staleReviewResult();
+      return { ok: true, ...frame };
+    } catch {
+      if (active !== current) return staleReviewResult();
+      return {
+        ok: false,
+        message: 'Screenshot preview unavailable. Try another time or reset to the midpoint.',
+      };
+    } finally {
+      current.frameInFlight = false;
+    }
+  }
+
+  async function stopPreview(reviewId: string): Promise<MediaTimingReviewActionResult> {
+    const current = active;
+    if (!current || reviewId !== current.payload.reviewId) {
+      return staleReviewResult();
+    }
+    try {
+      const previewSession = current.preview ? await current.preview.session : null;
+      if (active !== current) {
+        return staleReviewResult();
+      }
+      await previewSession?.stop();
+      if (active !== current) {
+        return staleReviewResult();
+      }
+      return { ok: true };
+    } catch (error) {
+      if (active !== current) {
+        return staleReviewResult();
+      }
+      return {
+        ok: false,
+        message: `Could not stop preview: ${error instanceof Error ? error.message : String(error)}`,
+      };
+    }
+  }
+
+  function resolveReview(request: MediaTimingReviewResolveRequest): MediaTimingReviewActionResult {
+    const current = active;
+    if (!current || request.reviewId !== current.payload.reviewId) {
+      return staleReviewResult();
+    }
+    if (request.decision.action === 'confirm') {
+      const { startTime, endTime, text, screenshotTime } = request.decision;
+      if (!isValidMediaTimingRange(current.payload, startTime, endTime)) {
+        return { ok: false, message: 'The selected timing range is invalid.' };
+      }
+      if (text !== undefined && (typeof text !== 'string' || text.trim().length === 0)) {
+        return { ok: false, message: 'The combined sentence text is invalid.' };
+      }
+      if (
+        screenshotTime !== undefined &&
+        (!current.payload.screenshotEnabled ||
+          !Number.isFinite(screenshotTime) ||
+          screenshotTime < 0 ||
+          (current.payload.mediaDuration !== undefined &&
+            screenshotTime >= current.payload.mediaDuration))
+      ) {
+        return { ok: false, message: 'The screenshot time is invalid.' };
+      }
+    }
+    current.resolve(request.decision);
+    return { ok: true };
+  }
+
+  async function cleanupActiveReview(expected?: ActiveReview): Promise<void> {
+    const current = active;
+    if (expected && current !== expected) return;
+    active = null;
+    if (!current) return;
+    deps.clearFrameCache?.();
+    void current.preview?.session.then((session) => session.dispose()).catch(() => {});
+    if (current.restorePlayback && current.mpvClient.connected) {
+      current.mpvClient.send({ command: ['set_property', 'pause', 'no'] });
+    }
+  }
+
+  async function dispose(): Promise<void> {
+    const request = currentRequest;
+    request?.cancel();
+    active?.resolve({ action: 'use-original' });
+    await cleanupActiveReview();
+    restorePendingPlayback();
+    await request?.settled;
+  }
+
+  return {
+    requestReview,
+    previewRange,
+    getWaveform,
+    getFrame,
+    stopPreview,
+    resolveReview,
+    dispose,
+  };
+}
diff --git a/src/main/runtime/mpv-input-bindings.test.ts b/src/main/runtime/mpv-input-bindings.test.ts
new file mode 100644
index 00000000..f8f1202c
--- /dev/null
+++ b/src/main/runtime/mpv-input-bindings.test.ts
@@ -0,0 +1,41 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { readMpvInputBindings } from './mpv-input-bindings';
+
+test('discovery reads the connected player and preserves configured keys including disabled bindings', async () => {
+  const client = {
+    connected: true,
+    requestProperty: async (name: string) => {
+      assert.equal(name, 'input-bindings');
+      return [{ key: 'r', cmd: 'script-binding replay/run', priority: 1 }];
+    },
+  };
+  assert.deepEqual(
+    await readMpvInputBindings({
+      getMpvClient: () => client,
+      getConfiguredKeybindings: () => [{ key: 'Ctrl+KeyR', command: null }],
+      platform: 'linux',
+    }),
+    { keys: ['r'], blockedKeys: [{ code: 'KeyR', modifiers: ['ctrl'] }] },
+  );
+});
+
+test('discovery safely handles unsupported properties and disconnects during a request', async () => {
+  const client = {
+    connected: true,
+    requestProperty: async (): Promise<unknown> => {
+      throw new Error('property unavailable');
+    },
+  };
+  const deps = {
+    getMpvClient: () => client,
+    getConfiguredKeybindings: () => [],
+    platform: 'linux',
+  } satisfies Parameters<typeof readMpvInputBindings>[0];
+  assert.deepEqual((await readMpvInputBindings(deps)).keys, []);
+  client.requestProperty = async () => {
+    client.connected = false;
+    return [{ key: 'r', cmd: 'seek 5', priority: 1 }];
+  };
+  assert.deepEqual((await readMpvInputBindings(deps)).keys, []);
+});
diff --git a/src/main/runtime/mpv-input-bindings.ts b/src/main/runtime/mpv-input-bindings.ts
new file mode 100644
index 00000000..ffc88749
--- /dev/null
+++ b/src/main/runtime/mpv-input-bindings.ts
@@ -0,0 +1,31 @@
+import type { Keybinding } from '../../types';
+import { parseSessionBindingKey } from '../../core/services/session-bindings';
+import { parseMpvInputBindingKeys } from '../../shared/mpv-input-bindings';
+import type { MpvInputBindingsSnapshot } from '../../types/session-bindings';
+
+export async function readMpvInputBindings(deps: {
+  getMpvClient: () => {
+    connected: boolean;
+    requestProperty: (name: string) => Promise<unknown>;
+  } | null;
+  getConfiguredKeybindings: () => Keybinding[];
+  platform: 'darwin' | 'win32' | 'linux';
+}): Promise<MpvInputBindingsSnapshot> {
+  const blockedKeys = deps.getConfiguredKeybindings().flatMap((binding) => {
+    const { key } = parseSessionBindingKey(binding.key, deps.platform);
+    return key ? [key] : [];
+  });
+  const client = deps.getMpvClient();
+  if (!client?.connected) return { keys: [], blockedKeys };
+  try {
+    const value = await client.requestProperty('input-bindings');
+    return {
+      keys:
+        client === deps.getMpvClient() && client.connected ? parseMpvInputBindingKeys(value) : [],
+      blockedKeys,
+    };
+  } catch {
+    // Older mpv versions and disconnected sessions retain SubMiner's controls.
+    return { keys: [], blockedKeys };
+  }
+}
diff --git a/src/main/runtime/mpv-main-event-actions.test.ts b/src/main/runtime/mpv-main-event-actions.test.ts
index e0eb59ed..a7667143 100644
--- a/src/main/runtime/mpv-main-event-actions.test.ts
+++ b/src/main/runtime/mpv-main-event-actions.test.ts
@@ -358,6 +358,30 @@ test('time-pos handler forces Jellyfin progress when mpv position jumps', () =>
   ]);
 });
 
+test('time-pos handler treats an explicit short jump as a seek', () => {
+  const updateKinds: string[] = [];
+  let explicitSeekPending = false;
+  const timeHandler = createHandleMpvTimePosChangeHandler({
+    recordPlaybackPosition: () => {},
+    reportJellyfinRemoteProgress: () => {},
+    refreshDiscordPresence: () => {},
+    maybeRunAnilistPostWatchUpdate: async () => {},
+    consumeExplicitSeek: () => {
+      const pending = explicitSeekPending;
+      explicitSeekPending = false;
+      return pending;
+    },
+    onTimePosUpdate: (_time, kind) => updateKinds.push(kind),
+  });
+
+  timeHandler({ time: 10 });
+  explicitSeekPending = true;
+  timeHandler({ time: 11.5 });
+  timeHandler({ time: 11.6 });
+
+  assert.deepEqual(updateKinds, ['initial', 'seek', 'playback']);
+});
+
 test('time-pos handler passes fresh playback time to AniList post-watch', async () => {
   const watchedSeconds: unknown[] = [];
   const timeHandler = createHandleMpvTimePosChangeHandler({
diff --git a/src/main/runtime/mpv-main-event-actions.ts b/src/main/runtime/mpv-main-event-actions.ts
index 3e304a7e..ab0b4577 100644
--- a/src/main/runtime/mpv-main-event-actions.ts
+++ b/src/main/runtime/mpv-main-event-actions.ts
@@ -4,6 +4,8 @@ type AnilistPostWatchRunOptions = {
   watchedSeconds?: number;
 };
 
+type TimePosUpdateKind = 'initial' | 'playback' | 'seek';
+
 /** Jump size that marks a time-pos change as a seek rather than normal playback. */
 export const SEEK_LIKE_TIME_DELTA_SECONDS = 2.5;
 
@@ -138,12 +140,20 @@ export function createHandleMpvTimePosChangeHandler(deps: {
   refreshDiscordPresence: () => void;
   maybeRunAnilistPostWatchUpdate?: (options?: AnilistPostWatchRunOptions) => Promise<void>;
   logError?: (message: string, error: unknown) => void;
-  onTimePosUpdate?: (time: number) => void;
+  onTimePosUpdate?: (time: number, kind: TimePosUpdateKind) => void;
+  consumeExplicitSeek?: () => boolean;
 }) {
   let lastObservedTime: number | null = null;
 
   return ({ time }: { time: number }): void => {
-    const forceImmediate = isSeekLikeTimeChange(lastObservedTime, time);
+    const explicitSeek = deps.consumeExplicitSeek?.() ?? false;
+    const updateKind: TimePosUpdateKind =
+      lastObservedTime === null
+        ? 'initial'
+        : explicitSeek || isSeekLikeTimeChange(lastObservedTime, time)
+          ? 'seek'
+          : 'playback';
+    const forceImmediate = updateKind === 'seek';
     if (Number.isFinite(time)) {
       lastObservedTime = time;
     }
@@ -153,7 +163,7 @@ export function createHandleMpvTimePosChangeHandler(deps: {
     void deps.maybeRunAnilistPostWatchUpdate?.({ watchedSeconds: time }).catch((error) => {
       deps.logError?.('AniList post-watch update failed unexpectedly', error);
     });
-    deps.onTimePosUpdate?.(time);
+    deps.onTimePosUpdate?.(time, updateKind);
   };
 }
 
diff --git a/src/main/runtime/mpv-main-event-bindings.test.ts b/src/main/runtime/mpv-main-event-bindings.test.ts
index 58db5288..82133f71 100644
--- a/src/main/runtime/mpv-main-event-bindings.test.ts
+++ b/src/main/runtime/mpv-main-event-bindings.test.ts
@@ -1,10 +1,23 @@
 import assert from 'node:assert/strict';
 import test from 'node:test';
+import { parseSubtitleCues } from '../../core/services/subtitle-cue-parser';
 import { createBindMpvMainEventHandlersHandler } from './mpv-main-event-bindings';
+import { resolvePrimarySubtitleText } from './primary-subtitle-text';
 
 test('main mpv event binder wires callbacks through to runtime deps', () => {
   const handlers = new Map<string, (payload: unknown) => void>();
   const calls: string[] = [];
+  let currentTime = 0;
+  const seekLiveText = '少しだけ好きになる\n少しだけ好きになる';
+  const seekCues = parseSubtitleCues(
+    [
+      '[Events]',
+      'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+      'Dialogue: 1,0:01:29.00,0:01:32.00,EDJP,,0,0,0,,少しだけ好きになる',
+      'Dialogue: 0,0:01:29.00,0:01:32.00,EDJP,,0,0,0,,少しだけ好きになる',
+    ].join('\n'),
+    'seek-ending.ass',
+  );
 
   const bind = createBindMpvMainEventHandlersHandler({
     reportJellyfinRemoteStopped: () => calls.push('remote-stopped'),
@@ -27,6 +40,9 @@ test('main mpv event binder wires callbacks through to runtime deps', () => {
       calls.push(`post-watch:${options?.watchedSeconds ?? 'none'}`);
     },
     logSubtitleTimingError: () => calls.push('subtitle-error'),
+    resolveSubtitleText: (liveText) =>
+      resolvePrimarySubtitleText({ liveText, currentTimeSec: currentTime, cues: seekCues }),
+    getCurrentLiveSubtitleText: () => seekLiveText,
     setCurrentSubText: (text) => calls.push(`set-sub:${text}`),
     getImmediateSubtitlePayload: (text) => ({ text, tokens: [] }),
     broadcastSubtitle: (payload) => calls.push(`broadcast-sub:${payload.text}`),
@@ -60,6 +76,9 @@ test('main mpv event binder wires callbacks through to runtime deps', () => {
     recordMediaDuration: (duration) => calls.push(`duration:${duration}`),
     reportJellyfinRemoteProgress: (forceImmediate) =>
       calls.push(`progress:${forceImmediate ? 'force' : 'normal'}`),
+    onTimePosUpdate: (time) => {
+      currentTime = time;
+    },
     recordPauseState: (paused) => calls.push(`pause:${paused ? 'yes' : 'no'}`),
 
     updateSubtitleRenderMetrics: () => calls.push('subtitle-metrics'),
@@ -83,7 +102,13 @@ test('main mpv event binder wires callbacks through to runtime deps', () => {
   handlers.get('media-path-change')?.({ path: '' });
   handlers.get('media-title-change')?.({ title: 'Episode 1' });
   handlers.get('subtitle-timing')?.({ text: 'timed line', start: 899, end: 901 });
+  handlers.get('subtitle-change')?.({ text: seekLiveText });
+  handlers.get('time-pos-change')?.({ time: 90 });
+  assert.ok(calls.includes('set-sub:少しだけ好きになる'));
+
   handlers.get('time-pos-change')?.({ time: 2.5 });
+  handlers.get('subtitle-change')?.({ text: seekLiveText });
+  handlers.get('time-pos-change')?.({ time: 90 });
   handlers.get('pause-change')?.({ paused: true });
 
   assert.ok(calls.includes('set-sub:line'));
diff --git a/src/main/runtime/mpv-main-event-bindings.ts b/src/main/runtime/mpv-main-event-bindings.ts
index d217652c..f4eee996 100644
--- a/src/main/runtime/mpv-main-event-bindings.ts
+++ b/src/main/runtime/mpv-main-event-bindings.ts
@@ -44,6 +44,7 @@ export function createBindMpvMainEventHandlersHandler(deps: {
 
   setCurrentSubText: (text: string) => void;
   resolveSubtitleText?: (text: string) => string;
+  getCurrentLiveSubtitleText?: () => string;
   getImmediateSubtitlePayload?: (text: string) => SubtitleData | null;
   emitImmediateSubtitle?: (payload: SubtitleData) => void;
   broadcastSubtitle: (payload: SubtitleData) => void;
@@ -78,6 +79,7 @@ export function createBindMpvMainEventHandlersHandler(deps: {
   recordMediaDuration: (durationSec: number) => void;
   reportJellyfinRemoteProgress: (forceImmediate: boolean) => void;
   onTimePosUpdate?: (time: number) => void;
+  consumeExplicitSeek?: () => boolean;
   onFullscreenChange?: (fullscreen: boolean) => void;
   recordPauseState: (paused: boolean) => void;
 
@@ -171,7 +173,15 @@ export function createBindMpvMainEventHandlersHandler(deps: {
       refreshDiscordPresence: () => deps.refreshDiscordPresence(),
       maybeRunAnilistPostWatchUpdate: (options) => deps.maybeRunAnilistPostWatchUpdate(options),
       logError: (message, error) => deps.logSubtitleTimingError(message, error),
-      onTimePosUpdate: (time) => deps.onTimePosUpdate?.(time),
+      consumeExplicitSeek: deps.consumeExplicitSeek,
+      onTimePosUpdate: (time, updateKind) => {
+        deps.onTimePosUpdate?.(time);
+        if (updateKind === 'playback') return;
+        const liveText = deps.getCurrentLiveSubtitleText?.();
+        if (liveText !== undefined) {
+          handleMpvSubtitleChange({ text: liveText });
+        }
+      },
     });
     const handleMpvPauseChange = createHandleMpvPauseChangeHandler({
       recordPauseState: (paused) => deps.recordPauseState(paused),
diff --git a/src/main/runtime/mpv-main-event-main-deps.test.ts b/src/main/runtime/mpv-main-event-main-deps.test.ts
index 910882d1..3f97c7e3 100644
--- a/src/main/runtime/mpv-main-event-main-deps.test.ts
+++ b/src/main/runtime/mpv-main-event-main-deps.test.ts
@@ -1,5 +1,6 @@
 import assert from 'node:assert/strict';
 import test from 'node:test';
+import { parseAssCues } from '../../core/services/subtitle-cue-parser';
 import { createBuildBindMpvMainEventHandlersMainDepsHandler } from './mpv-main-event-main-deps';
 
 test('mpv main event main deps map app state updates and delegate callbacks', async () => {
@@ -426,6 +427,13 @@ test('canonical ASS cues replace live glyph spam for display, history, and immer
           text: '飛び越えてみたくて',
           source: 'canonical-ass',
         },
+        {
+          startTime: 10,
+          endTime: 12,
+          text: 'MaidCafeMaidCafe',
+          source: 'reconstructed-ass',
+          assLayout: { kind: 'fragment-grid', sourceOrder: 2 },
+        },
       ],
       currentMediaPath: '/video.mkv',
       currentSubText: '',
@@ -496,13 +504,25 @@ test('canonical ASS cues replace live glyph spam for display, history, and immer
   assert.deepEqual(timing.slice(3), [{ text: '今　手にある物差しでは', start: 1.2, end: 3.8 }]);
   assert.equal(immersion.length, 3);
 
-  // A jump of exactly the seek threshold counts as a seek, matching the time-pos
-  // handler's own `>=` boundary.
-  handlers.onTimePosUpdate?.(4.5);
-  handlers.onTimePosUpdate?.(2);
+  // Jumping back to a brief previous line moves time-pos by less than the general
+  // seek threshold. It is still a backward seek, so the revisited line records
+  // again; otherwise multi-line copy would keep treating the later line as current.
+  handlers.onTimePosUpdate?.(3.9);
+  handlers.onTimePosUpdate?.(2.9);
   handlers.recordSubtitleTiming('今', 0.8, 1.5);
 
   assert.deepEqual(timing.slice(4), [{ text: '今　手にある物差しでは', start: 1.2, end: 3.8 }]);
+
+  // Tiny time-pos jitter is not a seek and must not re-record the line.
+  handlers.onTimePosUpdate?.(3.0);
+  handlers.onTimePosUpdate?.(2.9);
+  handlers.recordSubtitleTiming('今', 0.8, 1.5);
+  assert.equal(timing.length, 5);
+
+  handlers.recordImmersionSubtitleLine('Maid\nCafe', 10, 12);
+  handlers.recordSubtitleTiming('Maid\nCafe', 10, 12);
+  assert.equal(immersion.length, 3);
+  assert.equal(timing.length, 5);
 });
 
 test('subtitle-track changes stop stale canonical cues from substituting immediately', () => {
@@ -563,3 +583,156 @@ test('subtitle-track changes stop stale canonical cues from substituting immedia
   assert.equal(appState.activeParsedSubtitleSource, null);
   assert.equal(handlers.resolveSubtitleText?.('今\n手にある'), '今\n手にある');
 });
+
+test('subtitle recorders drop ASS furigana events the same way the display does', () => {
+  // Broadcast-caption ASS (Caption2Ass style): furigana are separate half-scale events
+  // positioned above their base line, and mpv lists them as their own live lines.
+  const cues = parseAssCues(
+    [
+      '[Script Info]',
+      'PlayResX: 960',
+      'PlayResY: 540',
+      '',
+      '[V4+ Styles]',
+      'Format: Name, Fontname, Fontsize, PrimaryColour, SecondaryColour, OutlineColour, BackColour, Bold, Italic, Underline, StrikeOut, ScaleX, ScaleY, Spacing, Angle, BorderStyle, Outline, Shadow, Alignment, MarginL, MarginR, MarginV, Encoding',
+      'Style: Default,Yu Gothic,46,&H00FFFFFF,&H000000FF,&H00000000,&H7F000000,1,0,0,0,100,100,4,0,1,2,2,1,0,0,0,1',
+      '',
+      '[Events]',
+      'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+      'Dialogue: 0,0:04:56.26,0:04:59.63,Default,,0000,0000,0000,,{\\pos(472,443)\\fscx50\\fscy50}あくむ',
+      'Dialogue: 0,0:04:56.26,0:04:59.63,Default,,0000,0000,0000,,{\\pos(172,497)}こんな短時間で{\\fscx50}　{\\fscx100}悪夢{\\fscx50}　{\\fscx100}見んなよ{\\fscx50}。',
+      'Dialogue: 0,0:04:59.63,0:05:03.54,Default,,0000,0000,0000,,{\\pos(172,407)\\fscx50}（{\\fscx100}平{\\fscx50}）{\\fscx100}暗記教科は{\\fscx50}　{\\fscx100}もう',
+      'Dialogue: 0,0:04:59.63,0:05:03.54,Default,,0000,0000,0000,,{\\pos(332,443)\\fscx50\\fscy50}かた',
+      'Dialogue: 0,0:04:59.63,0:05:03.54,Default,,0000,0000,0000,,{\\pos(412,443)\\fscx50\\fscy50}ぱし',
+      'Dialogue: 0,0:04:59.63,0:05:03.54,Default,,0000,0000,0000,,{\\pos(172,497)}とにかく片っ端から覚えるんだよ{\\fscx50}。',
+    ].join('\n'),
+  );
+  assert.deepEqual(
+    cues.map((cue) => cue.text),
+    [
+      'こんな短時間で　悪夢　見んなよ。',
+      '（平）暗記教科は　もう',
+      'とにかく片っ端から覚えるんだよ。',
+    ],
+  );
+
+  const immersion: string[] = [];
+  const timing: string[] = [];
+  const handlers = createBuildBindMpvMainEventHandlersMainDepsHandler({
+    appState: {
+      initialArgs: null,
+      overlayRuntimeInitialized: true,
+      mpvClient: { currentTimePos: 299.7 },
+      immersionTracker: { recordSubtitleLine: (text: string) => immersion.push(text) },
+      subtitleTimingTracker: { recordSubtitle: (text: string) => timing.push(text) },
+      activeParsedSubtitleCues: cues,
+      currentSubText: '',
+      currentSubAssText: '',
+      playbackPaused: null,
+      previousSecondarySubVisibility: false,
+    },
+    getQuitOnDisconnectArmed: () => false,
+    scheduleQuitCheck: () => {},
+    quitApp: () => {},
+    reportJellyfinRemoteStopped: () => {},
+    syncOverlayMpvSubtitleSuppression: () => {},
+    maybeRunAnilistPostWatchUpdate: async () => {},
+    logSubtitleTimingError: () => {},
+    broadcastToOverlayWindows: () => {},
+    onSubtitleChange: () => {},
+    ensureImmersionTrackerInitialized: () => {},
+    updateCurrentMediaPath: () => {},
+    restoreMpvSubVisibility: () => {},
+    getCurrentAnilistMediaKey: () => null,
+    resetAnilistMediaTracking: () => {},
+    maybeProbeAnilistDuration: () => {},
+    ensureAnilistMediaGuess: () => {},
+    syncImmersionMediaState: () => {},
+    updateCurrentMediaTitle: () => {},
+    resetAnilistMediaGuessState: () => {},
+    reportJellyfinRemoteProgress: () => {},
+    updateSubtitleRenderMetrics: () => {},
+    refreshDiscordPresence: () => {},
+  })();
+
+  const liveText = '（平）暗記教科は　もう\nかた\nぱし\nとにかく片っ端から覚えるんだよ。';
+  const expected = '（平）暗記教科は　もう\n\nとにかく片っ端から覚えるんだよ。';
+  assert.equal(handlers.resolveSubtitleText?.(liveText), expected);
+  handlers.recordImmersionSubtitleLine(liveText, 299.63, 303.54);
+  handlers.recordSubtitleTiming(liveText, 299.63, 303.54);
+
+  assert.deepEqual(immersion, [expected]);
+  assert.deepEqual(timing, [expected]);
+});
+
+test('a resolved line survives recording while a fragment grid is on screen', () => {
+  // Fragment stripping drops every line it can trace back to a cue, and returns nothing
+  // at all when a fragment grid is nearby. Text the parsed cues already resolved is a
+  // complete line, not raw mpv output, so it must not be fed through that path.
+  const immersion: string[] = [];
+  const timing: string[] = [];
+  const handlers = createBuildBindMpvMainEventHandlersMainDepsHandler({
+    appState: {
+      initialArgs: null,
+      overlayRuntimeInitialized: true,
+      mpvClient: { currentTimePos: 3.2 },
+      immersionTracker: { recordSubtitleLine: (text: string) => immersion.push(text) },
+      subtitleTimingTracker: { recordSubtitle: (text: string) => timing.push(text) },
+      activeParsedSubtitleCues: [
+        { startTime: 3, endTime: 6, text: '飛び越えてみたくて', source: 'canonical-ass' },
+        {
+          startTime: 3,
+          endTime: 6,
+          text: 'MaidCafeMaidCafe',
+          source: 'reconstructed-ass',
+          assLayout: { kind: 'fragment-grid', sourceOrder: 2 },
+        },
+      ],
+      currentSubText: '',
+      currentSubAssText: '',
+      playbackPaused: null,
+      previousSecondarySubVisibility: false,
+    },
+    getQuitOnDisconnectArmed: () => false,
+    scheduleQuitCheck: () => {},
+    quitApp: () => {},
+    reportJellyfinRemoteStopped: () => {},
+    syncOverlayMpvSubtitleSuppression: () => {},
+    maybeRunAnilistPostWatchUpdate: async () => {},
+    logSubtitleTimingError: () => {},
+    broadcastToOverlayWindows: () => {},
+    onSubtitleChange: () => {},
+    ensureImmersionTrackerInitialized: () => {},
+    updateCurrentMediaPath: () => {},
+    restoreMpvSubVisibility: () => {},
+    getCurrentAnilistMediaKey: () => null,
+    resetAnilistMediaTracking: () => {},
+    maybeProbeAnilistDuration: () => {},
+    ensureAnilistMediaGuess: () => {},
+    syncImmersionMediaState: () => {},
+    updateCurrentMediaTitle: () => {},
+    resetAnilistMediaGuessState: () => {},
+    reportJellyfinRemoteProgress: () => {},
+    updateSubtitleRenderMetrics: () => {},
+    refreshDiscordPresence: () => {},
+  })();
+
+  // The grid fragment beside the lyric keeps canonical substitution from applying, so
+  // recording falls to the parsed view -- which is where the whole line is recovered.
+  const liveText = '飛び越え\nMaid';
+  assert.equal(handlers.resolveSubtitleText?.(liveText), '飛び越えてみたくて');
+  handlers.recordImmersionSubtitleLine(liveText, 3, 6);
+  handlers.recordSubtitleTiming(liveText, 3, 6);
+
+  assert.deepEqual(immersion, ['飛び越えてみたくて']);
+  assert.deepEqual(timing, ['飛び越えてみたくて']);
+
+  // A spacer event left as literal control debris is not a subtitle line. The display
+  // drops it, so no recorder may keep it either.
+  assert.equal(handlers.resolveSubtitleText?.('\\'), '');
+  handlers.recordImmersionSubtitleLine('\\', 3, 6);
+  handlers.recordSubtitleTiming('\\', 3, 6);
+
+  assert.equal(immersion.length, 1);
+  assert.equal(timing.length, 1);
+});
diff --git a/src/main/runtime/mpv-main-event-main-deps.ts b/src/main/runtime/mpv-main-event-main-deps.ts
index 467ced81..a7bd5d6c 100644
--- a/src/main/runtime/mpv-main-event-main-deps.ts
+++ b/src/main/runtime/mpv-main-event-main-deps.ts
@@ -1,10 +1,9 @@
 import { createSubtitleLineDedupGate } from '../../core/services/subtitle-line-dedup-gate';
 import type { MergedToken, SubtitleCue, SubtitleData } from '../../types';
-import { SEEK_LIKE_TIME_DELTA_SECONDS } from './mpv-main-event-actions';
 import {
   resolveCanonicalPrimarySubtitle,
   resolvePrimarySubtitleText,
-  stripCanonicalFragmentLines,
+  resolveRecordedPrimarySubtitleText,
 } from './primary-subtitle-text';
 
 type AnilistPostWatchRunOptions = {
@@ -21,6 +20,7 @@ export function createBuildBindMpvMainEventHandlersMainDepsHandler(deps: {
     overlayRuntimeInitialized: boolean;
     mpvClient: {
       connected?: boolean;
+      currentSubText?: string;
       currentSecondarySubText?: string;
       currentTimePos?: number;
       requestProperty?: (name: string) => Promise<unknown>;
@@ -85,6 +85,7 @@ export function createBuildBindMpvMainEventHandlersMainDepsHandler(deps: {
   resetAnilistMediaGuessState: () => void;
   reportJellyfinRemoteProgress: (forceImmediate: boolean) => void;
   onTimePosUpdate?: (time: number) => void;
+  consumeExplicitSeek?: () => boolean;
   onFullscreenChange?: (fullscreen: boolean) => void;
   updateSubtitleRenderMetrics: (patch: Record<string, unknown>) => void;
   refreshDiscordPresence: () => void;
@@ -113,6 +114,8 @@ export function createBuildBindMpvMainEventHandlersMainDepsHandler(deps: {
   // after the change is dropped instead of landing in the next session.
   let subtitleSessionEpoch = 0;
   let lastTimePosForTimingReset: number | null = null;
+  // Small margin so time-pos jitter is not mistaken for a backward seek.
+  const BACKWARD_SEEK_TIMING_RESET_SECONDS = 0.25;
   const canonicalCueKey = (cue: SubtitleCue): string =>
     `${cue.startTime}|${cue.endTime}|${cue.text}`;
   const resetSubtitleDeduplication = (): void => {
@@ -128,10 +131,12 @@ export function createBuildBindMpvMainEventHandlersMainDepsHandler(deps: {
       currentTimeSec: startSec,
       cues: deps.appState.activeParsedSubtitleCues,
     });
-  // When substitution declined because dialogue shares the screen with a song, record
-  // the dialogue alone rather than the combined dialogue-plus-fragments stack.
-  const stripFragmentsForRecording = (liveText: string, startSec: number) =>
-    stripCanonicalFragmentLines({
+  // Recorders see the same text the overlay displays: mpv's live `sub-text` lists every
+  // simultaneously active ASS event, including furigana events the parser folded into
+  // their base line. Cues the caller already resolved canonically are recorded one by
+  // one above; everything else goes through the shared recording resolution.
+  const resolveTextForRecording = (liveText: string, startSec: number): string =>
+    resolveRecordedPrimarySubtitleText({
       liveText,
       currentTimeSec: startSec,
       cues: deps.appState.activeParsedSubtitleCues,
@@ -160,6 +165,7 @@ export function createBuildBindMpvMainEventHandlersMainDepsHandler(deps: {
         currentTimeSec: Number(deps.appState.mpvClient?.currentTimePos),
         cues: deps.appState.activeParsedSubtitleCues,
       }),
+    getCurrentLiveSubtitleText: () => deps.appState.mpvClient?.currentSubText ?? '',
     recordImmersionSubtitleLine: (text: string, start: number, end: number) => {
       deps.ensureImmersionTrackerInitialized();
       const tracker = deps.appState.immersionTracker;
@@ -214,7 +220,10 @@ export function createBuildBindMpvMainEventHandlersMainDepsHandler(deps: {
         }
         return;
       }
-      text = stripFragmentsForRecording(text, start);
+      text = resolveTextForRecording(text, start);
+      if (!text.trim()) {
+        return;
+      }
       if (!immersionLineDedupGate.shouldRecord({ text, startSec: start, endSec: end })) {
         return;
       }
@@ -225,8 +234,12 @@ export function createBuildBindMpvMainEventHandlersMainDepsHandler(deps: {
       const secondaryText = deps.appState.mpvClient?.currentSecondarySubText || undefined;
       const canonical = resolveCanonicalSample(text, start);
       if (!canonical) {
+        const recordableText = resolveTextForRecording(text, start);
+        if (!recordableText.trim()) {
+          return;
+        }
         deps.appState.subtitleTimingTracker?.recordSubtitle?.(
-          stripFragmentsForRecording(text, start),
+          recordableText,
           start,
           end,
           secondaryText,
@@ -332,14 +345,17 @@ export function createBuildBindMpvMainEventHandlersMainDepsHandler(deps: {
     },
     reportJellyfinRemoteProgress: (forceImmediate: boolean) =>
       deps.reportJellyfinRemoteProgress(forceImmediate),
+    consumeExplicitSeek: deps.consumeExplicitSeek,
     onTimePosUpdate: (time: number) => {
-      // Timing history is a viewing log: after a real backward seek, a rewatched
-      // canonical line should enter it again. Immersion stats keep their
-      // once-per-media deduplication and are not reset here.
+      // Timing history is a viewing log: after any backward seek, a rewatched canonical
+      // line should enter it again so multi-line copy treats it as the current line.
+      // Playback never moves time-pos backward on its own, so even a short jump to a
+      // brief previous line counts. Immersion stats keep their once-per-media
+      // deduplication and are not reset here.
       if (
         Number.isFinite(time) &&
         lastTimePosForTimingReset !== null &&
-        time <= lastTimePosForTimingReset - SEEK_LIKE_TIME_DELTA_SECONDS
+        time <= lastTimePosForTimingReset - BACKWARD_SEEK_TIMING_RESET_SECONDS
       ) {
         recordedTimingCanonicalKeys.clear();
       }
diff --git a/src/main/runtime/mpv-process.test.ts b/src/main/runtime/mpv-process.test.ts
new file mode 100644
index 00000000..6ab3836f
--- /dev/null
+++ b/src/main/runtime/mpv-process.test.ts
@@ -0,0 +1,39 @@
+import assert from 'node:assert/strict';
+import { once } from 'node:events';
+import test from 'node:test';
+import { resolveMpvExecutablePath, spawnMpvProcess } from './mpv-process';
+
+const testWindows = process.platform === 'win32' ? test : test.skip;
+
+test('mpv process launcher forwards arguments and environment to the child', async () => {
+  const child = spawnMpvProcess(
+    process.execPath,
+    ['-e', 'process.exit(Number(process.env.SUBMINER_TEST_EXIT))'],
+    { ...process.env, DISPLAY: '', SUBMINER_TEST_EXIT: '17' },
+  );
+  try {
+    const [code] = await once(child, 'exit');
+    assert.equal(code, 17);
+  } finally {
+    if (child.exitCode === null) child.kill();
+  }
+});
+
+testWindows('managed Windows playback launches the configured executable', async () => {
+  const executable = resolveMpvExecutablePath(`  ${process.execPath}  `);
+  const child = spawnMpvProcess(executable, ['-e', 'process.exit(17)']);
+  try {
+    assert.equal(child.spawnfile, process.execPath);
+    const [code] = await once(child, 'exit');
+    assert.equal(code, 17);
+  } finally {
+    if (child.exitCode === null) child.kill();
+  }
+});
+
+testWindows('managed Windows playback rejects an invalid configured executable', () => {
+  assert.throws(
+    () => resolveMpvExecutablePath(`${process.execPath}/missing-mpv.exe`),
+    /Could not find mpv.exe/,
+  );
+});
diff --git a/src/main/runtime/mpv-process.ts b/src/main/runtime/mpv-process.ts
new file mode 100644
index 00000000..f0e3b94c
--- /dev/null
+++ b/src/main/runtime/mpv-process.ts
@@ -0,0 +1,112 @@
+import fs from 'node:fs';
+import { spawn, spawnSync } from 'node:child_process';
+import {
+  MPV_X11_BACKEND_ARGS,
+  applyX11EnvOverrides,
+  shouldForceX11WaylandSession,
+} from '../../shared/mpv-x11-backend';
+
+export interface WindowsMpvPathDeps {
+  getEnv: (name: string) => string | undefined;
+  runWhere: () => { status: number | null; stdout: string; error?: Error };
+  fileExists: (candidate: string) => boolean;
+}
+
+export type ConfiguredWindowsMpvPathStatus = 'blank' | 'configured' | 'invalid';
+
+function fileExists(candidate: string): boolean {
+  try {
+    return fs.statSync(candidate).isFile();
+  } catch {
+    return false;
+  }
+}
+
+export function getConfiguredWindowsMpvPathStatus(
+  configuredMpvPath = '',
+  exists: (candidate: string) => boolean = fileExists,
+): ConfiguredWindowsMpvPathStatus {
+  const configPath = configuredMpvPath.trim();
+  if (!configPath) {
+    return 'blank';
+  }
+  return exists(configPath) ? 'configured' : 'invalid';
+}
+
+export function createWindowsMpvPathDeps(
+  overrides: Partial<WindowsMpvPathDeps> = {},
+): WindowsMpvPathDeps {
+  return {
+    getEnv: overrides.getEnv ?? ((name) => process.env[name]),
+    fileExists: overrides.fileExists ?? fileExists,
+    runWhere:
+      overrides.runWhere ??
+      (() => {
+        const result = spawnSync('where.exe', ['mpv.exe'], {
+          encoding: 'utf8',
+          windowsHide: true,
+        });
+        return {
+          status: result.status,
+          stdout: result.stdout ?? '',
+          error: result.error ?? undefined,
+        };
+      }),
+  };
+}
+
+export function resolveWindowsMpvPath(deps: WindowsMpvPathDeps, configuredMpvPath = ''): string {
+  const configPath = configuredMpvPath.trim();
+  const configuredPathStatus = getConfiguredWindowsMpvPathStatus(configPath, deps.fileExists);
+  if (configuredPathStatus === 'configured') {
+    return configPath;
+  }
+  if (configuredPathStatus === 'invalid') {
+    return '';
+  }
+
+  const envPath = deps.getEnv('SUBMINER_MPV_PATH')?.trim();
+  if (envPath && deps.fileExists(envPath)) {
+    return envPath;
+  }
+
+  const whereResult = deps.runWhere();
+  if (whereResult.status === 0) {
+    const firstPath = whereResult.stdout
+      .split(/\r?\n/)
+      .map((line) => line.trim())
+      .find((line) => line.length > 0 && deps.fileExists(line));
+    if (firstPath) {
+      return firstPath;
+    }
+  }
+
+  return '';
+}
+
+export function spawnMpvProcess(
+  executablePath: string,
+  args: string[],
+  env: NodeJS.ProcessEnv = process.env,
+): ReturnType<typeof spawn> {
+  const forceX11 = shouldForceX11WaylandSession(env);
+  return spawn(executablePath, forceX11 ? [...args, ...MPV_X11_BACKEND_ARGS] : args, {
+    detached: true,
+    stdio: 'ignore',
+    windowsHide: true,
+    env: forceX11 ? applyX11EnvOverrides({ ...env }) : env,
+  });
+}
+
+export function resolveMpvExecutablePath(configuredMpvPath = ''): string {
+  const executablePath =
+    process.platform === 'win32'
+      ? resolveWindowsMpvPath(createWindowsMpvPathDeps(), configuredMpvPath)
+      : 'mpv';
+  if (!executablePath) {
+    throw new Error(
+      'Could not find mpv.exe. Check mpv.executablePath, SUBMINER_MPV_PATH, or PATH.',
+    );
+  }
+  return executablePath;
+}
diff --git a/src/main/runtime/network-media-path.test.ts b/src/main/runtime/network-media-path.test.ts
new file mode 100644
index 00000000..002667f1
--- /dev/null
+++ b/src/main/runtime/network-media-path.test.ts
@@ -0,0 +1,64 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { createRemoteMediaPathDetector } from './network-media-path';
+
+test('remote media detector recognizes mounted network filesystems', async () => {
+  const detectRemoteMedia = createRemoteMediaPathDetector({
+    platform: 'darwin',
+    readMountOutput: async () =>
+      [
+        '/dev/disk3s5 on /System/Volumes/Data (apfs, local, journaled)',
+        '//viewer@media/jellyfin on /Volumes/jellyfin (smbfs, nodev, nosuid)',
+      ].join('\n'),
+  });
+
+  assert.equal(await detectRemoteMedia('/Volumes/jellyfin/movie.mkv'), true);
+  assert.equal(await detectRemoteMedia('/Volumes/jellyfin-another/movie.mkv'), false);
+  assert.equal(await detectRemoteMedia('/Users/viewer/movie.mkv'), false);
+});
+
+test('remote media detector recognizes Linux network mount output', async () => {
+  const detectRemoteMedia = createRemoteMediaPathDetector({
+    platform: 'linux',
+    readMountOutput: async () =>
+      '//media/jellyfin on /mnt/Jellyfin\\040Media type cifs (rw,relatime)',
+  });
+
+  assert.equal(await detectRemoteMedia('/mnt/Jellyfin Media/movie.mkv'), true);
+});
+
+test('remote media detector shares its mount lookup between concurrent callers', async () => {
+  let mountReads = 0;
+  const detectRemoteMedia = createRemoteMediaPathDetector({
+    platform: 'darwin',
+    readMountOutput: async () => {
+      mountReads += 1;
+      return '//viewer@media/jellyfin on /Volumes/jellyfin (smbfs, nodev, nosuid)';
+    },
+  });
+
+  const results = await Promise.all(
+    Array.from({ length: 6 }, () => detectRemoteMedia('/Volumes/jellyfin/movie.mkv')),
+  );
+
+  assert.deepEqual(
+    results,
+    Array.from({ length: 6 }, () => true),
+  );
+  assert.equal(mountReads, 1);
+});
+
+test('remote media detector recognizes URLs and Windows UNC paths without reading mounts', async () => {
+  let mountReads = 0;
+  const detectRemoteMedia = createRemoteMediaPathDetector({
+    platform: 'win32',
+    readMountOutput: async () => {
+      mountReads += 1;
+      return '';
+    },
+  });
+
+  assert.equal(await detectRemoteMedia('https://media.example/movie.mkv'), true);
+  assert.equal(await detectRemoteMedia('\\\\media-server\\jellyfin\\movie.mkv'), true);
+  assert.equal(mountReads, 0);
+});
diff --git a/src/main/runtime/network-media-path.ts b/src/main/runtime/network-media-path.ts
new file mode 100644
index 00000000..9f282821
--- /dev/null
+++ b/src/main/runtime/network-media-path.ts
@@ -0,0 +1,142 @@
+import { execFile } from 'node:child_process';
+import path from 'node:path';
+import process from 'node:process';
+import { resolveSubtitleSourcePath } from './subtitle-prefetch-source';
+
+const DEFAULT_MOUNT_CACHE_TTL_MS = 5_000;
+const NETWORK_FILESYSTEM_TYPES = new Set([
+  '9p',
+  'afpfs',
+  'cifs',
+  'davfs',
+  'davfs2',
+  'fuse.sshfs',
+  'nfs',
+  'nfs4',
+  'smbfs',
+  'sshfs',
+  'webdav',
+]);
+
+function isRemoteUrl(value: string): boolean {
+  try {
+    const url = new URL(value);
+    return url.protocol === 'http:' || url.protocol === 'https:';
+  } catch {
+    return false;
+  }
+}
+
+function decodeMountPath(value: string): string {
+  return value.replace(/\\([0-7]{3})/g, (_match, digits: string) =>
+    String.fromCharCode(Number.parseInt(digits, 8)),
+  );
+}
+
+function parseNetworkMountPaths(output: string): string[] {
+  const networkMountPaths: string[] = [];
+  for (const line of output.split('\n')) {
+    const optionsStart = line.lastIndexOf(' (');
+    if (optionsStart < 0) continue;
+
+    let mountDescription = line.slice(0, optionsStart);
+    const options = line.slice(optionsStart + 2, line.indexOf(')', optionsStart));
+    const linuxTypeSeparator = mountDescription.lastIndexOf(' type ');
+    const filesystemType = (
+      linuxTypeSeparator >= 0
+        ? mountDescription.slice(linuxTypeSeparator + ' type '.length)
+        : (options.split(',').at(0) ?? '')
+    )
+      .trim()
+      .toLowerCase();
+    if (!NETWORK_FILESYSTEM_TYPES.has(filesystemType)) continue;
+
+    if (linuxTypeSeparator >= 0) {
+      mountDescription = mountDescription.slice(0, linuxTypeSeparator);
+    }
+    const mountSeparator = mountDescription.indexOf(' on ');
+    if (mountSeparator < 0) continue;
+    networkMountPaths.push(
+      path.posix.normalize(decodeMountPath(mountDescription.slice(mountSeparator + 4).trim())),
+    );
+  }
+  return networkMountPaths;
+}
+
+function readMountOutput(platform: NodeJS.Platform): Promise<string> {
+  if (platform === 'win32') return Promise.resolve('');
+  const command = platform === 'darwin' ? '/sbin/mount' : 'mount';
+  return new Promise((resolve, reject) => {
+    execFile(
+      command,
+      [],
+      { encoding: 'utf8', timeout: 1_000, maxBuffer: 1024 * 1024 },
+      (error, stdout) => {
+        if (error) {
+          reject(error);
+          return;
+        }
+        resolve(stdout);
+      },
+    );
+  });
+}
+
+function isPathWithinMount(filePath: string, mountPath: string): boolean {
+  const relativePath = path.posix.relative(mountPath, filePath);
+  return (
+    relativePath === '' ||
+    (relativePath !== '..' &&
+      !relativePath.startsWith(`..${path.posix.sep}`) &&
+      !path.posix.isAbsolute(relativePath))
+  );
+}
+
+export type RemoteMediaPathDetector = (mediaPath: string) => Promise<boolean>;
+
+export function createRemoteMediaPathDetector(
+  deps: {
+    platform?: NodeJS.Platform;
+    readMountOutput?: () => Promise<string>;
+    now?: () => number;
+    mountCacheTtlMs?: number;
+  } = {},
+): RemoteMediaPathDetector {
+  const platform = deps.platform ?? process.platform;
+  const getMountOutput = deps.readMountOutput ?? (() => readMountOutput(platform));
+  const now = deps.now ?? Date.now;
+  const mountCacheTtlMs = deps.mountCacheTtlMs ?? DEFAULT_MOUNT_CACHE_TTL_MS;
+  let mountCache: { expiresAt: number; networkMountPaths: Promise<readonly string[]> } | undefined;
+
+  const getNetworkMountPaths = (): Promise<readonly string[]> => {
+    const currentTime = now();
+    if (mountCache && currentTime < mountCache.expiresAt) {
+      return mountCache.networkMountPaths;
+    }
+
+    const networkMountPaths = getMountOutput()
+      .then(parseNetworkMountPaths)
+      .catch(() => []);
+    mountCache = {
+      expiresAt: currentTime + mountCacheTtlMs,
+      networkMountPaths,
+    };
+    return networkMountPaths;
+  };
+
+  return async (mediaPath): Promise<boolean> => {
+    const source = mediaPath.trim();
+    if (!source) return false;
+    if (isRemoteUrl(source)) return true;
+
+    const filePath = resolveSubtitleSourcePath(source);
+    if (platform === 'win32') {
+      return filePath.startsWith('\\\\');
+    }
+    if (!path.posix.isAbsolute(filePath)) return false;
+
+    const networkMountPaths = await getNetworkMountPaths();
+    const normalizedPath = path.posix.normalize(filePath);
+    return networkMountPaths.some((mountPath) => isPathWithinMount(normalizedPath, mountPath));
+  };
+}
diff --git a/src/main/runtime/overlay-hosted-modal-open.test.ts b/src/main/runtime/overlay-hosted-modal-open.test.ts
index adaa8552..09913807 100644
--- a/src/main/runtime/overlay-hosted-modal-open.test.ts
+++ b/src/main/runtime/overlay-hosted-modal-open.test.ts
@@ -1,6 +1,77 @@
 import assert from 'node:assert/strict';
 import test from 'node:test';
-import { openOverlayHostedModal } from './overlay-hosted-modal-open';
+import { openOverlayHostedModal, retryOverlayModalOpen } from './overlay-hosted-modal-open';
+
+test('retryOverlayModalOpen skips the first send when already aborted', async () => {
+  const controller = new AbortController();
+  controller.abort();
+  const unexpectedCall = () => assert.fail('aborted open must not send or wait');
+  assert.equal(
+    await retryOverlayModalOpen(
+      { waitForModalOpen: unexpectedCall, logWarn: unexpectedCall },
+      {
+        modal: 'media-timing-review',
+        timeoutMs: 4_000,
+        retryWarning: 'retry',
+        sendOpen: unexpectedCall,
+        signal: controller.signal,
+      },
+    ),
+    false,
+  );
+});
+
+for (const abortOnWait of [1, 2]) {
+  test(`retryOverlayModalOpen rejects an acknowledgement aborted during wait ${abortOnWait}`, async () => {
+    const controller = new AbortController();
+    let waitCalls = 0;
+    let sendCalls = 0;
+    const opened = await retryOverlayModalOpen(
+      {
+        waitForModalOpen: async () => {
+          waitCalls += 1;
+          if (waitCalls === abortOnWait) {
+            controller.abort();
+            return true;
+          }
+          return false;
+        },
+        logWarn: () => {},
+      },
+      {
+        modal: 'media-timing-review',
+        timeoutMs: 4_000,
+        retryWarning: 'retry',
+        sendOpen: () => {
+          sendCalls += 1;
+          return true;
+        },
+        signal: controller.signal,
+      },
+    );
+    assert.equal(opened, false);
+    assert.equal(sendCalls, abortOnWait);
+    assert.equal(waitCalls, abortOnWait);
+  });
+}
+
+test('retryOverlayModalOpen still retries other modals without a signal', async () => {
+  let sendCalls = 0;
+  const opened = await retryOverlayModalOpen(
+    { waitForModalOpen: async () => sendCalls === 2, logWarn: () => {} },
+    {
+      modal: 'runtime-options',
+      timeoutMs: 1_500,
+      retryWarning: 'retry',
+      sendOpen: () => {
+        sendCalls += 1;
+        return true;
+      },
+    },
+  );
+  assert.equal(opened, true);
+  assert.equal(sendCalls, 2);
+});
 
 test('openOverlayHostedModal ensures overlay readiness before sending the open event', () => {
   const calls: string[] = [];
diff --git a/src/main/runtime/overlay-hosted-modal-open.ts b/src/main/runtime/overlay-hosted-modal-open.ts
index 15366ae8..f19b30f4 100644
--- a/src/main/runtime/overlay-hosted-modal-open.ts
+++ b/src/main/runtime/overlay-hosted-modal-open.ts
@@ -38,20 +38,24 @@ export async function retryOverlayModalOpen(
     timeoutMs: number;
     retryWarning: string;
     sendOpen: () => boolean;
+    signal?: AbortSignal;
   },
 ): Promise<boolean> {
-  if (!input.sendOpen()) {
+  if (input.signal?.aborted || !input.sendOpen()) {
     return false;
   }
 
-  if (await deps.waitForModalOpen(input.modal, input.timeoutMs)) {
+  const opened = await deps.waitForModalOpen(input.modal, input.timeoutMs);
+  if (input.signal?.aborted) return false;
+  if (opened) {
     return true;
   }
 
   deps.logWarn(input.retryWarning);
-  if (!input.sendOpen()) {
+  if (input.signal?.aborted || !input.sendOpen()) {
     return false;
   }
 
-  return await deps.waitForModalOpen(input.modal, input.timeoutMs);
+  const retryOpened = await deps.waitForModalOpen(input.modal, input.timeoutMs);
+  return !input.signal?.aborted && retryOpened;
 }
diff --git a/src/main/runtime/overlay-runtime-bootstrap.ts b/src/main/runtime/overlay-runtime-bootstrap.ts
index 287fba85..6266d394 100644
--- a/src/main/runtime/overlay-runtime-bootstrap.ts
+++ b/src/main/runtime/overlay-runtime-bootstrap.ts
@@ -26,6 +26,7 @@ type InitializeOverlayRuntimeCore = (options: {
   } | null;
   setAnkiIntegration: (integration: unknown | null) => void;
   showDesktopNotification: (title: string, options: { body?: string; icon?: string }) => void;
+  dismissOverlayNotification?: (id: string) => void;
   createFieldGroupingCallback: () => (
     data: KikuFieldGroupingRequestData,
   ) => Promise<KikuFieldGroupingChoice>;
diff --git a/src/main/runtime/overlay-runtime-options-main-deps.test.ts b/src/main/runtime/overlay-runtime-options-main-deps.test.ts
index 83f7f895..c6d48569 100644
--- a/src/main/runtime/overlay-runtime-options-main-deps.test.ts
+++ b/src/main/runtime/overlay-runtime-options-main-deps.test.ts
@@ -33,6 +33,8 @@ test('overlay runtime main deps builder maps runtime state and callbacks', () =>
     getOverlayWindows: () => [],
     getResolvedConfig: () => ({}),
     showDesktopNotification: () => calls.push('notify'),
+    showOverlayNotification: () => calls.push('show-overlay'),
+    dismissOverlayNotification: () => calls.push('dismiss-overlay'),
     createFieldGroupingCallback: () => async () => ({
       keepNoteId: 1,
       deleteNoteId: 2,
@@ -57,6 +59,8 @@ test('overlay runtime main deps builder maps runtime state and callbacks', () =>
   deps.refreshCurrentSubtitle?.();
   deps.syncOverlayShortcuts();
   deps.showDesktopNotification('title', {});
+  deps.showOverlayNotification?.({ title: 'title' });
+  deps.dismissOverlayNotification?.('notification-id');
 
   const tracker = {
     close: () => {},
@@ -73,6 +77,8 @@ test('overlay runtime main deps builder maps runtime state and callbacks', () =>
     'refresh-subtitle',
     'sync-shortcuts',
     'notify',
+    'show-overlay',
+    'dismiss-overlay',
   ]);
   assert.equal(appState.windowTracker, tracker);
   assert.deepEqual(appState.ankiIntegration, { id: 'anki' });
diff --git a/src/main/runtime/overlay-runtime-options-main-deps.ts b/src/main/runtime/overlay-runtime-options-main-deps.ts
index a9150f91..d3000b2d 100644
--- a/src/main/runtime/overlay-runtime-options-main-deps.ts
+++ b/src/main/runtime/overlay-runtime-options-main-deps.ts
@@ -39,6 +39,7 @@ export function createBuildInitializeOverlayRuntimeMainDepsHandler(deps: {
   getResolvedConfig: () => { ankiConnect?: AnkiConnectConfig };
   showDesktopNotification: (title: string, options: { body?: string; icon?: string }) => void;
   showOverlayNotification?: (payload: OverlayNotificationPayload) => void;
+  dismissOverlayNotification?: (id: string) => void;
   createFieldGroupingCallback: OverlayRuntimeOptionsMainDeps['createFieldGroupingCallback'];
   getKnownWordCacheStatePath: () => string;
   getCachedMediaPath?: OverlayRuntimeOptionsMainDeps['getCachedMediaPath'];
@@ -78,6 +79,7 @@ export function createBuildInitializeOverlayRuntimeMainDepsHandler(deps: {
     },
     showDesktopNotification: deps.showDesktopNotification,
     showOverlayNotification: deps.showOverlayNotification,
+    dismissOverlayNotification: deps.dismissOverlayNotification,
     createFieldGroupingCallback: () => deps.createFieldGroupingCallback(),
     getKnownWordCacheStatePath: () => deps.getKnownWordCacheStatePath(),
     ...(deps.getCachedMediaPath ? { getCachedMediaPath: deps.getCachedMediaPath } : {}),
diff --git a/src/main/runtime/overlay-runtime-options.test.ts b/src/main/runtime/overlay-runtime-options.test.ts
index 90a35960..2886aa6a 100644
--- a/src/main/runtime/overlay-runtime-options.test.ts
+++ b/src/main/runtime/overlay-runtime-options.test.ts
@@ -22,6 +22,8 @@ test('build initialize overlay runtime options maps dependencies', () => {
     getRuntimeOptionsManager: () => null,
     setAnkiIntegration: () => calls.push('set-anki'),
     showDesktopNotification: () => calls.push('notify'),
+    showOverlayNotification: () => calls.push('show-overlay'),
+    dismissOverlayNotification: () => calls.push('dismiss-overlay'),
     createFieldGroupingCallback: () => async () => ({
       keepNoteId: 1,
       deleteNoteId: 2,
@@ -47,6 +49,8 @@ test('build initialize overlay runtime options maps dependencies', () => {
   options.setWindowTracker(null);
   options.setAnkiIntegration(null);
   options.showDesktopNotification('title', {});
+  options.showOverlayNotification?.({ title: 'title' });
+  options.dismissOverlayNotification?.('notification-id');
 
   assert.deepEqual(calls, [
     'create-main',
@@ -58,5 +62,7 @@ test('build initialize overlay runtime options maps dependencies', () => {
     'set-tracker',
     'set-anki',
     'notify',
+    'show-overlay',
+    'dismiss-overlay',
   ]);
 });
diff --git a/src/main/runtime/overlay-runtime-options.ts b/src/main/runtime/overlay-runtime-options.ts
index 63d5f688..98e7e08a 100644
--- a/src/main/runtime/overlay-runtime-options.ts
+++ b/src/main/runtime/overlay-runtime-options.ts
@@ -33,6 +33,7 @@ type OverlayRuntimeOptions = {
   setAnkiIntegration: (integration: unknown | null) => void;
   showDesktopNotification: (title: string, options: { body?: string; icon?: string }) => void;
   showOverlayNotification?: (payload: OverlayNotificationPayload) => void;
+  dismissOverlayNotification?: (id: string) => void;
   createFieldGroupingCallback: () => (
     data: KikuFieldGroupingRequestData,
   ) => Promise<KikuFieldGroupingChoice>;
@@ -73,6 +74,7 @@ export function createBuildInitializeOverlayRuntimeOptionsHandler(deps: {
   setAnkiIntegration: (integration: unknown | null) => void;
   showDesktopNotification: (title: string, options: { body?: string; icon?: string }) => void;
   showOverlayNotification?: (payload: OverlayNotificationPayload) => void;
+  dismissOverlayNotification?: (id: string) => void;
   createFieldGroupingCallback: () => (
     data: KikuFieldGroupingRequestData,
   ) => Promise<KikuFieldGroupingChoice>;
@@ -107,6 +109,7 @@ export function createBuildInitializeOverlayRuntimeOptionsHandler(deps: {
     setAnkiIntegration: deps.setAnkiIntegration,
     showDesktopNotification: deps.showDesktopNotification,
     showOverlayNotification: deps.showOverlayNotification,
+    dismissOverlayNotification: deps.dismissOverlayNotification,
     createFieldGroupingCallback: deps.createFieldGroupingCallback,
     getKnownWordCacheStatePath: deps.getKnownWordCacheStatePath,
     ...(deps.getCachedMediaPath ? { getCachedMediaPath: deps.getCachedMediaPath } : {}),
diff --git a/src/main/runtime/posix-launcher-bootstrap.test.ts b/src/main/runtime/posix-launcher-bootstrap.test.ts
new file mode 100644
index 00000000..c1793e1d
--- /dev/null
+++ b/src/main/runtime/posix-launcher-bootstrap.test.ts
@@ -0,0 +1,66 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import test from 'node:test';
+import { posixLauncherBootstrapContent, shellQuote } from './posix-launcher-bootstrap';
+
+test('downloaded launcher prepares once, survives unmount, and refreshes after app replacement', (t) => {
+  if (process.platform !== 'linux') return;
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "subminer bootstrap's "));
+  t.after(() => fs.rmSync(root, { recursive: true, force: true }));
+  const appPath = path.join(root, 'SubMiner.AppImage');
+  const resources = path.join(root, 'mount', 'resources');
+  fs.mkdirSync(path.join(resources, 'launcher'), { recursive: true });
+  fs.mkdirSync(path.join(resources, 'bun', 'licenses'), { recursive: true });
+  fs.symlinkSync(process.execPath, path.join(resources, 'bun', 'bun'));
+  fs.writeFileSync(path.join(resources, 'bun', 'licenses', 'notice'), 'Bun notice');
+  fs.writeFileSync(path.join(resources, 'launcher', 'version'), '1.0.0\n');
+  fs.writeFileSync(
+    path.join(resources, 'launcher', 'prepare.cjs'),
+    `exports.prepareLauncherRuntime = require(${JSON.stringify(path.join(__dirname, 'prepare-launcher-runtime.ts'))}).prepareLauncherRuntime;`,
+  );
+  const script = (version: number) =>
+    `console.log(JSON.stringify({version:${version},args:process.argv.slice(2)}));`;
+  fs.writeFileSync(path.join(resources, 'launcher', 'subminer.js'), script(1));
+  const prepares = path.join(root, 'preparations');
+  const appContent = `#!/bin/sh\necho prepared >> ${shellQuote(prepares)}\nexport APPDIR=${shellQuote(path.dirname(resources))}\nexec ${shellQuote(process.execPath)} "$@"\n`;
+  fs.writeFileSync(appPath, appContent, { mode: 0o755 });
+  const wrapper = path.join(root, 'subminer');
+  fs.writeFileSync(wrapper, posixLauncherBootstrapContent(), { mode: 0o755 });
+  const env = { HOME: root, PATH: '', SUBMINER_BINARY_PATH: appPath };
+  const args = ['space here', "a'b", 'a&b', '$(touch nope)', '日本語'];
+  const run = (extraEnv = {}) =>
+    spawnSync(wrapper, args, { env: { ...env, ...extraEnv }, encoding: 'utf8' });
+  const first = run();
+  assert.equal(first.status, 0, first.stderr);
+  assert.deepEqual(JSON.parse(first.stdout), { version: 1, args });
+  const cache = path.join(root, '.local', 'share', 'SubMiner', 'launcher');
+  assert.equal(fs.readFileSync(path.join(cache, 'licenses', 'notice'), 'utf8'), 'Bun notice');
+
+  fs.renameSync(resources, `${resources}.unmounted`);
+  const warm = run({ SUBMINER_BINARY_PATH: '' }); // Finds the app recorded by preparation.
+  assert.equal(warm.status, 0, warm.stderr);
+  assert.deepEqual(JSON.parse(warm.stdout), { version: 1, args });
+  assert.equal(fs.readFileSync(prepares, 'utf8'), 'prepared\n');
+  fs.renameSync(`${resources}.unmounted`, resources);
+
+  // Same version and path, new inode: manual replacement must still refresh.
+  fs.writeFileSync(`${appPath}.new`, appContent, { mode: 0o755 });
+  fs.renameSync(`${appPath}.new`, appPath);
+  fs.writeFileSync(path.join(resources, 'launcher', 'subminer.js'), script(2));
+  const updated = run();
+  assert.equal(updated.status, 0, updated.stderr);
+  assert.deepEqual(JSON.parse(updated.stdout), { version: 2, args });
+  assert.equal(fs.readFileSync(prepares, 'utf8'), 'prepared\nprepared\n');
+
+  fs.unlinkSync(path.join(cache, 'bun'));
+  assert.equal(run().status, 0);
+  assert.equal(fs.readFileSync(prepares, 'utf8'), 'prepared\nprepared\nprepared\n');
+
+  fs.writeFileSync(appPath, '#!/bin/sh\nexit 42\n', { mode: 0o755 });
+  const failed = run();
+  assert.equal(failed.status, 42);
+  assert.equal(failed.stdout, ''); // Never silently execute stale CLI after failed preparation.
+});
diff --git a/src/main/runtime/posix-launcher-bootstrap.ts b/src/main/runtime/posix-launcher-bootstrap.ts
new file mode 100644
index 00000000..3cde8e6e
--- /dev/null
+++ b/src/main/runtime/posix-launcher-bootstrap.ts
@@ -0,0 +1,56 @@
+export const MANAGED_LAUNCHER_MARKER = 'SubMiner managed launcher (bundled runtime)';
+
+export function shellQuote(value: string): string {
+  return `'${value.replaceAll("'", "'\\''")}'`;
+}
+
+// Only a missing or stale Linux cache starts Electron in Node mode. Normal
+// launches do one stat and execute the cached Bun and matching CLI directly.
+export function posixLauncherBootstrapContent(appPath = ''): string {
+  return `#!/bin/sh
+# ${MANAGED_LAUNCHER_MARKER}
+export SUBMINER_MANAGED_LAUNCHER=1
+export SUBMINER_LAUNCHER_PATH="$0"
+subminer_default_app=${shellQuote(appPath)}
+case "\${XDG_DATA_HOME:-}" in
+  /*) subminer_data="$XDG_DATA_HOME" ;;
+  *) subminer_data="$HOME/.local/share" ;;
+esac
+subminer_cache="$subminer_data/SubMiner/launcher"
+subminer_saved_app=
+if [ -f "$subminer_cache/app-path" ]; then
+  IFS= read -r subminer_saved_app < "$subminer_cache/app-path" || :
+fi
+subminer_app=
+for subminer_candidate in "\${SUBMINER_APPIMAGE_PATH:-}" "\${SUBMINER_BINARY_PATH:-}" "$subminer_default_app" "$subminer_saved_app" "$HOME/.local/bin/SubMiner.AppImage" /opt/SubMiner/SubMiner.AppImage /Applications/SubMiner.app/Contents/MacOS/SubMiner "$HOME/Applications/SubMiner.app/Contents/MacOS/SubMiner"; do
+  if [ -n "$subminer_candidate" ] && [ -x "$subminer_candidate" ]; then
+    subminer_app="$subminer_candidate"
+    break
+  fi
+done
+if [ -z "$subminer_app" ]; then
+  echo 'SubMiner app not found. Install the app or set SUBMINER_BINARY_PATH to its executable.' >&2
+  exit 1
+fi
+export SUBMINER_BINARY_PATH="$subminer_app"
+case "$subminer_app" in
+  */Contents/MacOS/*)
+    subminer_resources="\${subminer_app%/MacOS/*}/Resources"
+    if [ ! -x "$subminer_resources/bun/bun" ] || [ ! -f "$subminer_resources/launcher/subminer.js" ]; then
+      echo 'This launcher requires a SubMiner app with the included Bun runtime. Update SubMiner.' >&2
+      exit 1
+    fi
+    exec "$subminer_resources/bun/bun" "$subminer_resources/launcher/subminer.js" "$@"
+    ;;
+esac
+subminer_fingerprint=$(PATH="/usr/bin:/bin:$PATH" stat -Lc '%d:%i:%s:%y:%z' -- "$subminer_app") || exit 1
+subminer_cached_fingerprint=
+if [ -f "$subminer_cache/fingerprint" ]; then
+  IFS= read -r subminer_cached_fingerprint < "$subminer_cache/fingerprint" || :
+fi
+if [ "$subminer_app" != "$subminer_saved_app" ] || [ "$subminer_fingerprint" != "$subminer_cached_fingerprint" ] || [ ! -x "$subminer_cache/bun" ] || [ ! -f "$subminer_cache/subminer" ]; then
+  PATH="/usr/bin:/bin:$PATH" ELECTRON_RUN_AS_NODE=1 "$subminer_app" -e 'const p=require("node:path"); const r=process.env.APPDIR ? p.join(process.env.APPDIR,"resources") : p.join(p.dirname(process.execPath),"resources"); try { require(p.join(r,"launcher/prepare.cjs")).prepareLauncherRuntime({appPath:process.env.SUBMINER_BINARY_PATH,resourcesPath:r}); } catch(e) { console.error("Cannot prepare SubMiner launcher. Update or reinstall the SubMiner app.",e.message); process.exit(1); }' || exit $?
+fi
+exec "$subminer_cache/bun" "$subminer_cache/subminer" "$@"
+`;
+}
diff --git a/src/main/runtime/prepare-launcher-runtime.ts b/src/main/runtime/prepare-launcher-runtime.ts
new file mode 100644
index 00000000..40de1aa2
--- /dev/null
+++ b/src/main/runtime/prepare-launcher-runtime.ts
@@ -0,0 +1,24 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { cleanupOldWindowsManagedRuntimes, stageManagedLauncher } from './managed-launcher';
+
+// Bundled separately as Node-compatible code so AppImages can prepare their
+// runtime without starting Electron's GUI, single-instance lock, or settings.
+export function prepareLauncherRuntime(options: { appPath: string; resourcesPath: string }) {
+  const appVersion = fs
+    .readFileSync(path.join(options.resourcesPath, 'launcher', 'version'), 'utf8')
+    .trim();
+  const payload = stageManagedLauncher({
+    appExePath: options.appPath,
+    appVersion,
+    bundledBunPath: path.join(
+      options.resourcesPath,
+      'bun',
+      process.platform === 'win32' ? 'bun.exe' : 'bun',
+    ),
+    launcherResourcePath: path.join(options.resourcesPath, 'launcher', 'subminer.js'),
+    force: process.platform === 'linux',
+  });
+  if (process.platform === 'win32') cleanupOldWindowsManagedRuntimes({ appVersion });
+  return payload;
+}
diff --git a/src/main/runtime/primary-subtitle-text.test.ts b/src/main/runtime/primary-subtitle-text.test.ts
index e43a94f1..c9ff6db0 100644
--- a/src/main/runtime/primary-subtitle-text.test.ts
+++ b/src/main/runtime/primary-subtitle-text.test.ts
@@ -3,6 +3,7 @@ import test from 'node:test';
 import { parseSubtitleCues } from '../../core/services/subtitle-cue-parser';
 import {
   resolveCanonicalPrimarySubtitle,
+  resolvePrimarySubtitle,
   resolvePrimarySubtitleText,
   stripCanonicalFragmentLines,
 } from './primary-subtitle-text';
@@ -60,7 +61,85 @@ test('resolvePrimarySubtitleText combines unique simultaneous parsed cues', () =
         { startTime: 1, endTime: 3, text: '二行目' },
       ],
     }),
-    '一行目\n二行目',
+    '一行目\n\n二行目',
+  );
+});
+
+test('resolvePrimarySubtitleText accounts for live ASS furigana after canonical recovery', () => {
+  const ass = [
+    '[Script Info]',
+    'PlayResY: 540',
+    '',
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    'Dialogue: 0,0:02:38.20,0:02:41.87,Default,,0,0,0,,{\\pos(192,77)}ごめん　結局　ぬれたな。',
+    'Comment: 0,0:02:38.20,0:02:41.87,Default,,0,0,0,,大丈夫。',
+    'Dialogue: 0,0:02:38.20,0:02:41.87,Default,,0,0,0,,{\\pos(552,113)\\fscx50\\fscy50}だいじょうぶ',
+    'Dialogue: 0,0:02:38.20,0:02:41.87,Default,,0,0,0,,{\\pos(552,167)\\clip(m 1 1)}大丈夫。',
+    'Dialogue: 0,0:02:38.20,0:02:41.87,Default,,0,0,0,,{\\pos(552,167)\\clip(m 2 2)}大丈夫。',
+    'Dialogue: 0,0:02:38.20,0:02:41.87,Default,,0,0,0,,{\\pos(552,167)\\clip(m 3 3)}大丈夫。',
+  ].join('\n');
+  const cues = parseSubtitleCues(ass, 'polar-opposites-s02e08.ass');
+
+  assert.equal(
+    resolvePrimarySubtitleText({
+      liveText: 'ごめん　結局　ぬれたな。\nだいじょうぶ\n大丈夫。',
+      currentTimeSec: 159,
+      cues,
+    }),
+    'ごめん　結局　ぬれたな。\n\n大丈夫。',
+  );
+});
+
+test('resolvePrimarySubtitleText removes duplicate lines across multiline parsed cues', () => {
+  assert.equal(
+    resolvePrimarySubtitleText({
+      liveText: 'First line\nSecond line\nFirst line',
+      currentTimeSec: 2,
+      cues: [
+        { startTime: 1, endTime: 3, text: 'First line\nSecond line' },
+        { startTime: 1, endTime: 3, text: 'First line' },
+      ],
+    }),
+    'First line\nSecond line',
+  );
+});
+
+test('resolvePrimarySubtitleText removes equivalent full-width duplicate lines', () => {
+  assert.equal(
+    resolvePrimarySubtitleText({
+      liveText: '２０分５３秒\n20分53秒',
+      currentTimeSec: 2,
+      cues: [
+        { startTime: 1, endTime: 3, text: '２０分５３秒' },
+        { startTime: 1, endTime: 3, text: '20分53秒' },
+      ],
+    }),
+    '２０分５３秒',
+  );
+});
+
+test('resolvePrimarySubtitleText collapses whitespace variants of one ASS lyric', () => {
+  const ass = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    'Dialogue: 2,0:00:01.00,0:00:03.00,EDJP,,0,0,0,,少しだけ好きになる',
+    'Dialogue: 1,0:00:01.00,0:00:03.00,EDJP,,0,0,0,,少しだけ\\h好きになる',
+    'Dialogue: 0,0:00:01.00,0:00:03.00,EDJP,,0,0,0,,少しだけ　好きになる',
+  ].join('\n');
+  const cues = parseSubtitleCues(ass, 'polar-opposites-s01e10.ass');
+
+  assert.deepEqual(
+    cues.map((cue) => cue.text),
+    ['少しだけ好きになる', '少しだけ 好きになる', '少しだけ　好きになる'],
+  );
+  assert.equal(
+    resolvePrimarySubtitleText({
+      liveText: ['少しだけ好きになる', '少しだけ 好きになる', '少しだけ　好きになる'].join('\n'),
+      currentTimeSec: 2,
+      cues,
+    }),
+    '少しだけ好きになる',
   );
 });
 
@@ -128,6 +207,73 @@ test('resolvePrimarySubtitleText keeps concurrent dialogue that is not part of t
   assert.equal(text, '普通のセリフ\n今\n手にある');
 });
 
+test('resolvePrimarySubtitleText combines parsed dialogue with a reconstructed lyric', () => {
+  const text = resolvePrimarySubtitleText({
+    liveText: '普通のセリフ\n今\n今\n手\n手\nにある\nにある',
+    currentTimeSec: 2,
+    cues: [
+      { startTime: 1, endTime: 3, text: '普通のセリフ' },
+      {
+        startTime: 1.2,
+        endTime: 3.8,
+        text: '今　手にある',
+        source: 'reconstructed-ass',
+      },
+    ],
+  });
+
+  assert.equal(text, '普通のセリフ\n\n今　手にある');
+});
+
+test('resolvePrimarySubtitleText uses fragment grids only to account for live sign pieces', () => {
+  const text = resolvePrimarySubtitleText({
+    liveText: 'Ordinary dialogue\nMaid\nCafe',
+    currentTimeSec: 2,
+    cues: [
+      { startTime: 1, endTime: 3, text: 'Ordinary dialogue' },
+      {
+        startTime: 1,
+        endTime: 3,
+        text: 'MaidCafeMaidCafe',
+        source: 'reconstructed-ass',
+        assLayout: { kind: 'fragment-grid', sourceOrder: 2 },
+      },
+    ],
+  });
+
+  assert.equal(text, 'Ordinary dialogue');
+});
+
+test('resolvePrimarySubtitleText drops malformed ASS control debris from live text', () => {
+  const cues = parseSubtitleCues(
+    [
+      '[Events]',
+      'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+      'Dialogue: 0,0:00:01.00,0:00:03.00,Default,,0,0,0,,Visible line',
+    ].join('\n'),
+    'test.ass',
+  );
+
+  assert.equal(
+    resolvePrimarySubtitleText({
+      liveText: 'Visible line\n\\\n{\\fr0',
+      currentTimeSec: 2,
+      cues,
+    }),
+    'Visible line',
+  );
+});
+
+test('resolvePrimarySubtitleText preserves SRT text that resembles ASS control debris', () => {
+  const liveText = 'Visible line\n\\\n{\\fr0';
+  const cues = parseSubtitleCues(
+    ['1', '00:00:01,000 --> 00:00:03,000', liveText].join('\n'),
+    'test.srt',
+  );
+
+  assert.equal(resolvePrimarySubtitleText({ liveText, currentTimeSec: 2, cues }), liveText);
+});
+
 test('resolvePrimarySubtitleText keeps a fresh line starting just after the animation ended', () => {
   const text = resolvePrimarySubtitleText({
     liveText: '次のセリフ',
@@ -181,7 +327,46 @@ test('resolvePrimarySubtitleText combines simultaneous canonical cues in source
     ],
   });
 
-  assert.equal(text, 'first\nsecond');
+  assert.equal(text, 'first\n\nsecond');
+});
+
+test('resolveCanonicalPrimarySubtitle orders active cues from top to bottom', () => {
+  const resolved = resolveCanonicalPrimarySubtitle({
+    liveText: 'bottom\ntop',
+    currentTimeSec: 2,
+    cues: [
+      {
+        startTime: 1,
+        endTime: 3,
+        text: 'bottom',
+        source: 'canonical-ass',
+        assLayout: { kind: 'source-order', sourceOrder: 1, verticalBand: 'bottom' },
+      },
+      {
+        startTime: 1,
+        endTime: 3,
+        text: 'top',
+        source: 'canonical-ass',
+        assLayout: { kind: 'source-order', sourceOrder: 0, verticalBand: 'top' },
+      },
+    ],
+  });
+
+  assert.equal(resolved?.text, 'top\n\nbottom');
+});
+
+test('resolvePrimarySubtitleText collapses whitespace variants of a canonical lyric', () => {
+  assert.equal(
+    resolvePrimarySubtitleText({
+      liveText: '少しだけ好きになる\n少しだけ　好きになる',
+      currentTimeSec: 2,
+      cues: [
+        { startTime: 1, endTime: 3, text: '少しだけ好きになる', source: 'canonical-ass' },
+        { startTime: 1, endTime: 3, text: '少しだけ　好きになる', source: 'canonical-ass' },
+      ],
+    }),
+    '少しだけ好きになる',
+  );
 });
 
 test('resolveCanonicalPrimarySubtitle covers a nearby generated animation edge', () => {
@@ -344,3 +529,211 @@ test('resolveCanonicalPrimarySubtitle picks the cue its fragments spell, not the
     '今　手にある',
   );
 });
+
+test('resolvePrimarySubtitleText suppresses a live glyph wall when no cues are available', () => {
+  const wall = [...'wansdumretoikhI'].join('\n');
+  assert.equal(
+    resolvePrimarySubtitleText({ liveText: `${wall}\ntai`, currentTimeSec: 1355, cues: null }),
+    '',
+  );
+});
+
+test('stripCanonicalFragmentLines drops a live glyph wall with no nearby canonical cues', () => {
+  const wall = [...'wansdumretoikhI'].join('\n');
+  assert.equal(
+    stripCanonicalFragmentLines({
+      liveText: `${wall}\nそれよりも　ノート…`,
+      currentTimeSec: 1355,
+      cues: [],
+    }),
+    'それよりも　ノート…',
+  );
+});
+
+test('resolvePrimarySubtitleText keeps a line joining an active cue despite stale time-pos', () => {
+  // Issue #220: mpv publishes the combined sub-text the moment a joining line's first
+  // frame renders, while the observed time-pos still sits just before that line's
+  // start. The joining cue must not be filtered out as inactive.
+  assert.equal(
+    resolvePrimarySubtitleText({
+      liveText: 'Балда! Балда, балда, балда!\nСестренка не может остановиться',
+      currentTimeSec: 767.78,
+      cues: [
+        { startTime: 767.19, endTime: 772.78, text: 'Балда! Балда, балда, балда!' },
+        { startTime: 767.79, endTime: 771.15, text: 'Сестренка не может остановиться' },
+      ],
+    }),
+    'Балда! Балда, балда, балда!\n\nСестренка не может остановиться',
+  );
+});
+
+test('resolvePrimarySubtitleText drops a finished lyric whose exit ghosts outlive it beside a raw line', () => {
+  // The reconstructed lyric ended at 6.0 but its exit ghost glyphs stay in the live
+  // text until 7.0, while the next authored line is a plain raw event. The retired cue
+  // must explain the ghost fragments without re-surfacing next to the active line.
+  const cues = [
+    {
+      startTime: 1.0,
+      endTime: 6.0,
+      text: 'エネルギーはサイクル',
+      source: 'reconstructed-ass' as const,
+      animationStartTime: 0.5,
+      animationEndTime: 7.0,
+      assStyle: 'OP - JP',
+    },
+    { startTime: 6.0, endTime: 12.0, text: '象徴的なパレード' },
+  ];
+
+  assert.equal(
+    resolvePrimarySubtitleText({
+      liveText: 'エ\nネ\nル\nギ\nー\n象徴的なパレード',
+      currentTimeSec: 6.5,
+      cues,
+    }),
+    '象徴的なパレード',
+  );
+});
+
+test('resolvePrimarySubtitleText stacks simultaneous cues by screen position, not start order', () => {
+  // A top-anchored lyric and bottom dialogue: mpv draws the lyric above the dialogue for
+  // the whole overlap. Whichever event started first must not decide the row, or the
+  // pair swaps every time one side is replaced mid-overlap.
+  const lyricLayout = { kind: 'source-order', sourceOrder: 0, verticalBand: 'top' } as const;
+  const dialogueLayout = { kind: 'source-order', sourceOrder: 1, verticalBand: 'bottom' } as const;
+  const dialogue = {
+    startTime: 632.2,
+    endTime: 634.8,
+    text: '\u30e9\u30a4\u30d6\u3000\u3084\u3081\u3088\u3063\u304b',
+    assLayout: dialogueLayout,
+  };
+
+  // Lyric started before the dialogue...
+  assert.equal(
+    resolvePrimarySubtitleText({
+      liveText: '\u30e9\u30a4\u30d6\u3000\u3084\u3081\u3088\u3063\u304b\n\u6b4c\u8a5e\uff21',
+      currentTimeSec: 632.5,
+      cues: [
+        { startTime: 629.5, endTime: 633.5, text: '\u6b4c\u8a5e\uff21', assLayout: lyricLayout },
+        dialogue,
+      ],
+    }),
+    '\u6b4c\u8a5e\uff21\n\n\u30e9\u30a4\u30d6\u3000\u3084\u3081\u3088\u3063\u304b',
+  );
+  // ...and the next lyric starts after it: the rows must not swap.
+  assert.equal(
+    resolvePrimarySubtitleText({
+      liveText: '\u30e9\u30a4\u30d6\u3000\u3084\u3081\u3088\u3063\u304b\n\u6b4c\u8a5e\uff22',
+      currentTimeSec: 633.8,
+      cues: [
+        dialogue,
+        { startTime: 633.5, endTime: 637.0, text: '\u6b4c\u8a5e\uff22', assLayout: lyricLayout },
+      ],
+    }),
+    '\u6b4c\u8a5e\uff22\n\n\u30e9\u30a4\u30d6\u3000\u3084\u3081\u3088\u3063\u304b',
+  );
+});
+
+test('resolvePrimarySubtitleText puts an unreadable placement above bottom dialogue', () => {
+  // Dialogue is the case that reliably declares a bottom alignment, so a cue whose
+  // placement could not be read is more often a sign or song line. Keeping dialogue on
+  // the bottom row means the line worth reading stays where the eye already is.
+  assert.equal(
+    resolvePrimarySubtitleText({
+      liveText: '\u4e0b\u306e\u30bb\u30ea\u30d5\n\u4e0d\u660e\u306a\u884c',
+      currentTimeSec: 2,
+      cues: [
+        {
+          startTime: 1,
+          endTime: 3,
+          text: '\u4e0b\u306e\u30bb\u30ea\u30d5',
+          assLayout: { kind: 'source-order', sourceOrder: 0, verticalBand: 'bottom' },
+        },
+        {
+          startTime: 1.5,
+          endTime: 3,
+          text: '\u4e0d\u660e\u306a\u884c',
+          assLayout: { kind: 'source-order', sourceOrder: 1 },
+        },
+      ],
+    }),
+    '\u4e0d\u660e\u306a\u884c\n\n\u4e0b\u306e\u30bb\u30ea\u30d5',
+  );
+});
+
+test('resolvePrimarySubtitleText keeps source order when no cue declares a placement', () => {
+  // SRT and websocket cues carry no layout at all: every cue ties, so the stable sort
+  // must leave them exactly as the cue list had them.
+  assert.equal(
+    resolvePrimarySubtitleText({
+      liveText: 'First line\nSecond line',
+      currentTimeSec: 2,
+      cues: [
+        { startTime: 1, endTime: 3, text: 'First line' },
+        { startTime: 1.5, endTime: 3, text: 'Second line' },
+      ],
+    }),
+    'First line\n\nSecond line',
+  );
+});
+
+test('resolvePrimarySubtitleText publishes a wrapped caption sentence as one cue', () => {
+  // mpv still reports the two source rows (plus the ruby row) as separate live lines, so
+  // the merged cue must explain all of them and come back as a single-break line the
+  // display layer may flatten, not as a two-cue boundary.
+  const ass = [
+    '[Script Info]',
+    'PlayResY: 540',
+    '',
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    'Dialogue: 0,0:02:42.33,0:02:44.43,Default,,0,0,0,,{\\pos(232,437)\\fscx50}（{\\fscx100}東{\\fscx50}）{\\fscx100}≪好きだと',
+    'Dialogue: 0,0:02:42.33,0:02:44.43,Default,,0,0,0,,{\\pos(292,443)\\fscx50\\fscy50}じかく',
+    'Dialogue: 0,0:02:42.33,0:02:44.43,Default,,0,0,0,,{\\pos(232,497)}自覚してしまったものの➡',
+    // A second labeled turn, so the script reads as broadcast captions.
+    'Dialogue: 0,0:02:44.43,0:02:47.37,Default,,0,0,0,,{\\pos(212,497)\\fscx50}（{\\fscx100}平{\\fscx50}）{\\fscx100}どうした？',
+  ].join('\n');
+  const cues = parseSubtitleCues(ass, 'polar-opposites-s02e09.ass');
+
+  assert.equal(
+    resolvePrimarySubtitleText({
+      liveText: '（東）≪好きだと\nじかく\n自覚してしまったものの➡',
+      currentTimeSec: 163,
+      cues,
+    }),
+    '（東）≪好きだと\n自覚してしまったものの➡',
+  );
+});
+
+test('resolvePrimarySubtitle drops a finished caption row lingering beside a fresh line', () => {
+  // Broadcast captions give each row its own event, and a row of the previous line can
+  // outlive its siblings by a frame. mpv's sub-text still lists it, so the mined line
+  // must come from the parsed cue that is actually running, with that cue's timings.
+  const ass = [
+    '[Script Info]',
+    'PlayResY: 540',
+    '',
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    'Dialogue: 0,0:14:30.00,0:14:33.00,Default,,0,0,0,,{\\pos(232,437)\\fscx50}（{\\fscx100}東{\\fscx50}）{\\fscx100}ずっと　言えなかっ',
+    'Dialogue: 0,0:14:30.00,0:14:33.02,Default,,0,0,0,,{\\pos(232,497)}たが',
+    'Dialogue: 0,0:14:33.00,0:14:36.00,Default,,0,0,0,,{\\pos(232,437)}⸨もし　お互い',
+    'Dialogue: 0,0:14:33.00,0:14:36.00,Default,,0,0,0,,{\\pos(232,497)}本命　受かったら　大学　近いし➡',
+  ].join('\n');
+  const cues = parseSubtitleCues(ass, 'polar-opposites-s02e09.ass');
+
+  const resolved = resolvePrimarySubtitle({
+    liveText: 'たが\n⸨もし　お互い\n本命　受かったら　大学　近いし➡',
+    currentTimeSec: 14 * 60 + 33.05,
+    cues,
+  });
+
+  assert.deepEqual(
+    { ...resolved, cues: resolved?.cues.map((cue) => cue.text) },
+    {
+      text: '⸨もし　お互い\n本命　受かったら　大学　近いし➡',
+      startTime: 14 * 60 + 33,
+      endTime: 14 * 60 + 36,
+      cues: ['⸨もし　お互い\n本命　受かったら　大学　近いし➡'],
+    },
+  );
+});
diff --git a/src/main/runtime/primary-subtitle-text.ts b/src/main/runtime/primary-subtitle-text.ts
index 6e1164ef..afce7a18 100644
--- a/src/main/runtime/primary-subtitle-text.ts
+++ b/src/main/runtime/primary-subtitle-text.ts
@@ -1,4 +1,8 @@
-import type { SubtitleCue } from '../../types';
+import type { AssVerticalBand, SubtitleCue } from '../../types';
+import {
+  removeAssControlDebrisLines,
+  removeLiveGlyphFragmentLines,
+} from '../../core/services/ass-text';
 
 // Slack on top of each cue's recorded animation envelope, for time-pos observation
 // staleness and small user sub-delay offsets. The envelope itself covers how far
@@ -13,6 +17,22 @@ export interface ResolvedPrimarySubtitle {
   cues: SubtitleCue[];
 }
 
+function cuesUseAssSyntax(cues: readonly SubtitleCue[] | null | undefined): boolean {
+  return (cues ?? []).some(
+    (cue) =>
+      cue.source === 'canonical-ass' ||
+      cue.source === 'reconstructed-ass' ||
+      cue.assLayout !== undefined,
+  );
+}
+
+function decodedLiveText(
+  liveText: string,
+  cues: readonly SubtitleCue[] | null | undefined,
+): string {
+  return cuesUseAssSyntax(cues) ? removeAssControlDebrisLines(liveText) : liveText;
+}
+
 function animationSpan(cue: SubtitleCue): { start: number; end: number } {
   return {
     start: cue.animationStartTime ?? cue.startTime,
@@ -23,9 +43,13 @@ function animationSpan(cue: SubtitleCue): { start: number; end: number } {
 function nearbyCanonicalCues(
   cues: readonly SubtitleCue[] | null | undefined,
   currentTimeSec: number,
+  includeFragmentGrids = false,
 ): SubtitleCue[] {
   return (cues ?? []).filter((cue) => {
-    if (cue.source !== 'canonical-ass') {
+    if (
+      (cue.source !== 'canonical-ass' && cue.source !== 'reconstructed-ass') ||
+      (!includeFragmentGrids && cue.assLayout?.kind === 'fragment-grid')
+    ) {
       return false;
     }
     const span = animationSpan(cue);
@@ -37,7 +61,55 @@ function nearbyCanonicalCues(
 }
 
 function compactWhitespace(text: string): string {
-  return text.replace(/\s+/gu, '');
+  return text.normalize('NFKC').replace(/\s+/gu, '');
+}
+
+/**
+ * Distinct simultaneous cues are separated by a blank line so the display layer can tell
+ * a wrap inside one utterance from the boundary between two of them. Consumers that read
+ * the text rather than display it fold these back to single breaks.
+ */
+const CUE_BOUNDARY = '\n\n';
+
+const VERTICAL_BAND_RANK: Record<AssVerticalBand, number> = { top: 0, middle: 1, bottom: 2 };
+
+/**
+ * Stack simultaneous cues the way they sit on screen: mpv keeps a top-anchored lyric or
+ * sign above bottom dialogue for its whole run, while cue-list order follows start time
+ * and would swap the pair whenever one side is replaced mid-overlap. The band is
+ * constant per event, so a line never changes rows while it is displayed.
+ *
+ * A cue whose placement could not be read -- an unknown style, a script with no styles
+ * section -- sorts to the top. Dialogue is the case that reliably declares a bottom
+ * alignment, so what is left unresolved is more often a sign or a song line, and keeping
+ * the dialogue on the bottom row means the line worth reading stays where the eye
+ * already is. Sort is stable, so cues sharing a rank keep their existing order.
+ */
+function orderCuesForDisplay(cues: readonly SubtitleCue[]): SubtitleCue[] {
+  const rank = (cue: SubtitleCue): number =>
+    VERTICAL_BAND_RANK[cue.assLayout?.verticalBand ?? 'top'];
+  return [...cues].sort((a, b) => rank(a) - rank(b));
+}
+
+// ASS layers can encode the same visible spacing with ordinary, hard, or
+// ideographic spaces. Matching and emission must use the same identity or each
+// layer reappears as a copy.
+function uniqueCueTextGroups(cues: readonly SubtitleCue[]): string[] {
+  const groups: string[] = [];
+  const seen = new Set<string>();
+  for (const cue of cues) {
+    const lines: string[] = [];
+    for (const line of cue.text.split('\n')) {
+      const compactText = compactWhitespace(line);
+      if (!compactText || seen.has(compactText)) continue;
+      seen.add(compactText);
+      lines.push(line);
+    }
+    if (lines.length > 0) {
+      groups.push(lines.join('\n'));
+    }
+  }
+  return groups;
 }
 
 function compactLineSegments(text: string): string[] {
@@ -72,30 +144,58 @@ function resolveActiveParsedPrimarySubtitle(options: {
       return false;
     }
     const cueSegments = compactLineSegments(cue.text);
-    return cueSegments.length > 0 && cueSegments.every((segment) => liveSegmentSet.has(segment));
+    if (cueSegments.length === 0) return false;
+    if (cue.source === 'canonical-ass' || cue.source === 'reconstructed-ass') {
+      return liveSegments.some((segment) =>
+        cueSegments.some((cueSegment) => cueSegment.includes(segment)),
+      );
+    }
+    return cueSegments.every((segment) => liveSegmentSet.has(segment));
   });
   if (selected.length === 0) {
     return null;
   }
 
-  const parsedSegmentSet = new Set(selected.flatMap((cue) => compactLineSegments(cue.text)));
-  if (!liveSegments.every((segment) => parsedSegmentSet.has(segment))) {
+  const parsedSegments = selected.flatMap((cue) => {
+    const recovered = cue.source === 'canonical-ass' || cue.source === 'reconstructed-ass';
+    return [
+      ...compactLineSegments(cue.text).map((segment) => ({ segment, recovered })),
+      ...(cue.assFurigana ?? []).flatMap((text) =>
+        compactLineSegments(text).map((segment) => ({ segment, recovered: false })),
+      ),
+    ];
+  });
+  if (
+    !liveSegments.every((liveSegment) =>
+      parsedSegments.some(({ segment, recovered }) =>
+        recovered ? segment.includes(liveSegment) : segment === liveSegment,
+      ),
+    )
+  ) {
     return null;
   }
 
-  const texts: string[] = [];
-  const seen = new Set<string>();
-  for (const cue of selected) {
-    if (!seen.has(cue.text)) {
-      seen.add(cue.text);
-      texts.push(cue.text);
-    }
-  }
+  // A cue selected only through the edge tolerance on its end has already finished by
+  // its published timing: a lyric whose exit ghosts linger into the next line. It still
+  // explains those live fragments above, but must not re-surface beside cues that are
+  // still running. The start side keeps the tolerance: mpv publishes the combined
+  // sub-text the moment a joining line's first frame renders, while the observed
+  // time-pos still sits just before that line's start, and the selection above already
+  // required the cue's text to be on screen (#220). With every selected cue finished,
+  // the edge cues remain the display fallback for stale time-pos readings.
+  const unfinished = selected.filter((cue) => cue.endTime > options.currentTimeSec);
+  const displayCues = unfinished.length > 0 ? unfinished : selected;
+
+  // Dense sign grids still explain their raw mpv fragments, but are visual
+  // typesetting rather than a publishable subtitle line.
+  const groups = uniqueCueTextGroups(
+    orderCuesForDisplay(displayCues.filter((cue) => cue.assLayout?.kind !== 'fragment-grid')),
+  );
   return {
-    text: texts.join('\n'),
-    startTime: Math.min(...selected.map((cue) => cue.startTime)),
-    endTime: Math.max(...selected.map((cue) => cue.endTime)),
-    cues: selected,
+    text: groups.join(CUE_BOUNDARY),
+    startTime: Math.min(...displayCues.map((cue) => cue.startTime)),
+    endTime: Math.max(...displayCues.map((cue) => cue.endTime)),
+    cues: displayCues,
   };
 }
 
@@ -159,16 +259,9 @@ export function resolveCanonicalPrimarySubtitle(options: {
     return null;
   }
 
-  const texts: string[] = [];
-  const seen = new Set<string>();
-  for (const cue of selected) {
-    if (!seen.has(cue.text)) {
-      seen.add(cue.text);
-      texts.push(cue.text);
-    }
-  }
+  const groups = uniqueCueTextGroups(orderCuesForDisplay(selected));
   return {
-    text: texts.join('\n'),
+    text: groups.join(CUE_BOUNDARY),
     startTime: Math.min(...selected.map((cue) => cue.startTime)),
     endTime: Math.max(...selected.map((cue) => cue.endTime)),
     cues: selected,
@@ -178,8 +271,9 @@ export function resolveCanonicalPrimarySubtitle(options: {
 /**
  * Live text with generated-animation fragment lines removed. Recording paths use this
  * when full canonical substitution declined -- concurrent dialogue during an insert
- * song: the dialogue is worth recording, the glyph fragments beside it are not. Returns
- * the input unchanged when no canonical cue is near or nothing non-fragment remains.
+ * song: the dialogue is worth recording, the glyph fragments beside it are not. An
+ * all-fragment visual grid becomes empty; other all-matched input remains unchanged as a
+ * defensive fallback.
  */
 export function stripCanonicalFragmentLines(options: {
   liveText: string;
@@ -187,18 +281,62 @@ export function stripCanonicalFragmentLines(options: {
   cues: readonly SubtitleCue[] | null | undefined;
 }): string {
   if (!Number.isFinite(options.currentTimeSec)) {
-    return options.liveText;
+    return removeLiveGlyphFragmentLines(options.liveText);
   }
-  const nearby = nearbyCanonicalCues(options.cues, options.currentTimeSec);
+  const nearby = nearbyCanonicalCues(options.cues, options.currentTimeSec, true);
   if (nearby.length === 0) {
-    return options.liveText;
+    return removeLiveGlyphFragmentLines(options.liveText);
   }
   const compactCues = nearby.map((cue) => compactWhitespace(cue.text));
   const kept = options.liveText.split('\n').filter((line) => {
     const compact = compactWhitespace(line);
     return compact && !compactCues.some((cueText) => cueText.includes(compact));
   });
-  return kept.length > 0 ? kept.join('\n') : options.liveText;
+  if (kept.length > 0) return removeLiveGlyphFragmentLines(kept.join('\n'));
+  if (nearby.some((cue) => cue.assLayout?.kind === 'fragment-grid')) return '';
+  return removeLiveGlyphFragmentLines(options.liveText);
+}
+
+/**
+ * Recording text for a live sample. Callers substitute canonical cues themselves and
+ * record those cue by cue, so what is resolved here is the parsed view -- the one that
+ * folds ASS furigana events back into their base line. Its text is already a complete
+ * line, while fragment stripping takes raw mpv text and would discard a resolved line
+ * whole while a fragment grid is on screen, so only one of the two ever runs.
+ */
+export function resolveRecordedPrimarySubtitleText(options: {
+  liveText: string;
+  currentTimeSec: number;
+  cues: readonly SubtitleCue[] | null | undefined;
+}): string {
+  const liveText = decodedLiveText(options.liveText, options.cues);
+  if (!liveText.trim()) {
+    return liveText;
+  }
+  return (
+    resolveActiveParsedPrimarySubtitle({ ...options, liveText })?.text ??
+    stripCanonicalFragmentLines({ ...options, liveText })
+  );
+}
+
+/**
+ * The parsed view of the live text with its cue timings: a canonical animation when one
+ * explains the live lines, otherwise the active parsed cues. Null when the parsed cues
+ * cannot account for every live line, in which case callers keep the raw mpv text.
+ */
+export function resolvePrimarySubtitle(options: {
+  liveText: string;
+  currentTimeSec: number;
+  cues: readonly SubtitleCue[] | null | undefined;
+}): ResolvedPrimarySubtitle | null {
+  const liveText = decodedLiveText(options.liveText, options.cues);
+  if (!liveText.trim()) {
+    return null;
+  }
+  return (
+    resolveCanonicalPrimarySubtitle({ ...options, liveText }) ??
+    resolveActiveParsedPrimarySubtitle({ ...options, liveText })
+  );
 }
 
 export function resolvePrimarySubtitleText(options: {
@@ -206,16 +344,9 @@ export function resolvePrimarySubtitleText(options: {
   currentTimeSec: number;
   cues: readonly SubtitleCue[] | null | undefined;
 }): string {
-  if (!options.liveText.trim()) {
-    return options.liveText;
+  const liveText = decodedLiveText(options.liveText, options.cues);
+  if (!liveText.trim()) {
+    return liveText;
   }
-  return (
-    resolveCanonicalPrimarySubtitle({
-      liveText: options.liveText,
-      currentTimeSec: options.currentTimeSec,
-      cues: options.cues,
-    })?.text ??
-    resolveActiveParsedPrimarySubtitle(options)?.text ??
-    options.liveText
-  );
+  return resolvePrimarySubtitle(options)?.text ?? removeLiveGlyphFragmentLines(liveText);
 }
diff --git a/src/main/runtime/protocol-url-handlers-main-deps.test.ts b/src/main/runtime/protocol-url-handlers-main-deps.test.ts
deleted file mode 100644
index 5a6087aa..00000000
--- a/src/main/runtime/protocol-url-handlers-main-deps.test.ts
+++ /dev/null
@@ -1,29 +0,0 @@
-import assert from 'node:assert/strict';
-import test from 'node:test';
-import { createBuildRegisterProtocolUrlHandlersMainDepsHandler } from './protocol-url-handlers-main-deps';
-
-test('protocol url handlers main deps builder maps callbacks', () => {
-  const calls: string[] = [];
-  const deps = createBuildRegisterProtocolUrlHandlersMainDepsHandler({
-    registerOpenUrl: () => calls.push('open-register'),
-    registerSecondInstance: () => calls.push('second-register'),
-    handleAnilistSetupProtocolUrl: () => true,
-    findAnilistSetupDeepLinkArgvUrl: () => 'subminer://anilist-setup',
-    logUnhandledOpenUrl: (rawUrl) => calls.push(`open:${rawUrl}`),
-    logUnhandledSecondInstanceUrl: (rawUrl) => calls.push(`second:${rawUrl}`),
-  })();
-
-  deps.registerOpenUrl(() => {});
-  deps.registerSecondInstance(() => {});
-  assert.equal(deps.handleAnilistSetupProtocolUrl('subminer://anilist-setup'), true);
-  assert.equal(deps.findAnilistSetupDeepLinkArgvUrl(['x']), 'subminer://anilist-setup');
-  deps.logUnhandledOpenUrl('subminer://noop');
-  deps.logUnhandledSecondInstanceUrl('subminer://noop');
-
-  assert.deepEqual(calls, [
-    'open-register',
-    'second-register',
-    'open:subminer://noop',
-    'second:subminer://noop',
-  ]);
-});
diff --git a/src/main/runtime/protocol-url-handlers-main-deps.ts b/src/main/runtime/protocol-url-handlers-main-deps.ts
deleted file mode 100644
index a2a0554f..00000000
--- a/src/main/runtime/protocol-url-handlers-main-deps.ts
+++ /dev/null
@@ -1,16 +0,0 @@
-import type { registerProtocolUrlHandlers } from './protocol-url-handlers';
-
-type RegisterProtocolUrlHandlersMainDeps = Parameters<typeof registerProtocolUrlHandlers>[0];
-
-export function createBuildRegisterProtocolUrlHandlersMainDepsHandler(
-  deps: RegisterProtocolUrlHandlersMainDeps,
-) {
-  return (): RegisterProtocolUrlHandlersMainDeps => ({
-    registerOpenUrl: (listener) => deps.registerOpenUrl(listener),
-    registerSecondInstance: (listener) => deps.registerSecondInstance(listener),
-    handleAnilistSetupProtocolUrl: (rawUrl: string) => deps.handleAnilistSetupProtocolUrl(rawUrl),
-    findAnilistSetupDeepLinkArgvUrl: (argv: string[]) => deps.findAnilistSetupDeepLinkArgvUrl(argv),
-    logUnhandledOpenUrl: (rawUrl: string) => deps.logUnhandledOpenUrl(rawUrl),
-    logUnhandledSecondInstanceUrl: (rawUrl: string) => deps.logUnhandledSecondInstanceUrl(rawUrl),
-  });
-}
diff --git a/src/main/runtime/secondary-subtitle-track.test.ts b/src/main/runtime/secondary-subtitle-track.test.ts
index c4f5d995..cc553216 100644
--- a/src/main/runtime/secondary-subtitle-track.test.ts
+++ b/src/main/runtime/secondary-subtitle-track.test.ts
@@ -20,6 +20,295 @@ test('findActiveSubtitleText combines unique simultaneous parsed cues', () => {
   );
 });
 
+test('findActiveSubtitleText removes duplicate lines across multiline cues', () => {
+  assert.equal(
+    findActiveSubtitleText(
+      [
+        { startTime: 1, endTime: 3, text: 'First line\nSecond line' },
+        { startTime: 1, endTime: 3, text: 'First line' },
+      ],
+      2,
+    ),
+    'First line\nSecond line',
+  );
+});
+
+test('findActiveSubtitleText removes equivalent full-width duplicate lines', () => {
+  assert.equal(
+    findActiveSubtitleText(
+      [
+        { startTime: 1, endTime: 3, text: '真白～' },
+        { startTime: 1, endTime: 3, text: '真白~' },
+      ],
+      2,
+    ),
+    '真白～',
+  );
+});
+
+test('findActiveSubtitleText collapses whitespace variants of one ASS lyric', () => {
+  assert.equal(
+    findActiveSubtitleText(
+      [
+        { startTime: 1, endTime: 3, text: '少しだけ好きになる' },
+        { startTime: 1, endTime: 3, text: '少しだけ 好きになる' },
+        { startTime: 1, endTime: 3, text: '少しだけ　好きになる' },
+      ],
+      2,
+    ),
+    '少しだけ好きになる',
+  );
+});
+
+test('parsed secondary text collapses a positioned sign that repeats dialogue without punctuation', () => {
+  const ass = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    'Dialogue: 10,0:03:58.49,0:04:00.34,GJM_Main_1080p,Nar,0,0,0,,{\\i1}A question veiled as an insult!',
+    'Dialogue: 1,0:03:58.59,0:04:00.34,iFanzSigns,,0,0,0,,{\\pos(960,75)}A question veiled as an insult',
+  ].join('\n');
+  const cues = parseSubtitleCues(ass, 'kaguya-s02e10.ass');
+
+  assert.equal(findActiveSubtitleText(cues, 238.48), '');
+  assert.equal(findActiveSubtitleText(cues, 238.5), 'A question veiled as an insult!');
+  assert.equal(findActiveSubtitleText(cues, 239), 'A question veiled as an insult!');
+  assert.equal(findActiveSubtitleText(cues, 240.34), '');
+});
+
+test('parsed secondary text drops a reconstructed grid of positioned sign fragments', () => {
+  const signFragment = (text: string, x: number, y: number) =>
+    `Dialogue: 1,0:00:01.00,0:00:03.00,Signs,,0,0,0,,{\\pos(${x},${y})\\t(0,100,\\fscx101)}${text}`;
+  const ass = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    'Dialogue: 10,0:00:01.00,0:00:03.00,Default,Speaker,0,0,0,,Come on, wake up!',
+    signFragment('Timetable', 1700, 150),
+    signFragment('Mon', 1750, 230),
+    signFragment('Tue', 1850, 230),
+    signFragment('1', 1650, 320),
+    signFragment('2', 1650, 390),
+    signFragment('Civics', 1750, 320),
+    signFragment('Math', 1850, 390),
+    signFragment('PE', 1850, 460),
+  ].join('\n');
+
+  assert.equal(
+    findActiveSubtitleText(parseSubtitleCues(ass, 'kaguya-s02e11.ass'), 2),
+    'Come on, wake up!',
+  );
+});
+
+test('parsed secondary text keeps phone translations while dropping texture payloads', () => {
+  const ass = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    'Dialogue: 2,0:00:01.00,0:00:03.00,FrogSigns,,0,0,0,,{\\pos(580,95)\\fnGrain Medium\\clip(500,40,660,150)}LLLLLLLLLLLL',
+    'Dialogue: 90,0:00:01.00,0:00:03.00,Default,,0,0,0,,Why did you choose Hanajo instead?',
+    "Dialogue: 1,0:00:01.00,0:00:03.00,FrogSigns,,0,0,0,,{\\pos(580,95)\\fnGrain\\fs10\\alpha&H70&}q26D'vrA;\\NE? GS\\NESLhlawEv",
+    "Dialogue: 3,0:00:01.00,0:00:03.00,FrogSigns,,0,0,0,,{\\pos(582,180)\\fnSF Pro Display\\fs66}We're {\\2a0}running {\\2a1}out {\\2a0}of {\\2a1}time!\\N{\\2a0}Where {\\2a1}are {\\2a0}you {\\2a1}right {\\2a0}now?!",
+  ].join('\n');
+
+  assert.equal(
+    findActiveSubtitleText(parseSubtitleCues(ass, 'phone.ass'), 2),
+    "Why did you choose Hanajo instead?\nWe're running out of time!\nWhere are you right now?!",
+  );
+});
+
+test('parsed secondary lyrics keep explicit ASS vertical order when durations alternate', () => {
+  const lyric = (options: { start: string; end: string; style: string; y: number; text: string }) =>
+    `Dialogue: 0,0:00:${options.start},0:00:${options.end},${options.style},,0,0,0,fx,{\\move(100,${options.y},120,${options.y})\\t(0,200,\\fscx110)}${options.text}\\N{\\p1}m 0 0 l 0 5`;
+  const ass = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    lyric({
+      start: '01.00',
+      end: '02.20',
+      style: 'ed_romaji',
+      y: 66,
+      text: 'ima wo kakusarechau mae ni',
+    }),
+    lyric({
+      start: '01.00',
+      end: '02.00',
+      style: 'ed_english',
+      y: 1020,
+      text: 'Before the present moment gets hidden away.',
+    }),
+    lyric({
+      start: '03.00',
+      end: '04.00',
+      style: 'ed_romaji',
+      y: 66,
+      text: 'ame mitai ni hikatteru',
+    }),
+    lyric({
+      start: '03.00',
+      end: '04.20',
+      style: 'ed_english',
+      y: 1020,
+      text: 'Is shining like rain.',
+    }),
+  ].join('\n');
+  const cues = parseSubtitleCues(ass, 'polar-opposites-s01e08.ass');
+
+  assert.equal(
+    findActiveSubtitleText(cues, 1.5),
+    'ima wo kakusarechau mae ni\nBefore the present moment gets hidden away.',
+  );
+  assert.equal(findActiveSubtitleText(cues, 3.5), 'ame mitai ni hikatteru\nIs shining like rain.');
+});
+
+test('unpositioned secondary lyrics fall back to ASS source order', () => {
+  const ass = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    'Dialogue: 0,0:00:01.00,0:00:02.20,ED Romaji,,0,0,0,,ima wo kakusarechau mae ni',
+    'Dialogue: 0,0:00:01.00,0:00:02.00,ED English,,0,0,0,,Before the present moment gets hidden away.',
+  ].join('\n');
+
+  assert.equal(
+    findActiveSubtitleText(parseSubtitleCues(ass, 'ending.ass'), 1.5),
+    'ima wo kakusarechau mae ni\nBefore the present moment gets hidden away.',
+  );
+});
+
+test('findActiveSubtitleText keeps a canonical ASS cue for its generated animation span', () => {
+  const poof = {
+    startTime: 1110.67,
+    endTime: 1110.71,
+    text: 'POOF',
+    source: 'canonical-ass' as const,
+    animationStartTime: 1110.67,
+    animationEndTime: 1111.59,
+  };
+
+  assert.equal(findActiveSubtitleText([poof], 1111.58), 'POOF');
+  assert.equal(findActiveSubtitleText([poof], 1111.59), '');
+});
+
+test('findActiveSubtitleText advances when the next canonical lyric animation starts', () => {
+  const cues = [
+    {
+      startTime: 121.73,
+      endTime: 124.1,
+      text: 'Torn at the seams, a sound pours out',
+      source: 'canonical-ass' as const,
+      animationStartTime: 121.4,
+      animationEndTime: 124.1,
+    },
+    {
+      startTime: 124.13,
+      endTime: 126.38,
+      text: 'It’s silent, yet spreads all around',
+      source: 'canonical-ass' as const,
+      animationStartTime: 123.8,
+      animationEndTime: 126.38,
+    },
+  ];
+
+  assert.equal(findActiveSubtitleText(cues, 123.79), cues[0]!.text);
+  assert.equal(findActiveSubtitleText(cues, 123.8), cues[1]!.text);
+});
+
+test('ASS fragment karaoke stays separated by style with authored word spacing', () => {
+  const lineEvents = (
+    style: string,
+    fragments: readonly string[],
+    y: number,
+    baseTime = 1,
+  ): string[] => {
+    const events: string[] = [];
+    for (const layer of [0, 1]) {
+      fragments.forEach((fragment, index) => {
+        const x = 100 + index * 40;
+        const start = (baseTime + index * 0.25).toFixed(2).padStart(5, '0');
+        const end = (baseTime + 3 + index * 0.2).toFixed(2).padStart(5, '0');
+        events.push(
+          `Dialogue: ${layer},0:00:${start},0:00:${end},${style},,0,0,0,,{\\pos(${x},${y})\\t(0,200,\\fscx110)}${fragment}\\N{\\p1}m 0 0 l 0 10`,
+        );
+      });
+    }
+    return events;
+  };
+  const ass = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    ...lineEvents('ed_romaji', ['ji', 'gu', 'za', 'gu ', 'na', 'mi'], 70),
+    ...lineEvents('ed_english', ['Pas', 'si', 'ng ', 'thro', 'u', 'gh '], 110),
+    ...lineEvents('op_english', ['I', 'want', 'to', 'go'], 110, 7),
+  ].join('\n');
+
+  assert.equal(
+    findActiveSubtitleText(parseSubtitleCues(ass, 'ending.ass'), 2.5),
+    'jiguzagu nami\nPassing through',
+  );
+  // Some generated scripts discard spaces and retain only positioned chunks. Joining
+  // without invented separators avoids turning one word into spaced syllables.
+  assert.equal(findActiveSubtitleText(parseSubtitleCues(ass, 'ending.ass'), 8.5), 'Iwanttogo');
+});
+
+test('ASS fragment karaoke preserves word spaces authored at event boundaries', () => {
+  const fragments = [
+    'The ',
+    'shoot',
+    'ing ',
+    'stars ',
+    'arc',
+    'ing ',
+    'across ',
+    'the ',
+    'sky ',
+    'I ',
+    'wish ',
+    'upon,',
+  ];
+  const events: string[] = [];
+  for (const layer of [0, 1]) {
+    fragments.forEach((fragment, index) => {
+      events.push(
+        `Dialogue: ${layer},0:00:01.00,0:00:04.00,op_english,,0,0,0,,{\\pos(${100 + index * 40},110)\\t(0,200,\\fscx110)}${fragment}`,
+      );
+    });
+  }
+  const ass = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    ...events,
+  ].join('\n');
+
+  assert.equal(
+    findActiveSubtitleText(parseSubtitleCues(ass, 'bravern-s01e10.ass'), 2),
+    'The shooting stars arcing across the sky I wish upon,',
+  );
+});
+
+test('findActiveSubtitleText keeps a complete reconstructed line over entrance fragments', () => {
+  const current = {
+    startTime: 1,
+    endTime: 4,
+    text: 'Complete current line',
+    source: 'reconstructed-ass' as const,
+    assStyle: 'op_english',
+  };
+  const nextEntrance = {
+    startTime: 3.8,
+    endTime: 4.2,
+    text: 'Ne',
+    source: 'reconstructed-ass' as const,
+    assStyle: 'op_english',
+  };
+  const nextLine = {
+    startTime: 4,
+    endTime: 7,
+    text: 'Next complete line',
+    source: 'reconstructed-ass' as const,
+    assStyle: 'op_english',
+  };
+
+  assert.equal(findActiveSubtitleText([current, nextEntrance], 3.9), current.text);
+  assert.equal(findActiveSubtitleText([current, nextEntrance, nextLine], 4.1), nextLine.text);
+});
+
 test('secondary track controller parses the selected ASS file before publishing', async () => {
   const broadcasts: string[] = [];
   let currentText = '';
@@ -157,6 +446,125 @@ test('secondary track controller falls back to live mpv text without a readable
   assert.deepEqual(broadcasts, ['live fallback']);
 });
 
+test('secondary ASS live fallback drops malformed control debris', async () => {
+  const broadcasts: string[] = [];
+  const controller = createSecondarySubtitleTrackController({
+    getMpvClient: () => ({
+      connected: true,
+      requestProperty: async (name) => {
+        if (name === 'secondary-sid') return 2;
+        if (name === 'track-list') return [{ type: 'sub', id: 2 }];
+        if (name === 'path') return '/media/video.mkv';
+        return null;
+      },
+    }),
+    getCurrentTimePos: () => 2,
+    resolveSubtitleSource: async () => ({ path: '/subs/english.ass', sourceKey: 'english' }),
+    loadSubtitleSourceText: async () => '',
+    parseSubtitleCues: () => [],
+    setCurrentSecondaryText: () => {},
+    broadcastSecondaryText: (text) => broadcasts.push(text),
+  });
+
+  await controller.refresh();
+  broadcasts.length = 0;
+  controller.handleLiveText('Visible line\n\\\n{\\fr0');
+
+  assert.deepEqual(broadcasts, ['Visible line']);
+});
+
+test('secondary SRT live fallback preserves text that resembles ASS control debris', async () => {
+  const broadcasts: string[] = [];
+  const controller = createSecondarySubtitleTrackController({
+    getMpvClient: () => ({
+      connected: true,
+      requestProperty: async (name) => {
+        if (name === 'secondary-sid') return 2;
+        if (name === 'track-list') return [{ type: 'sub', id: 2 }];
+        if (name === 'path') return '/media/video.mkv';
+        return null;
+      },
+    }),
+    getCurrentTimePos: () => 2,
+    resolveSubtitleSource: async () => ({ path: '/subs/english.srt', sourceKey: 'english' }),
+    loadSubtitleSourceText: async () => '',
+    parseSubtitleCues: () => [],
+    setCurrentSecondaryText: () => {},
+    broadcastSecondaryText: (text) => broadcasts.push(text),
+  });
+
+  await controller.refresh();
+  broadcasts.length = 0;
+  controller.handleLiveText('Visible line\n\\\n{\\fr0');
+
+  assert.deepEqual(broadcasts, ['Visible line\n\\\n{\\fr0']);
+});
+
+test('secondary disconnect clears stale ASS fallback sanitization state', async () => {
+  let connected = true;
+  const broadcasts: string[] = [];
+  const controller = createSecondarySubtitleTrackController({
+    getMpvClient: () => ({
+      connected,
+      requestProperty: async (name) => {
+        if (name === 'secondary-sid') return 2;
+        if (name === 'track-list') return [{ type: 'sub', id: 2 }];
+        if (name === 'path') return '/media/video.mkv';
+        return null;
+      },
+    }),
+    getCurrentTimePos: () => 2,
+    resolveSubtitleSource: async () => ({ path: '/subs/english.ass', sourceKey: 'english' }),
+    loadSubtitleSourceText: async () => '',
+    parseSubtitleCues: () => [],
+    setCurrentSecondaryText: () => {},
+    broadcastSecondaryText: (text) => broadcasts.push(text),
+  });
+
+  await controller.refresh();
+  connected = false;
+  await controller.refresh();
+  broadcasts.length = 0;
+  controller.handleLiveText('Visible line\n\\\n{\\fr0');
+
+  assert.deepEqual(broadcasts, ['Visible line\n\\\n{\\fr0']);
+});
+
+test('secondary source refresh failure clears stale ASS fallback sanitization state', async () => {
+  let resolveCalls = 0;
+  const broadcasts: string[] = [];
+  const controller = createSecondarySubtitleTrackController({
+    getMpvClient: () => ({
+      connected: true,
+      requestProperty: async (name) => {
+        if (name === 'secondary-sid') return 2;
+        if (name === 'track-list') return [{ type: 'sub', id: 2 }];
+        if (name === 'path') return '/media/video.mkv';
+        return null;
+      },
+    }),
+    getCurrentTimePos: () => 2,
+    resolveSubtitleSource: async () => {
+      resolveCalls += 1;
+      if (resolveCalls === 1) {
+        return { path: '/subs/english.ass', sourceKey: 'english' };
+      }
+      throw new Error('source refresh failed');
+    },
+    loadSubtitleSourceText: async () => '',
+    parseSubtitleCues: () => [],
+    setCurrentSecondaryText: () => {},
+    broadcastSecondaryText: (text) => broadcasts.push(text),
+  });
+
+  await controller.refresh();
+  await controller.refresh();
+  broadcasts.length = 0;
+  controller.handleLiveText('Visible line\n\\\n{\\fr0');
+
+  assert.deepEqual(broadcasts, ['Visible line\n\\\n{\\fr0']);
+});
+
 test('secondary track controller reuses parsed cues for an unchanged embedded track', async () => {
   let resolveCalls = 0;
   let parseCalls = 0;
@@ -248,3 +656,36 @@ test('secondary track controller ignores and cleans up a refresh invalidated by
   assert.equal(parseCalls, 0);
   assert.equal(cleanupCalls, 1);
 });
+
+test('secondary live fallback suppresses a per-glyph typesetting wall', async () => {
+  let currentText = '';
+  const controller = createSecondarySubtitleTrackController({
+    getMpvClient: () => ({
+      connected: true,
+      requestProperty: async (name) => {
+        if (name === 'secondary-sid') return 2;
+        if (name === 'track-list') return [{ type: 'sub', id: 2 }];
+        if (name === 'path') return '/mnt/nas/video.mkv';
+        if (name === 'secondary-sub-delay') return 0;
+        return null;
+      },
+    }),
+    getCurrentTimePos: () => 1355,
+    // Network-mounted media: embedded extraction is skipped, so no parsed cues exist.
+    resolveSubtitleSource: async () => null,
+    loadSubtitleSourceText: async () => '',
+    parseSubtitleCues,
+    setCurrentSecondaryText: (text) => {
+      currentText = text;
+    },
+    broadcastSecondaryText: () => {},
+  });
+
+  await controller.refresh();
+  const wall = [...'wansdumretoikhI'].join('\n');
+  controller.handleLiveText(`${wall}\ntai`);
+  assert.equal(currentText, '');
+
+  controller.handleLiveText(`${wall}\nそれよりも　ノート…`);
+  assert.equal(currentText, 'それよりも　ノート…');
+});
diff --git a/src/main/runtime/secondary-subtitle-track.ts b/src/main/runtime/secondary-subtitle-track.ts
index 0ef68b50..f6b076b9 100644
--- a/src/main/runtime/secondary-subtitle-track.ts
+++ b/src/main/runtime/secondary-subtitle-track.ts
@@ -1,4 +1,9 @@
 import type { SubtitleCue } from '../../types/subtitle';
+import { flattenedSecondarySubtitleLineIdentity } from '../../core/services/secondary-subtitle-line-identity';
+import {
+  removeAssControlDebrisLines,
+  removeLiveGlyphFragmentLines,
+} from '../../core/services/ass-text';
 
 type SecondarySubtitleMpvClient = {
   connected?: boolean;
@@ -22,6 +27,11 @@ type SecondarySubtitleSourceInput = {
 
 const DEFAULT_REFRESH_DELAY_MS = 500;
 
+function sourceUsesAssSyntax(source: string): boolean {
+  const sourceWithoutQuery = source.split(/[?#]/u, 1)[0] ?? '';
+  return /\.(?:ass|ssa)$/iu.test(sourceWithoutQuery);
+}
+
 function finiteNumber(value: unknown, fallback = 0): number {
   const number = typeof value === 'number' ? value : Number(value);
   return Number.isFinite(number) ? number : fallback;
@@ -58,17 +68,130 @@ function buildSelectedTrackIdentity(
   ]);
 }
 
+type IndexedSubtitleCue = { cue: SubtitleCue; index: number };
+
+function compareAuthoredSubtitleOrder(left: IndexedSubtitleCue, right: IndexedSubtitleCue): number {
+  const leftLayout = left.cue.assLayout;
+  const rightLayout = right.cue.assLayout;
+  if (leftLayout?.kind === 'positioned' && rightLayout?.kind === 'positioned') {
+    const verticalOrder = leftLayout.y - rightLayout.y;
+    if (verticalOrder !== 0) return verticalOrder;
+  }
+  if (leftLayout && rightLayout) {
+    const sourceOrder = leftLayout.sourceOrder - rightLayout.sourceOrder;
+    if (sourceOrder !== 0) return sourceOrder;
+  }
+  return left.index - right.index;
+}
+
 export function findActiveSubtitleText(cues: readonly SubtitleCue[], timeSeconds: number): string {
   if (!Number.isFinite(timeSeconds)) return '';
 
-  const seen = new Set<string>();
+  const authoredCanonical = cues.filter(
+    (cue) =>
+      cue.source === 'canonical-ass' && cue.startTime <= timeSeconds && cue.endTime > timeSeconds,
+  );
+  const enteringCanonical = cues.filter(
+    (cue) =>
+      cue.source === 'canonical-ass' &&
+      (cue.animationStartTime ?? cue.startTime) <= timeSeconds &&
+      cue.startTime > timeSeconds &&
+      (cue.animationEndTime ?? cue.endTime) > timeSeconds,
+  );
+  const nextAuthoredStart = enteringCanonical.reduce(
+    (earliest, cue) => Math.min(earliest, cue.startTime),
+    Infinity,
+  );
+  // Generated lyrics can begin drawing before their canonical Comment timing. Once that
+  // entrance starts, replace a preceding lyric that ends before the new authored span;
+  // genuinely concurrent subtitles that continue through the new span stay selected.
+  const selectedCanonical = new Set<SubtitleCue>([
+    ...authoredCanonical.filter(
+      (cue) => enteringCanonical.length === 0 || cue.endTime > nextAuthoredStart,
+    ),
+    ...enteringCanonical,
+  ]);
+  if (selectedCanonical.size === 0) {
+    const animatedCanonical = cues.filter(
+      (cue) =>
+        cue.source === 'canonical-ass' &&
+        (cue.animationStartTime ?? cue.startTime) <= timeSeconds &&
+        (cue.animationEndTime ?? cue.endTime) > timeSeconds,
+    );
+    const nearestDistance = animatedCanonical.reduce((nearest, cue) => {
+      const distance =
+        timeSeconds < cue.startTime
+          ? cue.startTime - timeSeconds
+          : Math.max(0, timeSeconds - cue.endTime);
+      return Math.min(nearest, distance);
+    }, Infinity);
+    for (const cue of animatedCanonical) {
+      const distance =
+        timeSeconds < cue.startTime
+          ? cue.startTime - timeSeconds
+          : Math.max(0, timeSeconds - cue.endTime);
+      if (distance === nearestDistance) {
+        selectedCanonical.add(cue);
+      }
+    }
+  }
+
+  const activeReconstructed = cues.filter(
+    (cue) =>
+      cue.source === 'reconstructed-ass' &&
+      cue.assLayout?.kind !== 'fragment-grid' &&
+      cue.startTime <= timeSeconds &&
+      cue.endTime > timeSeconds,
+  );
+  const reconstructedByStyle = new Map<string, SubtitleCue>();
+  for (const cue of activeReconstructed) {
+    const style = cue.assStyle ?? '';
+    const existing = reconstructedByStyle.get(style);
+    if (!existing) {
+      reconstructedByStyle.set(style, cue);
+      continue;
+    }
+    const duration = cue.endTime - cue.startTime;
+    const existingDuration = existing.endTime - existing.startTime;
+    if (
+      duration > existingDuration ||
+      (duration === existingDuration && cue.text.length > existing.text.length) ||
+      (duration === existingDuration &&
+        cue.text.length === existing.text.length &&
+        cue.startTime > existing.startTime)
+    ) {
+      reconstructedByStyle.set(style, cue);
+    }
+  }
+  const selectedReconstructed = new Set(reconstructedByStyle.values());
+
+  const seenExact = new Set<string>();
+  const seenFlattened = new Set<string>();
   const activeText: string[] = [];
-  for (const cue of cues) {
-    if (cue.startTime > timeSeconds || cue.endTime <= timeSeconds) continue;
-    const text = cue.text.trim();
-    if (!text || seen.has(text)) continue;
-    seen.add(text);
-    activeText.push(text);
+  const activeCues: IndexedSubtitleCue[] = [];
+  cues.forEach((cue, index) => {
+    const active =
+      cue.source === 'canonical-ass'
+        ? selectedCanonical.has(cue)
+        : cue.source === 'reconstructed-ass'
+          ? selectedReconstructed.has(cue)
+          : cue.startTime <= timeSeconds && cue.endTime > timeSeconds;
+    if (active) activeCues.push({ cue, index });
+  });
+  activeCues.sort(compareAuthoredSubtitleOrder);
+
+  for (const { cue } of activeCues) {
+    for (const line of cue.text.split('\n')) {
+      const text = line.trim();
+      const compactText = text.normalize('NFKC').replace(/\s+/gu, '');
+      if (!compactText || seenExact.has(compactText)) continue;
+      seenExact.add(compactText);
+
+      const flattenedIdentity = flattenedSecondarySubtitleLineIdentity(text);
+      if (flattenedIdentity && seenFlattened.has(flattenedIdentity)) continue;
+      if (flattenedIdentity) seenFlattened.add(flattenedIdentity);
+      activeText.push(text);
+    }
   }
   return activeText.join('\n');
 }
@@ -89,6 +212,7 @@ export function createSecondarySubtitleTrackController(deps: {
   let parsedCues: SubtitleCue[] | null = null;
   let parsedSourceKey: string | null = null;
   let parsedTrackIdentity: string | null = null;
+  let activeSourceUsesAssSyntax = false;
   let secondaryDelaySeconds = 0;
   let lastLiveText = '';
   let lastBroadcastText: string | null = null;
@@ -118,6 +242,7 @@ export function createSecondarySubtitleTrackController(deps: {
     const generation = ++refreshGeneration;
     const client = deps.getMpvClient();
     if (!client?.connected) {
+      activeSourceUsesAssSyntax = false;
       useLiveFallback();
       return;
     }
@@ -134,6 +259,7 @@ export function createSecondarySubtitleTrackController(deps: {
 
       const videoPath = typeof videoPathRaw === 'string' ? videoPathRaw.trim() : '';
       if (!videoPath || secondarySid === null || secondarySid === 'no') {
+        activeSourceUsesAssSyntax = false;
         useLiveFallback();
         return;
       }
@@ -155,11 +281,14 @@ export function createSecondarySubtitleTrackController(deps: {
       });
       if (generation !== refreshGeneration) return;
       if (!resolvedSource) {
+        activeSourceUsesAssSyntax = false;
         deps.logDebug?.('[secondary-subtitle-track] selected source is not readable');
         useLiveFallback();
         return;
       }
 
+      activeSourceUsesAssSyntax = sourceUsesAssSyntax(resolvedSource.path);
+
       if (resolvedSource.sourceKey === parsedSourceKey && parsedCues) {
         parsedTrackIdentity = selectedTrackIdentity;
         publish(resolveAtTime(deps.getCurrentTimePos()));
@@ -181,6 +310,7 @@ export function createSecondarySubtitleTrackController(deps: {
       publish(resolveAtTime(deps.getCurrentTimePos()));
     } catch (error) {
       if (generation !== refreshGeneration) return;
+      activeSourceUsesAssSyntax = false;
       deps.logWarn?.('[secondary-subtitle-track] failed to parse selected source', error);
       useLiveFallback();
     } finally {
@@ -203,6 +333,7 @@ export function createSecondarySubtitleTrackController(deps: {
     parsedCues = null;
     parsedSourceKey = null;
     parsedTrackIdentity = null;
+    activeSourceUsesAssSyntax = false;
     secondaryDelaySeconds = 0;
     lastLiveText = '';
     publish('');
@@ -212,7 +343,9 @@ export function createSecondarySubtitleTrackController(deps: {
     refresh,
     scheduleRefresh,
     handleLiveText(text: string): void {
-      lastLiveText = text;
+      lastLiveText = removeLiveGlyphFragmentLines(
+        activeSourceUsesAssSyntax ? removeAssControlDebrisLines(text) : text,
+      );
       publish(resolveAtTime(deps.getCurrentTimePos()));
     },
     handleTimePos(timeSeconds: number): void {
diff --git a/src/main/runtime/session-bindings-runtime.test.ts b/src/main/runtime/session-bindings-runtime.test.ts
index 5d17d86d..b6785b00 100644
--- a/src/main/runtime/session-bindings-runtime.test.ts
+++ b/src/main/runtime/session-bindings-runtime.test.ts
@@ -70,3 +70,69 @@ test('persistSessionBindings keeps saved bindings when mpv reload notification f
     fs.rmSync(root, { recursive: true, force: true });
   }
 });
+
+test('native prefix conflicts publish the same effective bindings to the overlay and plugin and recover', async () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'subminer-session-conflict-'));
+  const sequence: CompiledSessionBinding = {
+    sourcePath: 'shortcuts.openSubtitleSelection',
+    originalKey: 'g-s',
+    key: { code: 'KeyG-KeyS', modifiers: [] },
+    actionType: 'session-action',
+    actionId: 'openSubtitleSelection',
+  };
+  let nativeKeys: unknown = [];
+  let failDiscovery = false;
+  let published: CompiledSessionBinding[] = [];
+  const events: CompiledSessionBinding[][] = [];
+  const warnings: string[] = [];
+  const client = {
+    connected: true,
+    send: () => {},
+    requestProperty: async () => {
+      if (failDiscovery) throw new Error('temporarily unavailable');
+      return nativeKeys;
+    },
+  };
+  const runtime = createSessionBindingsRuntime({
+    configDir: root,
+    getKeybindings: () => [],
+    getConfiguredShortcuts: () => ({ multiCopyTimeoutMs: 1500 }) as never,
+    getResolvedConfig: () => ({ stats: { toggleKey: 's', markWatchedKey: 'w' } }) as ResolvedConfig,
+    getMpvClient: () => client,
+    setSessionBindings: (bindings) => {
+      published = bindings;
+    },
+    setSessionBindingsInitialized: () => {},
+    logWarn: () => {},
+    onBindingsChanged: (bindings) => events.push(bindings),
+    onWarning: (warning) => warnings.push(warning.message),
+  });
+  const readArtifact = () =>
+    JSON.parse(fs.readFileSync(path.join(root, 'session-bindings.json'), 'utf8'));
+  try {
+    runtime.persistSessionBindings([sequence]);
+    nativeKeys = [{ key: 'g', cmd: 'show-text single', priority: 1 }];
+    await runtime.refreshMpvSessionBindings();
+    assert.deepEqual(published, []);
+    assert.deepEqual(events.at(-1), readArtifact().bindings);
+    assert.equal(warnings.length, 1);
+    assert.match(warnings[0]!, /mpv input binding "g"/);
+    await runtime.refreshMpvSessionBindings();
+    assert.equal(events.length, 2, 'unchanged discovery must not create a reload loop');
+    assert.equal(warnings.length, 1);
+    failDiscovery = true;
+    await runtime.refreshMpvSessionBindings();
+    assert.deepEqual(published, [], 'failed discovery retains the known conflict');
+    failDiscovery = false;
+    nativeKeys = [{ key: 'Shift+g', cmd: 'show-text shifted', priority: 1 }];
+    await runtime.refreshMpvSessionBindings();
+    assert.deepEqual(published, [sequence]);
+    assert.equal(readArtifact().bindings[0].key.code, 'KeyG-KeyS');
+    assert.deepEqual(readArtifact().warnings, []);
+    client.connected = false;
+    await runtime.refreshMpvSessionBindings();
+    assert.deepEqual(published, [sequence]);
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
diff --git a/src/main/runtime/session-bindings-runtime.ts b/src/main/runtime/session-bindings-runtime.ts
index 998331ac..8912d632 100644
--- a/src/main/runtime/session-bindings-runtime.ts
+++ b/src/main/runtime/session-bindings-runtime.ts
@@ -6,16 +6,26 @@ import {
 import type { ConfiguredShortcuts } from '../../core/utils/shortcut-config';
 import type { CompiledSessionBinding, Keybinding, ResolvedConfig } from '../../types';
 import { writeSessionBindingsArtifact } from './session-bindings-artifact';
+import { parseMpvInputBindingKeys } from '../../shared/mpv-input-bindings';
+import {
+  reserveMpvSequencePrefixes,
+  resolveSessionSequenceConflicts,
+} from '../../shared/session-key-sequences';
+import type { SessionBindingWarning } from '../../types/session-bindings';
 
 export interface SessionBindingsRuntimeDeps {
   configDir: string;
   getKeybindings: () => Keybinding[];
   getConfiguredShortcuts: () => ConfiguredShortcuts;
   getResolvedConfig: () => ResolvedConfig;
-  getMpvClient: () => MpvRuntimeClientLike | null;
+  getMpvClient: () =>
+    | (MpvRuntimeClientLike & { requestProperty: (name: string) => Promise<unknown> })
+    | null;
   setSessionBindings: (bindings: CompiledSessionBinding[]) => void;
   setSessionBindingsInitialized: (initialized: boolean) => void;
   logWarn: (message: string, details?: unknown) => void;
+  onBindingsChanged?: (bindings: CompiledSessionBinding[]) => void;
+  onWarning?: (warning: SessionBindingWarning) => void;
 }
 
 export function createSessionBindingsRuntime(deps: SessionBindingsRuntimeDeps): {
@@ -24,7 +34,20 @@ export function createSessionBindingsRuntime(deps: SessionBindingsRuntimeDeps):
     warnings?: ReturnType<typeof compileSessionBindings>['warnings'],
   ) => void;
   refreshCurrentSessionBindings: () => void;
+  refreshMpvSessionBindings: () => Promise<void>;
 } {
+  let sourceBindings: CompiledSessionBinding[] = [];
+  let sourceWarnings: SessionBindingWarning[] = [];
+  let nativeSnapshot: {
+    client: ReturnType<SessionBindingsRuntimeDeps['getMpvClient']>;
+    keys: string[];
+  } | null = null;
+  let pending: {
+    client: ReturnType<SessionBindingsRuntimeDeps['getMpvClient']>;
+    promise: Promise<void>;
+  } | null = null;
+  let publishedSignature: string | null = null;
+  let reportedWarnings = new Set<string>();
   function resolveSessionBindingPlatform(): 'darwin' | 'win32' | 'linux' {
     if (process.platform === 'darwin') return 'darwin';
     if (process.platform === 'win32') return 'win32';
@@ -49,8 +72,27 @@ export function createSessionBindingsRuntime(deps: SessionBindingsRuntimeDeps):
     bindings: CompiledSessionBinding[],
     warnings: ReturnType<typeof compileSessionBindings>['warnings'] = [],
   ): void {
+    sourceBindings = bindings;
+    sourceWarnings = warnings;
+    publishBindings();
+  }
+
+  function publishBindings(): void {
+    const client = deps.getMpvClient();
+    const keys = client?.connected && nativeSnapshot?.client === client ? nativeSnapshot.keys : [];
+    const result = resolveSessionSequenceConflicts(
+      sourceBindings,
+      reserveMpvSequencePrefixes(keys),
+    );
+    const warnings = [...sourceWarnings, ...result.warnings];
+    const signature = JSON.stringify([
+      result.bindings,
+      warnings,
+      deps.getConfiguredShortcuts().multiCopyTimeoutMs,
+    ]);
+    if (signature === publishedSignature) return;
     const artifact = buildPluginSessionBindingsArtifact({
-      bindings,
+      bindings: result.bindings,
       warnings,
       numericSelectionTimeoutMs: deps.getConfiguredShortcuts().multiCopyTimeoutMs,
     });
@@ -60,8 +102,16 @@ export function createSessionBindingsRuntime(deps: SessionBindingsRuntimeDeps):
       deps.logWarn('[session-bindings] Failed to write session bindings artifact');
       throw error;
     }
-    deps.setSessionBindings(bindings);
+    publishedSignature = signature;
+    deps.setSessionBindings(result.bindings);
     deps.setSessionBindingsInitialized(true);
+    const nextWarnings = new Set(warnings.map((warning) => warning.message));
+    for (const warning of warnings) {
+      if (reportedWarnings.has(warning.message)) continue;
+      deps.logWarn(`[session-bindings] ${warning.message}`);
+      deps.onWarning?.(warning);
+    }
+    reportedWarnings = nextWarnings;
     const mpvClient = deps.getMpvClient();
     if (mpvClient?.connected) {
       try {
@@ -70,15 +120,41 @@ export function createSessionBindingsRuntime(deps: SessionBindingsRuntimeDeps):
         deps.logWarn('[session-bindings] Failed to notify mpv to reload session bindings', error);
       }
     }
+    deps.onBindingsChanged?.(result.bindings);
+  }
+
+  async function refreshMpvSessionBindings(): Promise<void> {
+    const client = deps.getMpvClient();
+    if (!client?.connected) {
+      nativeSnapshot = null;
+      publishBindings();
+      return;
+    }
+    if (pending?.client === client) return pending.promise;
+    const promise = (async () => {
+      try {
+        const raw = await client.requestProperty('input-bindings');
+        if (client !== deps.getMpvClient() || !client.connected) return;
+        nativeSnapshot = { client, keys: parseMpvInputBindingKeys(raw, { includeIgnored: false }) };
+        publishBindings();
+      } catch {
+        // Keep the last successful snapshot if discovery is temporarily unavailable.
+      }
+    })();
+    const request = { client, promise };
+    pending = request;
+    try {
+      await promise;
+    } finally {
+      if (pending === request) pending = null;
+    }
   }
 
   function refreshCurrentSessionBindings(): void {
     const compiled = compileCurrentSessionBindings();
-    for (const warning of compiled.warnings) {
-      deps.logWarn(`[session-bindings] ${warning.message}`);
-    }
     persistSessionBindings(compiled.bindings, compiled.warnings);
+    void refreshMpvSessionBindings();
   }
 
-  return { persistSessionBindings, refreshCurrentSessionBindings };
+  return { persistSessionBindings, refreshCurrentSessionBindings, refreshMpvSessionBindings };
 }
diff --git a/src/main/runtime/stats-cli-command.ts b/src/main/runtime/stats-cli-command.ts
index 955f7b2c..cb1d9cf8 100644
--- a/src/main/runtime/stats-cli-command.ts
+++ b/src/main/runtime/stats-cli-command.ts
@@ -57,8 +57,10 @@ export function createRunStatsCliCommandHandler(deps: {
     }) => Promise<DuplicateSubtitleLineCleanupSummary>;
     rebuildLifetimeSummaries?: () => Promise<LifetimeRebuildSummary>;
   } | null;
-  ensureStatsServerStarted: () => string;
-  ensureBackgroundStatsServerStarted: () => BackgroundStatsStartResult;
+  ensureStatsServerStarted: () => Promise<string> | string;
+  ensureBackgroundStatsServerStarted: () =>
+    | Promise<BackgroundStatsStartResult>
+    | BackgroundStatsStartResult;
   stopBackgroundStatsServer: () => Promise<BackgroundStatsStopResult> | BackgroundStatsStopResult;
   openExternal: (url: string) => Promise<unknown>;
   writeResponse: (responsePath: string, payload: StatsCliCommandResponse) => void;
@@ -115,7 +117,7 @@ export function createRunStatsCliCommandHandler(deps: {
       }
 
       if (args.statsBackground) {
-        const result = deps.ensureBackgroundStatsServerStarted();
+        const result = await deps.ensureBackgroundStatsServerStarted();
         deps.logInfo(`Stats dashboard available at ${result.url}`);
         writeResponseSafe(args.statsResponsePath, { ok: true, url: result.url });
         if (!result.runningInCurrentProcess && source === 'initial') {
@@ -183,7 +185,7 @@ export function createRunStatsCliCommandHandler(deps: {
         return;
       }
 
-      const url = deps.ensureStatsServerStarted();
+      const url = await deps.ensureStatsServerStarted();
       if (config.stats.autoOpenBrowser !== false) {
         await deps.openExternal(url);
       }
diff --git a/src/main/runtime/stats-server-routing.test.ts b/src/main/runtime/stats-server-routing.test.ts
index 496b3f30..c7e5b13e 100644
--- a/src/main/runtime/stats-server-routing.test.ts
+++ b/src/main/runtime/stats-server-routing.test.ts
@@ -23,7 +23,7 @@ function createHarness(options?: {
       return options?.processAlive ?? true;
     },
     hasLocalStatsServer: () => localServerStarted,
-    startLocalStatsServer: () => {
+    startLocalStatsServer: async () => {
       calls.push('startLocalStatsServer');
       localServerStarted = true;
     },
@@ -36,23 +36,23 @@ function createHarness(options?: {
   };
 }
 
-test('stats server routing defers to a live background daemon from another process', () => {
+test('stats server routing defers to a live background daemon from another process', async () => {
   const { calls, handler } = createHarness({
     state: { pid: 200, port: 7979, startedAtMs: 1 },
     processAlive: true,
   });
 
-  assert.deepEqual(handler(), { url: 'http://127.0.0.1:7979', source: 'background' });
+  assert.deepEqual(await handler(), { url: 'http://127.0.0.1:7979', source: 'background' });
   assert.deepEqual(calls, ['readBackgroundState', 'isProcessAlive']);
 });
 
-test('stats server routing clears dead daemon state and starts local server', () => {
+test('stats server routing clears dead daemon state and starts local server', async () => {
   const { calls, handler } = createHarness({
     state: { pid: 200, port: 7979, startedAtMs: 1 },
     processAlive: false,
   });
 
-  assert.deepEqual(handler(), { url: 'http://127.0.0.1:6969', source: 'local' });
+  assert.deepEqual(await handler(), { url: 'http://127.0.0.1:6969', source: 'local' });
   assert.deepEqual(calls, [
     'readBackgroundState',
     'isProcessAlive',
@@ -61,13 +61,13 @@ test('stats server routing clears dead daemon state and starts local server', ()
   ]);
 });
 
-test('stats server routing clears self-owned stale state and starts local server', () => {
+test('stats server routing clears self-owned stale state and starts local server', async () => {
   const { calls, handler } = createHarness({
     state: { pid: 100, port: 7979, startedAtMs: 1 },
     processAlive: true,
   });
 
-  assert.deepEqual(handler(), { url: 'http://127.0.0.1:6969', source: 'local' });
+  assert.deepEqual(await handler(), { url: 'http://127.0.0.1:6969', source: 'local' });
   assert.deepEqual(calls, [
     'readBackgroundState',
     'removeBackgroundState',
@@ -75,12 +75,12 @@ test('stats server routing clears self-owned stale state and starts local server
   ]);
 });
 
-test('stats server routing reuses a started local stats server', () => {
+test('stats server routing reuses a started local stats server', async () => {
   const { calls, handler } = createHarness({
     state: null,
     localServerStarted: true,
   });
 
-  assert.deepEqual(handler(), { url: 'http://127.0.0.1:6969', source: 'local' });
+  assert.deepEqual(await handler(), { url: 'http://127.0.0.1:6969', source: 'local' });
   assert.deepEqual(calls, ['readBackgroundState', 'removeBackgroundState']);
 });
diff --git a/src/main/runtime/stats-server-routing.ts b/src/main/runtime/stats-server-routing.ts
index b2a42149..1fa0bb2e 100644
--- a/src/main/runtime/stats-server-routing.ts
+++ b/src/main/runtime/stats-server-routing.ts
@@ -6,7 +6,7 @@ type EnsureStatsServerUrlDeps = {
   removeBackgroundState: () => void;
   isProcessAlive: (pid: number) => boolean;
   hasLocalStatsServer: () => boolean;
-  startLocalStatsServer: () => void;
+  startLocalStatsServer: () => Promise<void>;
   getConfiguredPort: () => number;
 };
 
@@ -18,8 +18,8 @@ export type EnsureStatsServerUrlResult = { url: string; source: 'background' | '
 
 export function createEnsureStatsServerUrlHandler(
   deps: EnsureStatsServerUrlDeps,
-): () => EnsureStatsServerUrlResult {
-  return () => {
+): () => Promise<EnsureStatsServerUrlResult> {
+  return async () => {
     const state = deps.readBackgroundState();
     if (!state) {
       deps.removeBackgroundState();
@@ -32,7 +32,7 @@ export function createEnsureStatsServerUrlHandler(
     }
 
     if (!deps.hasLocalStatsServer()) {
-      deps.startLocalStatsServer();
+      await deps.startLocalStatsServer();
     }
     return { url: formatStatsServerUrl(deps.getConfiguredPort()), source: 'local' };
   };
diff --git a/src/main/runtime/stats-server-runtime.test.ts b/src/main/runtime/stats-server-runtime.test.ts
index 060c17e9..92f4dee0 100644
--- a/src/main/runtime/stats-server-runtime.test.ts
+++ b/src/main/runtime/stats-server-runtime.test.ts
@@ -1,10 +1,77 @@
 import assert from 'node:assert/strict';
-import test from 'node:test';
+import test, { after } from 'node:test';
+import { DEFAULT_CONFIG } from '../../config';
+import { ImmersionTrackerService } from '../../core/services/immersion-tracker-service';
+import { createAnilistRateLimiter } from '../../core/services/anilist/rate-limiter';
 import {
   createStatsServerRuntime,
   isSelfOwnedBackgroundStatsDaemonState,
-  shouldClearAppStateStatsServerOnStop,
+  type StatsServerRuntimeDeps,
 } from './stats-server-runtime';
+import type { StatsServer } from '../../core/services/stats-server';
+import type { BackgroundStatsServerState } from './stats-daemon';
+
+function createDeferred<T>() {
+  let settle: ((value: T) => void) | null = null;
+  let fail: ((error: unknown) => void) | null = null;
+  const promise = new Promise<T>((resolve, reject) => {
+    settle = resolve;
+    fail = reject;
+  });
+  return {
+    promise,
+    resolve(value: T): void {
+      if (!settle) throw new Error('deferred promise is unavailable');
+      settle(value);
+    },
+    reject(error: unknown): void {
+      if (!fail) throw new Error('deferred promise is unavailable');
+      fail(error);
+    },
+  };
+}
+
+function createRuntimeHarness(
+  startServer: NonNullable<StatsServerRuntimeDeps['startServer']>,
+  backgroundState: BackgroundStatsServerState | null = null,
+) {
+  const appStateValues: Array<StatsServer | null> = [];
+  const tracker = new ImmersionTrackerService({ dbPath: ':memory:' });
+  after(() => tracker.destroy());
+  const runtime = createStatsServerRuntime({
+    userDataPath: '/tmp/subminer-stats-runtime-test',
+    statsDistPath: '/tmp/stats-dist',
+    getResolvedConfig: () => ({
+      ...DEFAULT_CONFIG,
+      stats: { ...DEFAULT_CONFIG.stats, serverPort: 5175 },
+    }),
+    getImmersionTracker: () => tracker,
+    setAppStateStatsServer: (server) => {
+      appStateValues.push(server);
+    },
+    getMpvSocketPath: () => '/tmp/mpv.sock',
+    getYomitanExt: () => null,
+    getYomitanSession: () => null,
+    getYomitanParserWindow: () => null,
+    setYomitanParserWindow: () => {},
+    getYomitanParserReadyPromise: () => null,
+    setYomitanParserReadyPromise: () => {},
+    getYomitanParserInitPromise: () => null,
+    setYomitanParserInitPromise: () => {},
+    getYomitanAnkiDeckName: async () => 'Mining',
+    getAnilistRateLimiter: () => createAnilistRateLimiter(),
+    resolveAnkiNoteId: (noteId) => noteId,
+    trackDuplicateNoteIdsForNote: () => {},
+    resolveSentenceSearchHeadwords: async () => [],
+    ensureImmersionTrackerStarted: () => {},
+    setStatsStartupInProgress: () => {},
+    readBackgroundStatsServerState: () => backgroundState,
+    removeBackgroundStatsServerState: () => {},
+    isBackgroundStatsServerProcessAlive: () => false,
+    startServer,
+  });
+  return { runtime, appStateValues };
+}
 
 test('detects self-owned background stats daemon state', () => {
   assert.equal(
@@ -13,10 +80,6 @@ test('detects self-owned background stats daemon state', () => {
   );
 });
 
-test('stats server app-state reference should be cleared after private server stop', () => {
-  assert.equal(shouldClearAppStateStatsServerOnStop({ hadStatsServer: true }), true);
-});
-
 test('stopBackgroundStatsServer clears stale state when daemon identity mismatches', async () => {
   const calls: string[] = [];
   const runtime = createStatsServerRuntime({
@@ -57,3 +120,157 @@ test('stopBackgroundStatsServer clears stale state when daemon identity mismatch
   assert.deepEqual(result, { ok: true, stale: true });
   assert.deepEqual(calls, ['removeBackgroundStatsServerState']);
 });
+
+test('concurrent stats startup requests share one pending server', async () => {
+  const deferred = createDeferred<StatsServer>();
+  let startCalls = 0;
+  const server: StatsServer = { close: async () => {} };
+  const { runtime, appStateValues } = createRuntimeHarness(() => {
+    startCalls += 1;
+    return deferred.promise;
+  });
+
+  const first = runtime.ensureStatsServerStarted();
+  const second = runtime.ensureStatsServerStarted();
+  assert.equal(startCalls, 1);
+  assert.deepEqual(appStateValues, []);
+
+  deferred.resolve(server);
+  assert.deepEqual(await Promise.all([first, second]), [
+    { url: 'http://127.0.0.1:5175', source: 'local' },
+    { url: 'http://127.0.0.1:5175', source: 'local' },
+  ]);
+  assert.deepEqual(appStateValues, [server]);
+});
+
+test('failed stats startup remains recoverable on the next request', async () => {
+  const first = createDeferred<StatsServer>();
+  const second = createDeferred<StatsServer>();
+  const attempts = [first, second];
+  let startCalls = 0;
+  const server: StatsServer = { close: async () => {} };
+  const { runtime, appStateValues } = createRuntimeHarness(() => {
+    const attempt = attempts[startCalls];
+    startCalls += 1;
+    if (!attempt) throw new Error('unexpected startup attempt');
+    return attempt.promise;
+  });
+
+  const failedStartup = runtime.ensureStatsServerStarted();
+  first.reject(Object.assign(new Error('address in use'), { code: 'EADDRINUSE' }));
+  await assert.rejects(failedStartup, /address in use/);
+
+  const retry = runtime.ensureStatsServerStarted();
+  second.resolve(server);
+  assert.deepEqual(await retry, { url: 'http://127.0.0.1:5175', source: 'local' });
+  assert.equal(startCalls, 2);
+  assert.deepEqual(appStateValues, [null, server]);
+});
+
+test('shutdown cancels pending startup and closes the late server', async () => {
+  const deferred = createDeferred<StatsServer>();
+  let closeCalls = 0;
+  const server: StatsServer = {
+    close: async () => {
+      closeCalls += 1;
+    },
+  };
+  const { runtime, appStateValues } = createRuntimeHarness(() => deferred.promise);
+
+  const startup = runtime.ensureStatsServerStarted();
+  const shutdown = runtime.stopStatsServer();
+  deferred.resolve(server);
+
+  await assert.rejects(startup, /startup was cancelled/);
+  await shutdown;
+  assert.equal(closeCalls, 1);
+  assert.deepEqual(appStateValues, [null, null]);
+});
+
+test('stopping a self-owned background server closes its local handle', async () => {
+  let closeCalls = 0;
+  const server: StatsServer = {
+    close: async () => {
+      closeCalls += 1;
+    },
+  };
+  const { runtime } = createRuntimeHarness(async () => server, {
+    pid: process.pid,
+    port: 5175,
+    startedAtMs: 1,
+  });
+  await runtime.ensureStatsServerStarted();
+
+  assert.deepEqual(await runtime.stopBackgroundStatsServer(), { ok: true, stale: false });
+  assert.equal(closeCalls, 1);
+});
+
+test('background stop leaves a foreground-only server available', async () => {
+  let closeCalls = 0;
+  let startCalls = 0;
+  const { runtime } = createRuntimeHarness(async () => {
+    startCalls += 1;
+    return {
+      close: async () => {
+        closeCalls += 1;
+      },
+    };
+  });
+  const foreground = await runtime.ensureStatsServerStarted();
+  assert.deepEqual(await runtime.stopBackgroundStatsServer(), { ok: true, stale: true });
+  assert.equal(closeCalls, 0);
+  assert.deepEqual(await runtime.ensureStatsServerStarted(), foreground);
+  assert.equal(startCalls, 1);
+  await runtime.stopStatsServer();
+});
+
+test('background stop leaves a pending foreground-only startup alone', async () => {
+  const deferred = createDeferred<StatsServer>();
+  const { runtime } = createRuntimeHarness(() => deferred.promise);
+  const startup = runtime.ensureStatsServerStarted();
+  assert.deepEqual(await runtime.stopBackgroundStatsServer(), { ok: true, stale: true });
+  deferred.resolve({ close: async () => {} });
+  assert.deepEqual(await startup, { url: 'http://127.0.0.1:5175', source: 'local' });
+  await runtime.stopStatsServer();
+});
+
+test('a startup requested during shutdown waits and then restarts', async () => {
+  const closeDeferred = createDeferred<void>();
+  const firstServer: StatsServer = { close: () => closeDeferred.promise };
+  const secondServer: StatsServer = { close: async () => {} };
+  const servers = [firstServer, secondServer];
+  let startCalls = 0;
+  const { runtime } = createRuntimeHarness(async () => {
+    const server = servers[startCalls];
+    startCalls += 1;
+    if (!server) throw new Error('unexpected startup attempt');
+    return server;
+  });
+  await runtime.ensureStatsServerStarted();
+
+  const shutdown = runtime.stopStatsServer();
+  const restart = runtime.ensureStatsServerStarted();
+  assert.equal(startCalls, 1);
+
+  closeDeferred.resolve();
+  await shutdown;
+  assert.deepEqual(await restart, { url: 'http://127.0.0.1:5175', source: 'local' });
+  assert.equal(startCalls, 2);
+});
+
+test('background stop cancels startup before daemon ownership is published', async () => {
+  const deferred = createDeferred<StatsServer>();
+  let closeCalls = 0;
+  const { runtime, appStateValues } = createRuntimeHarness(() => deferred.promise);
+  const startup = runtime.ensureBackgroundStatsServerStarted();
+  const shutdown = runtime.stopBackgroundStatsServer();
+  deferred.resolve({
+    close: async () => {
+      closeCalls += 1;
+    },
+  });
+  await assert.rejects(startup, /startup was cancelled/);
+  assert.deepEqual(await shutdown, { ok: true, stale: false });
+  assert.equal(closeCalls, 1);
+  assert.equal(appStateValues.at(-1), null);
+});
diff --git a/src/main/runtime/stats-server-runtime.ts b/src/main/runtime/stats-server-runtime.ts
index dfe2a681..23378b78 100644
--- a/src/main/runtime/stats-server-runtime.ts
+++ b/src/main/runtime/stats-server-runtime.ts
@@ -1,10 +1,12 @@
+import { generateSentenceFurigana } from '../../core/services/tokenizer/sentence-furigana';
 import path from 'node:path';
 import type { BrowserWindow } from 'electron';
 import {
   addYomitanNoteViaSearch,
   syncYomitanDefaultAnkiServer as syncYomitanDefaultAnkiServerCore,
 } from '../../core/services';
-import { startStatsServer } from '../../core/services/stats-server';
+import { startStatsServer, type StatsServer } from '../../core/services/stats-server';
+import { createTmdbClient, createTmdbApiKeyResolver } from '../../core/services/tmdb/tmdb-client';
 import { createLogger } from '../../logger';
 import type { ResolvedConfig } from '../../types/config';
 import type { AppState } from '../state';
@@ -27,12 +29,6 @@ export function isSelfOwnedBackgroundStatsDaemonState(state: {
   return state.pid === process.pid;
 }
 
-export function shouldClearAppStateStatsServerOnStop(options: {
-  hadStatsServer: boolean;
-}): boolean {
-  return options.hadStatsServer;
-}
-
 export interface StatsServerRuntimeDeps {
   userDataPath: string;
   statsDistPath: string;
@@ -52,6 +48,8 @@ export interface StatsServerRuntimeDeps {
   getAnilistRateLimiter: () => NonNullable<
     Parameters<typeof startStatsServer>[0]['anilistRateLimiter']
   >;
+  /** Project TMDB key staged into release builds; null for source builds. */
+  getBundledTmdbApiKey?: () => string | null;
   resolveAnkiNoteId: (noteId: number) => number;
   trackDuplicateNoteIdsForNote: (noteId: number, duplicateNoteIds: number[]) => void;
   resolveSentenceSearchHeadwords: (term: string) => Promise<string[]>;
@@ -62,19 +60,28 @@ export interface StatsServerRuntimeDeps {
   isBackgroundStatsServerProcessAlive?: typeof defaultIsBackgroundStatsServerProcessAlive;
   verifyBackgroundStatsServerIdentity?: typeof defaultVerifyBackgroundStatsServerIdentity;
   killProcess?: (pid: number, signal: NodeJS.Signals) => void;
+  startServer?: typeof startStatsServer;
 }
 
 export function createStatsServerRuntime(deps: StatsServerRuntimeDeps): {
-  stopStatsServer: () => void;
+  stopStatsServer: () => Promise<void>;
   ensureStatsServerStarted: ReturnType<typeof createEnsureStatsServerUrlHandler>;
-  ensureBackgroundStatsServerStarted: () => {
+  ensureBackgroundStatsServerStarted: () => Promise<{
     url: string;
     runningInCurrentProcess: boolean;
-  };
+  }>;
   stopBackgroundStatsServer: () => Promise<{ ok: boolean; stale: boolean }>;
 } {
-  let statsServer: ReturnType<typeof startStatsServer> | null = null;
+  type LocalStatsServerState =
+    | { kind: 'stopped' }
+    | { kind: 'starting'; token: symbol; promise: Promise<void> }
+    | { kind: 'running'; server: StatsServer }
+    | { kind: 'stopping'; token: symbol; promise: Promise<void> };
+
+  let localStatsServerState: LocalStatsServerState = { kind: 'stopped' };
+  const pendingBackgroundStarts = new Set<symbol>();
   const statsDaemonStatePath = path.join(deps.userDataPath, 'stats-daemon.json');
+  const startServer = deps.startServer ?? startStatsServer;
   const readDaemonState =
     deps.readBackgroundStatsServerState ??
     ((statePath: string) => defaultReadBackgroundStatsServerState(statePath));
@@ -100,7 +107,7 @@ export function createStatsServerRuntime(deps: StatsServerRuntimeDeps): {
       removeDaemonState(statsDaemonStatePath);
       return null;
     }
-    if (state.pid === process.pid && !statsServer) {
+    if (state.pid === process.pid && localStatsServerState.kind !== 'running') {
       removeDaemonState(statsDaemonStatePath);
       return null;
     }
@@ -118,74 +125,142 @@ export function createStatsServerRuntime(deps: StatsServerRuntimeDeps): {
     }
   }
 
-  function stopStatsServer(): void {
-    if (!statsServer) {
-      return;
-    }
-    statsServer.close();
-    statsServer = null;
-    if (shouldClearAppStateStatsServerOnStop({ hadStatsServer: true })) {
-      deps.setAppStateStatsServer(null);
-    }
-    clearOwnedBackgroundStatsDaemonState();
-  }
-
-  const startLocalStatsServer = (): void => {
+  const buildStatsServerConfig = (): Parameters<typeof startStatsServer>[0] => {
     const tracker = deps.getImmersionTracker();
     if (!tracker) {
       throw new Error('Immersion tracker failed to initialize.');
     }
-    if (!statsServer) {
-      const yomitanDeps = {
-        getYomitanExt: () => deps.getYomitanExt(),
-        getYomitanSession: () => deps.getYomitanSession(),
-        getYomitanParserWindow: () => deps.getYomitanParserWindow(),
-        setYomitanParserWindow: (w: BrowserWindow | null) => {
-          deps.setYomitanParserWindow(w);
-        },
-        getYomitanParserReadyPromise: () => deps.getYomitanParserReadyPromise(),
-        setYomitanParserReadyPromise: (p: Promise<void> | null) => {
-          deps.setYomitanParserReadyPromise(p);
-        },
-        getYomitanParserInitPromise: () => deps.getYomitanParserInitPromise(),
-        setYomitanParserInitPromise: (p: Promise<boolean> | null) => {
-          deps.setYomitanParserInitPromise(p);
-        },
-      };
-      const yomitanLogger = createLogger('main:yomitan-stats');
-      statsServer = startStatsServer({
-        port: deps.getResolvedConfig().stats.serverPort,
-        staticDir: deps.statsDistPath,
-        tracker,
-        knownWordCachePath: path.join(deps.userDataPath, 'known-words-cache.json'),
-        mpvSocketPath: deps.getMpvSocketPath(),
-        getAnkiConnectConfig: () => deps.getResolvedConfig().ankiConnect,
-        getYomitanAnkiDeckName: deps.getYomitanAnkiDeckName,
-        getSecondarySubtitleLanguages: () =>
-          deps.getResolvedConfig().secondarySub.secondarySubLanguages,
-        getStatsMiningAlassPath: () => deps.getResolvedConfig().subsync.alass_path,
-        anilistRateLimiter: deps.getAnilistRateLimiter(),
-        resolveAnkiNoteId: (noteId: number) => deps.resolveAnkiNoteId(noteId),
-        resolveSentenceSearchHeadwords: (term: string) => deps.resolveSentenceSearchHeadwords(term),
-        addYomitanNote: async (word: string) => {
-          const ankiConnectConfig = deps.getResolvedConfig().ankiConnect;
-          const ankiUrl = ankiConnectConfig.url || 'http://127.0.0.1:8765';
-          await syncYomitanDefaultAnkiServerCore(ankiUrl, yomitanDeps, yomitanLogger, {
-            forceOverride: shouldForceOverrideYomitanAnkiServer(ankiConnectConfig),
-            deck: ankiConnectConfig.deck,
-          });
-          const result = await addYomitanNoteViaSearch(word, yomitanDeps, yomitanLogger);
-          if (result.noteId && result.duplicateNoteIds.length > 0) {
-            deps.trackDuplicateNoteIdsForNote(result.noteId, result.duplicateNoteIds);
-          }
-          return result.noteId;
-        },
-      });
-      deps.setAppStateStatsServer(statsServer);
-    }
-    deps.setAppStateStatsServer(statsServer);
+    const yomitanDeps = {
+      getYomitanExt: () => deps.getYomitanExt(),
+      getYomitanSession: () => deps.getYomitanSession(),
+      getYomitanParserWindow: () => deps.getYomitanParserWindow(),
+      setYomitanParserWindow: (w: BrowserWindow | null) => {
+        deps.setYomitanParserWindow(w);
+      },
+      getYomitanParserReadyPromise: () => deps.getYomitanParserReadyPromise(),
+      setYomitanParserReadyPromise: (p: Promise<void> | null) => {
+        deps.setYomitanParserReadyPromise(p);
+      },
+      getYomitanParserInitPromise: () => deps.getYomitanParserInitPromise(),
+      setYomitanParserInitPromise: (p: Promise<boolean> | null) => {
+        deps.setYomitanParserInitPromise(p);
+      },
+    };
+    const yomitanLogger = createLogger('main:yomitan-stats');
+    return {
+      port: deps.getResolvedConfig().stats.serverPort,
+      staticDir: deps.statsDistPath,
+      tracker,
+      knownWordCachePath: path.join(deps.userDataPath, 'known-words-cache.json'),
+      mpvSocketPath: deps.getMpvSocketPath(),
+      getAnkiConnectConfig: () => deps.getResolvedConfig().ankiConnect,
+      getYomitanAnkiDeckName: deps.getYomitanAnkiDeckName,
+      getSecondarySubtitleLanguages: () =>
+        deps.getResolvedConfig().secondarySub.secondarySubLanguages,
+      getStatsMiningAlassPath: () => deps.getResolvedConfig().subsync.alass_path,
+      anilistRateLimiter: deps.getAnilistRateLimiter(),
+      tmdbClient: createTmdbClient({
+        resolveApiKey: createTmdbApiKeyResolver(
+          () => deps.getResolvedConfig().tmdb,
+          () => deps.getBundledTmdbApiKey?.() ?? null,
+        ),
+      }),
+      resolveAnkiNoteId: (noteId: number) => deps.resolveAnkiNoteId(noteId),
+      resolveSentenceSearchHeadwords: (term: string) => deps.resolveSentenceSearchHeadwords(term),
+      generateSentenceFurigana: (text, highlightedText) =>
+        generateSentenceFurigana(text, highlightedText, yomitanDeps, yomitanLogger),
+      addYomitanNote: async (word: string) => {
+        const ankiConnectConfig = deps.getResolvedConfig().ankiConnect;
+        const ankiUrl = ankiConnectConfig.url || 'http://127.0.0.1:8765';
+        await syncYomitanDefaultAnkiServerCore(ankiUrl, yomitanDeps, yomitanLogger, {
+          forceOverride: shouldForceOverrideYomitanAnkiServer(ankiConnectConfig),
+          deck: ankiConnectConfig.deck,
+        });
+        const result = await addYomitanNoteViaSearch(word, yomitanDeps, yomitanLogger);
+        if (result.noteId && result.duplicateNoteIds.length > 0) {
+          deps.trackDuplicateNoteIdsForNote(result.noteId, result.duplicateNoteIds);
+        }
+        return result.noteId;
+      },
+    };
   };
 
+  const beginLocalStatsServerStartup = (): Promise<void> => {
+    const token = Symbol('stats-server-startup');
+    const promise = startServer(buildStatsServerConfig())
+      .then(async (server) => {
+        const state = localStatsServerState;
+        if (state.kind !== 'starting' || state.token !== token) {
+          await server.close();
+          throw new Error('Stats server startup was cancelled.');
+        }
+        localStatsServerState = { kind: 'running', server };
+        deps.setAppStateStatsServer(server);
+      })
+      .catch((error: unknown) => {
+        const state = localStatsServerState;
+        if (state.kind === 'starting' && state.token === token) {
+          localStatsServerState = { kind: 'stopped' };
+          deps.setAppStateStatsServer(null);
+        }
+        throw error;
+      });
+    localStatsServerState = { kind: 'starting', token, promise };
+    return promise;
+  };
+
+  const startLocalStatsServer = async (): Promise<void> => {
+    while (localStatsServerState.kind === 'stopping') {
+      await localStatsServerState.promise;
+    }
+    if (localStatsServerState.kind === 'running') {
+      deps.setAppStateStatsServer(localStatsServerState.server);
+      return;
+    }
+    if (localStatsServerState.kind === 'starting') {
+      await localStatsServerState.promise;
+      return;
+    }
+    await beginLocalStatsServerStartup();
+  };
+
+  function stopStatsServer(): Promise<void> {
+    const state = localStatsServerState;
+    if (state.kind === 'stopped') {
+      deps.setAppStateStatsServer(null);
+      clearOwnedBackgroundStatsDaemonState();
+      return Promise.resolve();
+    }
+    if (state.kind === 'stopping') {
+      return state.promise;
+    }
+
+    const token = Symbol('stats-server-shutdown');
+    const promise = Promise.resolve()
+      .then(async () => {
+        if (state.kind === 'starting') {
+          try {
+            await state.promise;
+          } catch {
+            // Startup owns cleanup of a server that finishes binding after cancellation.
+          }
+          return;
+        }
+        await state.server.close();
+      })
+      .finally(() => {
+        const current = localStatsServerState;
+        if (current.kind === 'stopping' && current.token === token) {
+          localStatsServerState = { kind: 'stopped' };
+        }
+        deps.setAppStateStatsServer(null);
+        clearOwnedBackgroundStatsDaemonState();
+      });
+    localStatsServerState = { kind: 'stopping', token, promise };
+    deps.setAppStateStatsServer(null);
+    return promise;
+  }
+
   const ensureStatsServerStarted = createEnsureStatsServerUrlHandler({
     currentPid: process.pid,
     readBackgroundState: () => readDaemonState(statsDaemonStatePath),
@@ -193,15 +268,15 @@ export function createStatsServerRuntime(deps: StatsServerRuntimeDeps): {
       removeDaemonState(statsDaemonStatePath);
     },
     isProcessAlive: (pid) => isDaemonAlive(pid),
-    hasLocalStatsServer: () => statsServer !== null,
+    hasLocalStatsServer: () => localStatsServerState.kind === 'running',
     startLocalStatsServer,
     getConfiguredPort: () => deps.getResolvedConfig().stats.serverPort,
   });
 
-  const ensureBackgroundStatsServerStarted = (): {
+  const ensureBackgroundStatsServerStarted = async (): Promise<{
     url: string;
     runningInCurrentProcess: boolean;
-  } => {
+  }> => {
     const liveDaemon = readLiveBackgroundStatsDaemonState();
     if (liveDaemon && liveDaemon.pid !== process.pid) {
       return {
@@ -217,27 +292,40 @@ export function createStatsServerRuntime(deps: StatsServerRuntimeDeps): {
       deps.setStatsStartupInProgress(false);
     }
 
-    const port = deps.getResolvedConfig().stats.serverPort;
-    const result = ensureStatsServerStarted();
-    if (result.source === 'local') {
-      writeBackgroundStatsServerState(statsDaemonStatePath, {
-        pid: process.pid,
-        port,
-        startedAtMs: Date.now(),
-      });
+    const request = Symbol('background-stats-startup');
+    pendingBackgroundStarts.add(request);
+    try {
+      const port = deps.getResolvedConfig().stats.serverPort;
+      const result = await ensureStatsServerStarted();
+      if (result.source === 'local') {
+        if (localStatsServerState.kind !== 'running') {
+          throw new Error('Stats server startup was cancelled.');
+        }
+        writeBackgroundStatsServerState(statsDaemonStatePath, {
+          pid: process.pid,
+          port,
+          startedAtMs: Date.now(),
+        });
+      }
+      return { url: result.url, runningInCurrentProcess: result.source === 'local' };
+    } finally {
+      pendingBackgroundStarts.delete(request);
     }
-    return { url: result.url, runningInCurrentProcess: result.source === 'local' };
   };
 
   const stopBackgroundStatsServer = async (): Promise<{ ok: boolean; stale: boolean }> => {
     const state = readDaemonState(statsDaemonStatePath);
     if (!state) {
+      if (pendingBackgroundStarts.size > 0) {
+        await stopStatsServer();
+        return { ok: true, stale: false };
+      }
       removeDaemonState(statsDaemonStatePath);
       return { ok: true, stale: true };
     }
     if (isSelfOwnedBackgroundStatsDaemonState(state)) {
-      removeDaemonState(statsDaemonStatePath);
-      return { ok: true, stale: true };
+      await stopStatsServer();
+      return { ok: true, stale: false };
     }
     if (!isDaemonAlive(state.pid)) {
       removeDaemonState(statsDaemonStatePath);
diff --git a/src/main/runtime/subtitle-generation-ipc.ts b/src/main/runtime/subtitle-generation-ipc.ts
new file mode 100644
index 00000000..5f8384ec
--- /dev/null
+++ b/src/main/runtime/subtitle-generation-ipc.ts
@@ -0,0 +1,43 @@
+import type { IpcMain, WebContents } from 'electron';
+import { IPC_CHANNELS } from '../../shared/ipc/contracts';
+import { isSubtitleGenerationModelId } from '../../shared/subtitle-generation-model-catalog';
+import type { createSubtitleGenerationRuntime } from './subtitle-generation-runtime';
+
+export function registerSubtitleGenerationIpc(deps: {
+  ipc: Pick<IpcMain, 'handle'>;
+  isAllowedSender: (sender: WebContents) => boolean;
+  openModal: () => Promise<boolean>;
+  runtime: ReturnType<typeof createSubtitleGenerationRuntime>;
+}): void {
+  const handlers = [
+    [IPC_CHANNELS.request.requestSubtitleGenerationOpen, () => deps.openModal()],
+    [IPC_CHANNELS.request.getSubtitleGenerationStatus, () => deps.runtime.getStatus()],
+    [
+      IPC_CHANNELS.request.selectSubtitleGenerationModel,
+      (model: unknown) => {
+        if (!isSubtitleGenerationModelId(model))
+          throw new Error('Unknown subtitle generation model.');
+        return deps.runtime.selectModel(model);
+      },
+    ],
+    [IPC_CHANNELS.request.startSubtitleGeneration, () => deps.runtime.start()],
+    [IPC_CHANNELS.request.downloadSubtitleGenerationModel, () => deps.runtime.download()],
+    [IPC_CHANNELS.request.downloadSubtitleGenerationVadModel, () => deps.runtime.downloadVad()],
+    [
+      IPC_CHANNELS.request.setSubtitleGenerationVadEnabled,
+      (enabled: unknown) => {
+        if (typeof enabled !== 'boolean')
+          throw new Error('Speech detection selection must be a boolean.');
+        return deps.runtime.setVadEnabled(enabled);
+      },
+    ],
+    [IPC_CHANNELS.request.cancelSubtitleGeneration, () => deps.runtime.cancel()],
+  ] as const;
+  for (const [channel, handler] of handlers) {
+    deps.ipc.handle(channel, (event, payload: unknown) => {
+      if (!deps.isAllowedSender(event.sender))
+        throw new Error('Subtitle generation is only available from the overlay.');
+      return handler(payload);
+    });
+  }
+}
diff --git a/src/main/runtime/subtitle-generation-open.test.ts b/src/main/runtime/subtitle-generation-open.test.ts
new file mode 100644
index 00000000..1b2951c3
--- /dev/null
+++ b/src/main/runtime/subtitle-generation-open.test.ts
@@ -0,0 +1,36 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { openSubtitleGenerationModal } from './subtitle-generation-open';
+import { IPC_CHANNELS } from '../../shared/ipc/contracts';
+
+test('subtitle generation opens in the dedicated modal window with normal close restoration', async () => {
+  const calls: string[] = [];
+  const opened = await openSubtitleGenerationModal({
+    ensureOverlayStartupPrereqs: () => {
+      calls.push('startup');
+    },
+    ensureOverlayWindowsReadyForVisibilityActions: () => {
+      calls.push('windows');
+    },
+    sendToActiveOverlayWindow: (channel, payload, options) => {
+      assert.deepEqual(calls, ['startup', 'windows']);
+      assert.equal(channel, IPC_CHANNELS.event.subtitleGenerationOpen);
+      assert.equal(payload, undefined);
+      assert.deepEqual(options, {
+        restoreOnModalClose: 'subtitle-generation',
+        preferModalWindow: true,
+      });
+      calls.push('open');
+      return true;
+    },
+    waitForModalOpen: async (modal) => {
+      assert.equal(modal, 'subtitle-generation');
+      return true;
+    },
+    logWarn: () => {
+      assert.fail('opening should not require a retry');
+    },
+  });
+  assert.equal(opened, true);
+  assert.deepEqual(calls, ['startup', 'windows', 'open']);
+});
diff --git a/src/main/runtime/subtitle-generation-open.ts b/src/main/runtime/subtitle-generation-open.ts
new file mode 100644
index 00000000..7e6c6070
--- /dev/null
+++ b/src/main/runtime/subtitle-generation-open.ts
@@ -0,0 +1,18 @@
+import { IPC_CHANNELS } from '../../shared/ipc/contracts';
+import { openOverlayHostedModal, retryOverlayModalOpen } from './overlay-hosted-modal-open';
+
+export function openSubtitleGenerationModal(
+  deps: Parameters<typeof openOverlayHostedModal>[0] & Parameters<typeof retryOverlayModalOpen>[0],
+): Promise<boolean> {
+  return retryOverlayModalOpen(deps, {
+    modal: 'subtitle-generation',
+    timeoutMs: 1500,
+    retryWarning: 'Subtitle generation modal did not acknowledge opening; retrying.',
+    sendOpen: () =>
+      openOverlayHostedModal(deps, {
+        channel: IPC_CHANNELS.event.subtitleGenerationOpen,
+        modal: 'subtitle-generation',
+        preferModalWindow: true,
+      }),
+  });
+}
diff --git a/src/main/runtime/subtitle-generation-runtime.test.ts b/src/main/runtime/subtitle-generation-runtime.test.ts
new file mode 100644
index 00000000..1c0b7bbc
--- /dev/null
+++ b/src/main/runtime/subtitle-generation-runtime.test.ts
@@ -0,0 +1,315 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { DEFAULT_SUBTITLE_GENERATION_CONFIG } from '../../shared/subtitle-generation';
+import {
+  createSubtitleGenerationRuntime,
+  type SubtitleGenerationRuntimeDeps,
+} from './subtitle-generation-runtime';
+
+function fixture(overrides: Partial<SubtitleGenerationRuntimeDeps> = {}) {
+  let mediaPath = '/video/episode.mkv';
+  const commands: unknown[][] = [];
+  const client = {
+    connected: true,
+    requestProperty: async (name: string): Promise<unknown> =>
+      name === 'path' ? mediaPath : [{ type: 'audio', selected: true, 'ff-index': 3 }],
+    request: async (command: unknown[]) => {
+      commands.push(command);
+      return { error: 'success' };
+    },
+  };
+  const runtime = createSubtitleGenerationRuntime({
+    getConfig: () => DEFAULT_SUBTITLE_GENERATION_CONFIG,
+    getModelDirectory: () => '/models',
+    getMpvClient: () => client,
+    onProgress: () => {},
+    detectAcceleration: async () => ({ kind: 'unavailable' }),
+    resolveModel: async () => ({ kind: 'external', path: '/models/local.bin' }),
+    resolveTools: async (config) => ({
+      ffmpeg: { kind: 'found', path: '/usr/bin/ffmpeg' },
+      ffprobe: { kind: 'found', path: '/usr/bin/ffprobe' },
+      whisper: { kind: 'found', path: '/usr/bin/whisper-cli' },
+      vad: config.vadModelPath ? { kind: 'found', path: '/usr/bin/vad' } : null,
+    }),
+    generate: async () => '/video/episode.ja.generated.srt',
+    ...overrides,
+  });
+  return {
+    runtime,
+    client,
+    commands,
+    changeMedia: () => {
+      mediaPath = '/video/next.mkv';
+    },
+  };
+}
+
+test('generation uses the selected audio track and loads the timed SRT with zero delay', async () => {
+  const { runtime, commands } = fixture({
+    generate: async (input) => {
+      assert.equal(input.mediaPath, '/video/episode.mkv');
+      assert.equal(input.audioStreamIndex, 3);
+      return '/video/generated.srt';
+    },
+  });
+  assert.equal((await runtime.start()).ok, true);
+  assert.deepEqual(commands, [
+    ['sub-add', '/video/generated.srt', 'select', 'Generated Japanese', 'ja'],
+    ['set_property', 'sub-delay', 0],
+  ]);
+});
+
+test('generation preserves the output without attaching it to a different video', async () => {
+  const subject = fixture({
+    generate: async () => {
+      subject.changeMedia();
+      return '/video/generated.srt';
+    },
+  });
+  const result = await subject.runtime.start();
+  assert.equal(result.ok, true);
+  assert.match(result.message, /Playback changed/);
+  assert.deepEqual(subject.commands, []);
+});
+
+test('generation selects loaded dialogue references and excludes the signs track', async () => {
+  const subject = fixture({
+    generate: async (input) => {
+      assert.deepEqual(input.references, [
+        { label: 'English Full', delaySeconds: 0, source: { kind: 'embedded', streamIndex: 5 } },
+      ]);
+      return '/video/generated.srt';
+    },
+  });
+  const request = subject.client.requestProperty;
+  subject.client.requestProperty = async (name) =>
+    name === 'track-list'
+      ? [
+          { type: 'audio', selected: true, 'ff-index': 3 },
+          { type: 'sub', lang: 'eng', title: 'Signs & Songs', 'ff-index': 4 },
+          { type: 'sub', lang: 'eng', title: 'English Full', 'ff-index': 5 },
+        ]
+      : request(name);
+  assert.equal((await subject.runtime.start()).ok, true);
+});
+
+test('mpv load failure still reports where the generated subtitles were saved', async () => {
+  const subject = fixture();
+  subject.client.request = async () => ({ error: 'loading failed' });
+  const result = await subject.runtime.start();
+  assert.equal(result.ok, true);
+  assert.match(result.message, /Subtitles saved:.*Could not finish loading/);
+});
+
+test('cancellation during the final media check keeps the saved file without loading it', async () => {
+  const subject = fixture();
+  const requestProperty = subject.client.requestProperty;
+  let mediaChecks = 0;
+  subject.client.requestProperty = async (name) => {
+    if (name === 'path' && ++mediaChecks === 3) subject.runtime.cancel();
+    return requestProperty(name);
+  };
+  const result = await subject.runtime.start();
+  assert.equal(result.ok, true);
+  assert.match(result.message, /Cancelled after saving/);
+  assert.deepEqual(subject.commands, []);
+});
+
+test('only one job runs, cancellation reaches the worker, and status retains its result', async () => {
+  let signal: AbortSignal | undefined;
+  let entered = () => {};
+  const started = new Promise<void>((resolve) => {
+    entered = resolve;
+  });
+  const { runtime } = fixture({
+    generate: async (input) => {
+      signal = input.signal;
+      input.onProgress?.({ stage: 'transcribe', percent: 25, message: 'Working' });
+      entered();
+      return new Promise((_, reject) =>
+        input.signal?.addEventListener('abort', () => reject(new Error('Aborted')), { once: true }),
+      );
+    },
+  });
+  const first = runtime.start();
+  await started;
+  await assert.rejects(runtime.selectModel('medium'), /current operation/);
+  assert.equal((await runtime.start()).ok, false);
+  assert.equal((await runtime.download()).ok, false);
+  const active = await runtime.getStatus();
+  assert.equal(active.running, true);
+  assert.equal(active.progress?.percent, 25);
+  runtime.cancel();
+  assert.equal(signal?.aborted, true);
+  assert.deepEqual(await first, { ok: false, message: 'Cancelled.' });
+  const completed = await runtime.getStatus();
+  assert.equal(completed.running, false);
+  assert.deepEqual(completed.lastResult, { ok: false, message: 'Cancelled.' });
+});
+
+test('external audio cannot silently generate from a different internal track', async () => {
+  const subject = fixture({
+    generate: async () => {
+      assert.fail('must not transcribe');
+    },
+  });
+  subject.client.requestProperty = async (name) =>
+    name === 'path'
+      ? '/video/episode.mkv'
+      : [{ type: 'audio', selected: true, external: true, 'ff-index': 0 }];
+  const result = await subject.runtime.start();
+  assert.equal(result.ok, false);
+  assert.match(result.message, /audio track inside/);
+});
+
+test('model selection is retained and used for status, download, and generation', async () => {
+  const seen: string[] = [];
+  const { runtime } = fixture({
+    resolveModel: async (config) => ({
+      kind: 'missing',
+      path: `/models/${config.managedModel}.bin`,
+    }),
+    download: async ({ config }) => {
+      seen.push(`download:${config.managedModel}`);
+      return '/models/downloaded.bin';
+    },
+    generate: async ({ config }) => {
+      seen.push(`generate:${config.managedModel}`);
+      return '/video/generated.srt';
+    },
+  });
+  const selected = await runtime.selectModel('medium');
+  assert.equal(selected.managedModel, 'medium');
+  assert.equal(selected.model.path, '/models/medium.bin');
+  assert.equal((await runtime.getStatus()).managedModel, 'medium');
+  assert.equal((await runtime.download()).ok, true);
+  assert.equal((await runtime.start()).ok, true);
+  assert.deepEqual(seen, ['download:medium', 'generate:medium']);
+  assert.equal(DEFAULT_SUBTITLE_GENERATION_CONFIG.managedModel, 'small');
+});
+
+test('external model paths prevent managed selection, including unreadable overrides', async () => {
+  const { runtime } = fixture({
+    getConfig: () => ({
+      ...DEFAULT_SUBTITLE_GENERATION_CONFIG,
+      modelPath: '/missing/external.bin',
+    }),
+    resolveModel: async () => ({
+      kind: 'invalid',
+      path: '/missing/external.bin',
+      message: 'Missing model',
+    }),
+  });
+  assert.equal((await runtime.getStatus()).externalModelPath, '/missing/external.bin');
+  await assert.rejects(runtime.selectModel('medium'), /Clear Model Path/);
+});
+
+test('CUDA recommendations preserve selected and configured models and follow the Whisper path', async () => {
+  let whisperPath = '/cuda/whisper-cli';
+  const checked: string[] = [];
+  const subject = fixture({
+    getConfig: () => ({ ...DEFAULT_SUBTITLE_GENERATION_CONFIG, managedModel: 'medium' }),
+    resolveTools: async () => ({
+      ffmpeg: { kind: 'found', path: '/usr/bin/ffmpeg' },
+      ffprobe: { kind: 'found', path: '/usr/bin/ffprobe' },
+      whisper: { kind: 'found', path: whisperPath },
+      vad: null,
+    }),
+    detectAcceleration: async (whisper) => {
+      assert.equal(whisper.kind, 'found');
+      if (whisper.kind !== 'found') throw new Error('Expected a Whisper executable');
+      checked.push(whisper.path);
+      return whisper.path.startsWith('/cuda/')
+        ? { kind: 'nvidia-cuda', gpuName: 'NVIDIA Test GPU' }
+        : { kind: 'unavailable' };
+    },
+  });
+  const initial = await subject.runtime.getStatus();
+  assert.deepEqual(initial.acceleration, { kind: 'nvidia-cuda', gpuName: 'NVIDIA Test GPU' });
+  assert.equal(initial.managedModel, 'medium');
+  const selected = await subject.runtime.selectModel('small');
+  assert.equal(selected.managedModel, 'small');
+  assert.equal(selected.acceleration.kind, 'nvidia-cuda');
+  assert.deepEqual(checked, ['/cuda/whisper-cli']);
+  whisperPath = '/cpu/whisper-cli';
+  const changed = await subject.runtime.getStatus();
+  assert.equal(changed.acceleration.kind, 'unavailable');
+  assert.equal(changed.managedModel, 'small');
+  assert.deepEqual(checked, ['/cuda/whisper-cli', '/cpu/whisper-cli']);
+});
+
+test('status reports the speech detector only while dialogue mode is on', async () => {
+  const { runtime } = fixture({
+    resolveVadModel: async () => ({ kind: 'managed', path: '/models/ggml-silero-v6.2.0.bin' }),
+  });
+  assert.equal((await runtime.getStatus()).tools.vad, null);
+  await runtime.setVadEnabled(true);
+  assert.deepEqual((await runtime.getStatus()).tools.vad, { kind: 'found', path: '/usr/bin/vad' });
+});
+
+test('speech detection is optional and downloading alone does not enable it', async () => {
+  let installed = false;
+  const paths: string[] = [];
+  const { runtime } = fixture({
+    resolveVadModel: async () => ({
+      kind: installed ? 'managed' : 'missing',
+      path: '/models/ggml-silero-v6.2.0.bin',
+    }),
+    downloadVad: async () => {
+      installed = true;
+      return '/models/ggml-silero-v6.2.0.bin';
+    },
+    generate: async ({ config }) => {
+      paths.push(config.vadModelPath);
+      return '/video/output.srt';
+    },
+  });
+  assert.equal((await runtime.getStatus()).vad.enabled, false);
+  assert.equal((await runtime.start()).ok, true);
+  await runtime.setVadEnabled(true);
+  assert.equal((await runtime.start()).ok, false);
+  await runtime.setVadEnabled(false);
+  assert.equal((await runtime.downloadVad()).ok, true);
+  assert.equal((await runtime.getStatus()).vad.enabled, false);
+  await runtime.setVadEnabled(true);
+  assert.equal((await runtime.start()).ok, true);
+  await runtime.setVadEnabled(false);
+  assert.equal((await runtime.start()).ok, true);
+  assert.deepEqual(paths, ['', '/models/ggml-silero-v6.2.0.bin', '']);
+});
+
+test('existing external speech model remains the default and survives session toggles', async () => {
+  const { runtime } = fixture({
+    getConfig: () => ({ ...DEFAULT_SUBTITLE_GENERATION_CONFIG, vadModelPath: '/external/vad.bin' }),
+    resolveVadModel: async (config) => ({ kind: 'external', path: config.vadModelPath }),
+    generate: async ({ config }) => {
+      assert.equal(config.vadModelPath, '/external/vad.bin');
+      return '/video/output.srt';
+    },
+  });
+  assert.equal((await runtime.getStatus()).vad.enabled, true);
+  await runtime.setVadEnabled(false);
+  await runtime.setVadEnabled(true);
+  assert.equal((await runtime.start()).ok, true);
+});
+
+test('speech model downloads share the job lock and cancellation', async () => {
+  let enter = () => {};
+  const started = new Promise<void>((resolve) => {
+    enter = resolve;
+  });
+  const { runtime } = fixture({
+    downloadVad: async ({ signal }) => {
+      enter();
+      return new Promise((_, reject) =>
+        signal?.addEventListener('abort', () => reject(new Error('cancelled')), { once: true }),
+      );
+    },
+  });
+  const download = runtime.downloadVad();
+  await started;
+  assert.equal((await runtime.start()).ok, false);
+  await assert.rejects(runtime.setVadEnabled(true), /current operation/);
+  runtime.cancel();
+  assert.deepEqual(await download, { ok: false, message: 'Cancelled.' });
+});
diff --git a/src/main/runtime/subtitle-generation-runtime.ts b/src/main/runtime/subtitle-generation-runtime.ts
new file mode 100644
index 00000000..94176c83
--- /dev/null
+++ b/src/main/runtime/subtitle-generation-runtime.ts
@@ -0,0 +1,294 @@
+import path from 'node:path';
+import { readSubtitleGenerationReferences } from '../../core/services/subtitle-generation-reference';
+import { detectSubtitleGenerationAcceleration } from '../../core/services/subtitle-generation-acceleration';
+import { SUBTITLE_GENERATION_VAD_MODEL } from '../../shared/subtitle-generation-vad-model';
+import {
+  downloadSubtitleGenerationVadModel,
+  resolveSubtitleGenerationVadModel,
+} from '../../core/services/subtitle-generation-vad-model';
+import type { SubtitleGenerationModelId } from '../../shared/subtitle-generation-model-catalog';
+import {
+  downloadSubtitleGenerationModel,
+  generateJapaneseSubtitles,
+  resolveSubtitleGenerationModel,
+  resolveSubtitleGenerationTools,
+} from '../../core/services/subtitle-generation';
+import type {
+  SubtitleGenerationConfig,
+  SubtitleGenerationProgress,
+} from '../../shared/subtitle-generation';
+import type {
+  SubtitleGenerationResult,
+  SubtitleGenerationStatus,
+} from '../../shared/subtitle-generation-ipc';
+
+interface GenerationMpvClient {
+  connected: boolean;
+  requestProperty: (name: string) => Promise<unknown>;
+  request: (command: unknown[]) => Promise<{ error?: string }>;
+}
+
+export interface SubtitleGenerationRuntimeDeps {
+  getConfig: () => SubtitleGenerationConfig;
+  getModelDirectory: () => string;
+  getMpvClient: () => GenerationMpvClient | null;
+  onProgress: (progress: SubtitleGenerationProgress) => void;
+  generate?: typeof generateJapaneseSubtitles;
+  download?: typeof downloadSubtitleGenerationModel;
+  resolveModel?: typeof resolveSubtitleGenerationModel;
+  resolveTools?: typeof resolveSubtitleGenerationTools;
+  detectAcceleration?: typeof detectSubtitleGenerationAcceleration;
+  downloadVad?: typeof downloadSubtitleGenerationVadModel;
+  resolveVadModel?: typeof resolveSubtitleGenerationVadModel;
+}
+
+async function currentLocalMedia(client: GenerationMpvClient | null): Promise<string | null> {
+  if (!client?.connected) return null;
+  const media = await client.requestProperty('path');
+  if (typeof media !== 'string' || !media || /^[a-z][a-z\d+.-]*:\/\//i.test(media)) return null;
+  if (path.isAbsolute(media)) return path.normalize(media);
+  const directory = await client.requestProperty('working-directory');
+  return typeof directory === 'string' ? path.resolve(directory, media) : null;
+}
+
+function selectedAudioIndex(tracks: unknown): number {
+  if (!Array.isArray(tracks)) throw new Error('Unable to inspect the selected audio track.');
+  for (const track of tracks) {
+    if (
+      !track ||
+      typeof track !== 'object' ||
+      !('type' in track) ||
+      track.type !== 'audio' ||
+      !('selected' in track) ||
+      track.selected !== true
+    )
+      continue;
+    if ('external' in track && track.external === true)
+      throw new Error('Select an audio track inside the local video before generating subtitles.');
+    if (
+      'ff-index' in track &&
+      typeof track['ff-index'] === 'number' &&
+      Number.isInteger(track['ff-index']) &&
+      track['ff-index'] >= 0
+    )
+      return track['ff-index'];
+    throw new Error('The selected audio track has no FFmpeg stream index.');
+  }
+  throw new Error('Select an audio track in mpv before generating subtitles.');
+}
+
+export function createSubtitleGenerationRuntime(deps: SubtitleGenerationRuntimeDeps) {
+  let controller: AbortController | null = null;
+  let progress: SubtitleGenerationProgress | null = null;
+  let lastResult: SubtitleGenerationResult | null = null;
+  let selectedModel: SubtitleGenerationModelId | null = null;
+  let vadEnabled: boolean | null = null;
+  let accelerationCheck:
+    | {
+        path: string;
+        expires: number;
+        result: ReturnType<typeof detectSubtitleGenerationAcceleration>;
+      }
+    | undefined;
+  function getConfig(): SubtitleGenerationConfig {
+    const config = deps.getConfig();
+    return {
+      ...config,
+      managedModel: selectedModel ?? config.managedModel,
+      vadModelPath:
+        vadEnabled === null
+          ? config.vadModelPath
+          : vadEnabled
+            ? config.vadModelPath.trim() ||
+              path.resolve(deps.getModelDirectory(), SUBTITLE_GENERATION_VAD_MODEL.filename)
+            : '',
+    };
+  }
+  const report = (update: SubtitleGenerationProgress) => {
+    progress = update;
+    deps.onProgress(update);
+  };
+
+  async function run(
+    operation: (signal: AbortSignal) => Promise<SubtitleGenerationResult>,
+  ): Promise<SubtitleGenerationResult> {
+    if (controller)
+      return { ok: false, message: 'A subtitle generation or model download is already running.' };
+    const active = new AbortController();
+    controller = active;
+    progress = null;
+    lastResult = null;
+    try {
+      lastResult = await operation(active.signal);
+    } catch (error) {
+      lastResult = {
+        ok: false,
+        message: active.signal.aborted
+          ? 'Cancelled.'
+          : error instanceof Error
+            ? error.message
+            : String(error),
+      };
+    } finally {
+      controller = null;
+    }
+    return lastResult;
+  }
+
+  async function getStatus(): Promise<SubtitleGenerationStatus> {
+    const config = getConfig();
+    const tools = await (deps.resolveTools ?? resolveSubtitleGenerationTools)(config);
+    const whisperPath = tools.whisper.kind === 'found' ? tools.whisper.path : '';
+    if (
+      !accelerationCheck ||
+      accelerationCheck.path !== whisperPath ||
+      (!controller && Date.now() >= accelerationCheck.expires)
+    ) {
+      accelerationCheck = {
+        path: whisperPath,
+        expires: Date.now() + 30_000,
+        result: (deps.detectAcceleration ?? detectSubtitleGenerationAcceleration)(tools.whisper),
+      };
+    }
+    const acceleration = await accelerationCheck.result;
+    const model = await (deps.resolveModel ?? resolveSubtitleGenerationModel)(
+      config,
+      deps.getModelDirectory(),
+    );
+    const mediaPath = await currentLocalMedia(deps.getMpvClient()).catch(() => null);
+    return {
+      model,
+      vad: {
+        enabled: Boolean(config.vadModelPath.trim()),
+        model: await (deps.resolveVadModel ?? resolveSubtitleGenerationVadModel)(
+          deps.getConfig(),
+          deps.getModelDirectory(),
+        ),
+      },
+      // Session toggles decide whether the speech detector executable is required.
+      tools,
+      acceleration,
+      managedModel: config.managedModel,
+      externalModelPath: config.modelPath.trim() || null,
+      mediaPath,
+      running: controller !== null,
+      progress,
+      lastResult,
+    };
+  }
+
+  return {
+    getStatus,
+    async setVadEnabled(enabled: boolean): Promise<SubtitleGenerationStatus> {
+      if (controller)
+        throw new Error('Wait for the current operation before changing speech detection.');
+      vadEnabled = enabled;
+      lastResult = null;
+      progress = null;
+      return getStatus();
+    },
+    downloadVad(): Promise<SubtitleGenerationResult> {
+      return run(async (signal) => {
+        await (deps.downloadVad ?? downloadSubtitleGenerationVadModel)({
+          config: deps.getConfig(),
+          modelDirectory: deps.getModelDirectory(),
+          onProgress: report,
+          signal,
+        });
+        return { ok: true, message: 'Speech detection model is ready.' };
+      });
+    },
+    async selectModel(model: SubtitleGenerationModelId): Promise<SubtitleGenerationStatus> {
+      if (controller) throw new Error('Wait for the current operation before changing models.');
+      if (deps.getConfig().modelPath.trim())
+        throw new Error('Clear Model Path in Settings before choosing a managed model.');
+      selectedModel = model;
+      lastResult = null;
+      progress = null;
+      return getStatus();
+    },
+    cancel(): void {
+      controller?.abort();
+    },
+    download(): Promise<SubtitleGenerationResult> {
+      return run(async (signal) => {
+        await (deps.download ?? downloadSubtitleGenerationModel)({
+          config: getConfig(),
+          modelDirectory: deps.getModelDirectory(),
+          onProgress: report,
+          signal,
+        });
+        return { ok: true, message: 'Model downloaded. Ready to generate Japanese subtitles.' };
+      });
+    },
+    start(): Promise<SubtitleGenerationResult> {
+      return run(async (signal) => {
+        const config = getConfig();
+        if (config.vadModelPath.trim()) {
+          const vad = await (deps.resolveVadModel ?? resolveSubtitleGenerationVadModel)(
+            deps.getConfig(),
+            deps.getModelDirectory(),
+          );
+          if (vad.kind === 'missing')
+            throw new Error(
+              'Download the optional speech detection model or turn off Focus on spoken dialogue.',
+            );
+          if (vad.kind === 'invalid') throw new Error(vad.message);
+        }
+        const client = deps.getMpvClient();
+        const mediaPath = await currentLocalMedia(client);
+        if (!client || !mediaPath)
+          throw new Error('Open a local video or audio file in mpv first.');
+        const tracks = await client.requestProperty('track-list');
+        const audioStreamIndex = selectedAudioIndex(tracks);
+        const references = await readSubtitleGenerationReferences(tracks, (name) =>
+          client.requestProperty(name),
+        );
+        if ((await currentLocalMedia(client)) !== mediaPath)
+          throw new Error('The current media changed. Start generation again.');
+        signal.throwIfAborted();
+        const outputPath = await (deps.generate ?? generateJapaneseSubtitles)({
+          config,
+          modelDirectory: deps.getModelDirectory(),
+          mediaPath,
+          audioStreamIndex,
+          references,
+          onProgress: report,
+          signal,
+        });
+        // Saving succeeds even if playback changes or disconnects during the job.
+        try {
+          const playingMedia = await currentLocalMedia(client);
+          if (!signal.aborted && deps.getMpvClient() === client && playingMedia === mediaPath) {
+            const loaded = await client.request([
+              'sub-add',
+              outputPath,
+              'select',
+              'Generated Japanese',
+              'ja',
+            ]);
+            if (loaded.error && loaded.error !== 'success') throw new Error(loaded.error);
+            const delay = await client.request(['set_property', 'sub-delay', 0]);
+            if (delay.error && delay.error !== 'success') throw new Error(delay.error);
+            return {
+              ok: true,
+              outputPath,
+              message: `Japanese subtitles saved and loaded: ${outputPath}`,
+            };
+          }
+          return {
+            ok: true,
+            outputPath,
+            message: `Subtitles saved: ${outputPath}. ${signal.aborted ? 'Cancelled after saving; the file was not loaded.' : 'Playback changed, so the file was not loaded.'}`,
+          };
+        } catch (error) {
+          return {
+            ok: true,
+            outputPath,
+            message: `Subtitles saved: ${outputPath}. Could not finish loading into mpv: ${error instanceof Error ? error.message : String(error)}`,
+          };
+        }
+      });
+    },
+  };
+}
diff --git a/src/main/runtime/subtitle-prefetch-runtime.test.ts b/src/main/runtime/subtitle-prefetch-runtime.test.ts
index a5780680..c0c6fca7 100644
--- a/src/main/runtime/subtitle-prefetch-runtime.test.ts
+++ b/src/main/runtime/subtitle-prefetch-runtime.test.ts
@@ -101,6 +101,32 @@ test('subtitle prefetch runtime preserves parsed cues when YouTube active track
   assert.deepEqual(calls, []);
 });
 
+test('subtitle prefetch runtime preserves parsed cues when a network mount source is unresolved', async () => {
+  const calls: string[] = [];
+  const refresh = createRefreshSubtitlePrefetchFromActiveTrackHandler({
+    getMpvClient: () => ({
+      connected: true,
+      requestProperty: async (name) => (name === 'path' ? '/Volumes/jellyfin/movie.mkv' : null),
+    }),
+    getLastObservedTimePos: () => 12,
+    subtitlePrefetchInitController: {
+      cancelPendingInit: () => {
+        calls.push('cancel');
+      },
+      initSubtitlePrefetch: async () => {
+        calls.push('init');
+      },
+    },
+    resolveActiveSubtitleSidebarSource: async () => null,
+    shouldKeepExistingCuesOnMissingSource: async (videoPath) =>
+      videoPath.startsWith('/Volumes/jellyfin/'),
+  });
+
+  await refresh();
+
+  assert.deepEqual(calls, []);
+});
+
 test('subtitle prefetch runtime does not extract internal subtitle tracks from remote media urls', async () => {
   let extracted = false;
   const resolveSource = createResolveActiveSubtitleSidebarSourceHandler({
@@ -131,6 +157,36 @@ test('subtitle prefetch runtime does not extract internal subtitle tracks from r
   assert.equal(extracted, false);
 });
 
+test('subtitle prefetch runtime extracts internal subtitle tracks from network-mounted media', async () => {
+  let extracted = false;
+  const resolveSource = createResolveActiveSubtitleSidebarSourceHandler({
+    getFfmpegPath: () => 'ffmpeg-custom',
+    extractInternalSubtitleTrack: async () => {
+      extracted = true;
+      return {
+        path: '/tmp/subminer-sidebar-123/track_7.ass',
+        cleanup: async () => {},
+      };
+    },
+  });
+
+  const resolved = await resolveSource({
+    currentExternalFilenameRaw: null,
+    currentTrackRaw: {
+      type: 'sub',
+      id: 3,
+      'ff-index': 7,
+      codec: 'ass',
+    },
+    trackListRaw: [],
+    sidRaw: 3,
+    videoPath: '/Volumes/jellyfin/movie.mkv',
+  });
+
+  assert.equal(resolved?.path, '/tmp/subminer-sidebar-123/track_7.ass');
+  assert.equal(extracted, true);
+});
+
 test('subtitle prefetch refresh logs a warning when source resolution throws', async () => {
   const warnings: string[] = [];
   const refresh = createRefreshSubtitlePrefetchFromActiveTrackHandler({
diff --git a/src/main/runtime/subtitle-prefetch-runtime.ts b/src/main/runtime/subtitle-prefetch-runtime.ts
index 098697a9..d759beff 100644
--- a/src/main/runtime/subtitle-prefetch-runtime.ts
+++ b/src/main/runtime/subtitle-prefetch-runtime.ts
@@ -28,7 +28,7 @@ function parseTrackId(value: unknown): number | null {
   return null;
 }
 
-function isRemoteMediaPath(value: string): boolean {
+function isRemoteMediaUrl(value: string): boolean {
   try {
     const url = new URL(value);
     return url.protocol === 'http:' || url.protocol === 'https:';
@@ -126,7 +126,10 @@ export function createResolveActiveSubtitleSidebarSourceHandler(deps: {
       return { path: externalFilename, sourceKey: externalFilename };
     }
 
-    if (isRemoteMediaPath(input.videoPath)) {
+    // Network-mounted files extract like local ones: demuxing reads the whole
+    // container (~10s/GB on gigabit), which a LAN handles alongside playback.
+    // Only true remote URLs have no on-disk container to demux.
+    if (isRemoteMediaUrl(input.videoPath)) {
       deps.logDebug?.('[subtitle-prefetch] skipping internal subtitle extraction for remote media');
       return null;
     }
@@ -156,7 +159,7 @@ export function createRefreshSubtitlePrefetchFromActiveTrackHandler(deps: {
     requestProperty: (name: string) => Promise<unknown>;
   } | null;
   getLastObservedTimePos: () => number;
-  shouldKeepExistingCuesOnMissingSource?: (videoPath: string) => boolean;
+  shouldKeepExistingCuesOnMissingSource?: (videoPath: string) => boolean | Promise<boolean>;
   subtitlePrefetchInitController: SubtitlePrefetchInitController;
   resolveActiveSubtitleSidebarSource: (
     input: Parameters<ReturnType<typeof createResolveActiveSubtitleSidebarSourceHandler>>[0],
@@ -195,7 +198,7 @@ export function createRefreshSubtitlePrefetchFromActiveTrackHandler(deps: {
         videoPath,
       });
       if (!resolvedSource) {
-        if (deps.shouldKeepExistingCuesOnMissingSource?.(videoPath) === true) {
+        if ((await deps.shouldKeepExistingCuesOnMissingSource?.(videoPath)) === true) {
           deps.logDebug?.(
             '[subtitle-prefetch] no active subtitle source resolved; keeping existing cues',
           );
diff --git a/src/main/runtime/subtitle-selection.test.ts b/src/main/runtime/subtitle-selection.test.ts
new file mode 100644
index 00000000..fc42db37
--- /dev/null
+++ b/src/main/runtime/subtitle-selection.test.ts
@@ -0,0 +1,101 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { createSubtitleSelectionRuntime } from './subtitle-selection';
+
+function setup() {
+  let enabled = true;
+  const properties = new Map<string, unknown>([
+    ['path', '/video.mkv'],
+    [
+      'track-list',
+      [
+        { id: 1, type: 'audio' },
+        { id: 2, type: 'sub', title: 'Japanese', lang: 'ja', codec: 'ass' },
+        { id: 3, type: 'sub', title: 'English', lang: 'en', external: true },
+        { id: '4', type: 'sub' },
+      ],
+    ],
+    ['sid', 2],
+    ['secondary-sid', 3],
+  ]);
+  const commands: unknown[][] = [];
+  const client = {
+    connected: true,
+    requestProperty: async (name: string) => properties.get(name),
+    request: async (command: unknown[]) => {
+      commands.push(command);
+      return { error: 'success' };
+    },
+  };
+  const runtime = createSubtitleSelectionRuntime({
+    isEnabled: () => enabled,
+    getMpvClient: () => client,
+  });
+  return {
+    runtime,
+    properties,
+    commands,
+    client,
+    disable: () => {
+      enabled = false;
+    },
+  };
+}
+
+test('subtitle selector lists only valid subtitle tracks and current selections', async () => {
+  const { runtime, properties } = setup();
+  assert.deepEqual(await runtime.getState(), {
+    mediaPath: '/video.mkv',
+    primary: 2,
+    secondary: 3,
+    tracks: [
+      { id: 2, label: '#2 · Japanese · ja · ass' },
+      { id: 3, label: '#3 · English · en · external' },
+    ],
+  });
+  properties.set('sid', 'no');
+  properties.set('secondary-sid', false);
+  const state = await runtime.getState();
+  assert.equal(state.primary, null);
+  assert.equal(state.secondary, null);
+});
+
+test('subtitle selector swaps tracks and supports disabling both tracks', async () => {
+  const { runtime, commands } = setup();
+  await runtime.apply({ mediaPath: '/video.mkv', primary: 3, secondary: 2 });
+  assert.deepEqual(commands, [
+    ['set_property', 'secondary-sid', 'no'],
+    ['set_property', 'sid', 3],
+    ['set_property', 'secondary-sid', 2],
+  ]);
+  commands.length = 0;
+  await runtime.apply({ mediaPath: '/video.mkv', primary: null, secondary: null });
+  assert.ok(commands.every((command) => command[2] === 'no'));
+});
+
+test('subtitle selector rejects stale media, unavailable tracks, duplicate tracks and malformed requests without mutation', async () => {
+  const { runtime, commands } = setup();
+  for (const request of [
+    { mediaPath: '/other.mkv', primary: 2, secondary: 3 },
+    { mediaPath: '/video.mkv', primary: 99, secondary: null },
+    { mediaPath: '/video.mkv', primary: 2, secondary: 2 },
+    { mediaPath: '/video.mkv', primary: '2', secondary: null },
+    { mediaPath: '/video.mkv', primary: -1, secondary: null },
+    null,
+  ])
+    await assert.rejects(runtime.apply(request));
+  assert.deepEqual(commands, []);
+});
+
+test('subtitle selector gates access on config and connection and propagates mpv failures', async () => {
+  const { runtime, client, disable } = setup();
+  client.request = async () => ({ error: 'property unavailable' });
+  await assert.rejects(
+    runtime.apply({ mediaPath: '/video.mkv', primary: 3, secondary: 2 }),
+    /property unavailable/,
+  );
+  client.connected = false;
+  await assert.rejects(runtime.getState(), /Connect to mpv/);
+  disable();
+  await assert.rejects(runtime.getState(), /Enable subtitle selection/);
+});
diff --git a/src/main/runtime/subtitle-selection.ts b/src/main/runtime/subtitle-selection.ts
new file mode 100644
index 00000000..19aca325
--- /dev/null
+++ b/src/main/runtime/subtitle-selection.ts
@@ -0,0 +1,117 @@
+import type { IpcMain, WebContents } from 'electron';
+import { IPC_CHANNELS } from '../../shared/ipc/contracts';
+import {
+  parseSubtitleSelectionRequest,
+  type SubtitleSelectionState,
+} from '../../shared/subtitle-selection';
+import { openOverlayHostedModal, retryOverlayModalOpen } from './overlay-hosted-modal-open';
+
+interface SelectionMpvClient {
+  connected: boolean;
+  requestProperty: (name: string) => Promise<unknown>;
+  request: (command: unknown[]) => Promise<{ error?: string }>;
+}
+
+export function openSubtitleSelectionModal(
+  deps: Parameters<typeof openOverlayHostedModal>[0] & Parameters<typeof retryOverlayModalOpen>[0],
+): Promise<boolean> {
+  return retryOverlayModalOpen(deps, {
+    modal: 'subtitle-selection',
+    timeoutMs: 1500,
+    retryWarning: 'Subtitle selection modal did not acknowledge opening; retrying.',
+    sendOpen: () =>
+      openOverlayHostedModal(deps, {
+        channel: IPC_CHANNELS.event.subtitleSelectionOpen,
+        modal: 'subtitle-selection',
+        preferModalWindow: true,
+      }),
+  });
+}
+
+export function createSubtitleSelectionRuntime(deps: {
+  isEnabled: () => boolean;
+  getMpvClient: () => SelectionMpvClient | null;
+}) {
+  function getClient(): SelectionMpvClient {
+    if (!deps.isEnabled()) throw new Error('Enable subtitle selection in Settings first.');
+    const client = deps.getMpvClient();
+    if (!client?.connected) throw new Error('Connect to mpv first.');
+    return client;
+  }
+
+  async function readState(client: SelectionMpvClient): Promise<SubtitleSelectionState> {
+    const mediaPath = await client.requestProperty('path');
+    if (typeof mediaPath !== 'string' || !mediaPath) throw new Error('Open a video first.');
+    const [rawTracks, primary, secondary] = await Promise.all([
+      client.requestProperty('track-list'),
+      client.requestProperty('sid'),
+      client.requestProperty('secondary-sid'),
+    ]);
+    const tracks: SubtitleSelectionState['tracks'] = [];
+    const candidates: unknown[] = Array.isArray(rawTracks) ? rawTracks : [];
+    for (const track of candidates) {
+      if (
+        typeof track !== 'object' ||
+        track === null ||
+        !('type' in track) ||
+        track.type !== 'sub' ||
+        !('id' in track) ||
+        typeof track.id !== 'number' ||
+        !Number.isSafeInteger(track.id) ||
+        track.id <= 0
+      )
+        continue;
+      const details = [
+        'title' in track ? track.title : undefined,
+        'lang' in track ? track.lang : undefined,
+        'codec' in track ? track.codec : undefined,
+      ].filter((value): value is string => typeof value === 'string' && value.length > 0);
+      if ('external' in track && track.external === true) details.push('external');
+      tracks.push({ id: track.id, label: `#${track.id} · ${details.join(' · ') || 'Subtitle'}` });
+    }
+    if ((await client.requestProperty('path')) !== mediaPath)
+      throw new Error('The video changed. Reopen subtitle selection.');
+    const selected = (value: unknown): number | null =>
+      tracks.find((track) => track.id === value)?.id ?? null;
+    return { mediaPath, tracks, primary: selected(primary), secondary: selected(secondary) };
+  }
+
+  async function apply(value: unknown): Promise<void> {
+    const selection = parseSubtitleSelectionRequest(value);
+    const client = getClient();
+    const current = await readState(client);
+    if (current.mediaPath !== selection.mediaPath)
+      throw new Error('The video changed. Reopen subtitle selection.');
+    for (const id of [selection.primary, selection.secondary]) {
+      if (id !== null && !current.tracks.some((track) => track.id === id))
+        throw new Error('A selected track is no longer available. Reopen subtitle selection.');
+    }
+    const set = async (property: string, id: number | null): Promise<void> => {
+      const response = await client.request(['set_property', property, id ?? 'no']);
+      if (response.error && response.error !== 'success') throw new Error(response.error);
+    };
+    // Clear secondary first so swapping the two tracks works in mpv.
+    await set('secondary-sid', null);
+    await set('sid', selection.primary);
+    await set('secondary-sid', selection.secondary);
+  }
+
+  return { getState: async () => readState(getClient()), apply };
+}
+
+export function registerSubtitleSelectionIpc(deps: {
+  ipc: Pick<IpcMain, 'handle'>;
+  isAllowedSender: (sender: WebContents) => boolean;
+  runtime: ReturnType<typeof createSubtitleSelectionRuntime>;
+}): void {
+  deps.ipc.handle(IPC_CHANNELS.request.getSubtitleSelection, (event) => {
+    if (!deps.isAllowedSender(event.sender))
+      throw new Error('Subtitle selection requires the overlay.');
+    return deps.runtime.getState();
+  });
+  deps.ipc.handle(IPC_CHANNELS.request.applySubtitleSelection, (event, value: unknown) => {
+    if (!deps.isAllowedSender(event.sender))
+      throw new Error('Subtitle selection requires the overlay.');
+    return deps.runtime.apply(value);
+  });
+}
diff --git a/src/main/runtime/update/appimage-updater.test.ts b/src/main/runtime/update/appimage-updater.test.ts
index 67a323ff..7c190036 100644
--- a/src/main/runtime/update/appimage-updater.test.ts
+++ b/src/main/runtime/update/appimage-updater.test.ts
@@ -58,7 +58,7 @@ test('updateAppImageFromRelease verifies hash and atomically replaces writable A
   ]);
 });
 
-test('updateAppImageFromRelease reports protected command without replacing non-writable AppImage', async () => {
+test('updateAppImageFromRelease reports protected command for a direct non-writable AppImage', async () => {
   const result = await updateAppImageFromRelease({
     release: {
       tag_name: 'v0.15.0',
@@ -67,7 +67,7 @@ test('updateAppImageFromRelease reports protected command without replacing non-
       assets: [{ name: 'SubMiner.AppImage', browser_download_url: 'https://example.test/app' }],
     },
     sha256Sums: new Map([['SubMiner.AppImage', appImageHash]]),
-    appImagePath: '/opt/SubMiner/SubMiner.AppImage',
+    appImagePath: '/usr/local/lib/SubMiner.AppImage',
     downloadAsset: async () => appImageBytes,
     fs: {
       stat: async () => ({
@@ -87,10 +87,50 @@ test('updateAppImageFromRelease reports protected command without replacing non-
   });
 
   assert.equal(result.status, 'protected');
-  assert.equal(result.path, '/opt/SubMiner/SubMiner.AppImage');
+  assert.equal(result.path, '/usr/local/lib/SubMiner.AppImage');
   assert.match(result.command ?? '', /curl -fSL 'https:\/\/example\.test\/app' -o "\$tmp"/);
   assert.match(result.command ?? '', /sha256sum -c -/);
-  assert.match(result.command ?? '', /sudo mv "\$tmp" '\/opt\/SubMiner\/SubMiner\.AppImage'/);
+  assert.match(result.command ?? '', /sudo mv "\$tmp" '\/usr\/local\/lib\/SubMiner\.AppImage'/);
+});
+
+test('updateAppImageFromRelease leaves canonical and symlinked AUR AppImages to pacman', async () => {
+  for (const appImagePath of ['/opt/SubMiner/SubMiner.AppImage', '/usr/bin/SubMiner.AppImage']) {
+    let accessed = false;
+    const result = await updateAppImageFromRelease({
+      release: {
+        tag_name: 'v0.15.0',
+        prerelease: false,
+        draft: false,
+        assets: [{ name: 'SubMiner.AppImage', browser_download_url: 'https://example.test/app' }],
+      },
+      sha256Sums: new Map([['SubMiner.AppImage', appImageHash]]),
+      appImagePath,
+      downloadAsset: async () => {
+        throw new Error('must not download package-managed AppImage');
+      },
+      fs: {
+        realpath: async () => '/opt/SubMiner/SubMiner.AppImage',
+        stat: async () => {
+          throw new Error('must not stat package-managed AppImage');
+        },
+        access: async () => {
+          accessed = true;
+        },
+        writeFile: async () => {},
+        chmod: async () => {},
+        rename: async () => {},
+        unlink: async () => {},
+      },
+    });
+
+    assert.deepEqual(result, {
+      status: 'skipped',
+      path: appImagePath,
+      message: 'This AppImage is managed by the subminer-bin system package.',
+    });
+    assert.equal(accessed, false);
+    assert.equal(result.command, undefined);
+  }
 });
 
 test('buildProtectedAppImageUpdateCommand quotes inputs and verifies checksum before sudo move', () => {
diff --git a/src/main/runtime/update/appimage-updater.ts b/src/main/runtime/update/appimage-updater.ts
index 337efc4e..de52acc9 100644
--- a/src/main/runtime/update/appimage-updater.ts
+++ b/src/main/runtime/update/appimage-updater.ts
@@ -25,6 +25,7 @@ export interface AppImageUpdateResult {
 }
 
 export interface AppImageUpdateFileSystem {
+  realpath?: (targetPath: string) => Promise<string>;
   stat: (targetPath: string) => Promise<StatLike>;
   access: (targetPath: string) => Promise<void>;
   writeFile: (targetPath: string, data: Buffer) => Promise<void>;
@@ -39,6 +40,7 @@ function sha256(data: Buffer): string {
 
 function defaultFs(): AppImageUpdateFileSystem {
   return {
+    realpath: (targetPath) => fs.promises.realpath(targetPath),
     stat: (targetPath) => fs.promises.stat(targetPath),
     access: async (targetPath) => {
       await fs.promises.access(targetPath, fs.constants.W_OK);
@@ -105,6 +107,19 @@ export async function updateAppImageFromRelease(options: {
   }
 
   const fsDeps = options.fs ?? defaultFs();
+  let resolvedAppImagePath = options.appImagePath;
+  try {
+    resolvedAppImagePath = (await fsDeps.realpath?.(options.appImagePath)) ?? options.appImagePath;
+  } catch {
+    // stat below reports a missing or inaccessible path with the existing result shape.
+  }
+  if (resolvedAppImagePath === '/opt/SubMiner/SubMiner.AppImage') {
+    return {
+      status: 'skipped',
+      path: options.appImagePath,
+      message: 'This AppImage is managed by the subminer-bin system package.',
+    };
+  }
   let stat: StatLike;
   try {
     stat = await fsDeps.stat(options.appImagePath);
diff --git a/src/main/runtime/update/launcher-updater.test.ts b/src/main/runtime/update/launcher-updater.test.ts
index 87ae05ff..6a8d99ea 100644
--- a/src/main/runtime/update/launcher-updater.test.ts
+++ b/src/main/runtime/update/launcher-updater.test.ts
@@ -5,6 +5,7 @@ import {
   buildProtectedLauncherUpdateCommand,
   looksLikeSubminerLauncher,
   updateLauncherAtPath,
+  updateLauncherFromRelease,
 } from './launcher-updater';
 
 const launcherBytes = Buffer.from('#!/usr/bin/env bash\n# SubMiner launcher\nexec SubMiner "$@"\n');
@@ -124,3 +125,137 @@ test('updateLauncherAtPath aborts on hash mismatch and suspicious launcher conte
   assert.equal(suspicious.status, 'skipped');
   assert.equal(mismatch.status, 'hash-mismatch');
 });
+
+test('app-managed wrappers are never overwritten by the standalone release script', async () => {
+  const { managedLauncherContent } = await import('../managed-launcher');
+  let downloaded = false;
+  const result = await updateLauncherAtPath({
+    launcherPath: '/home/tester/.local/bin/subminer',
+    assetUrl: 'https://example.test/subminer',
+    expectedSha256: launcherHash,
+    download: async () => {
+      downloaded = true;
+      return launcherBytes;
+    },
+    fs: {
+      stat: async () => ({ isFile: () => true }),
+      readFile: async () =>
+        managedLauncherContent({
+          platform: 'linux',
+          appPath: '/apps/SubMiner.AppImage',
+        }),
+      access: async () => {
+        throw new Error('must not modify wrapper');
+      },
+      writeFile: async () => {
+        throw new Error('must not modify wrapper');
+      },
+      chmod: async () => {},
+      rename: async () => {},
+      unlink: async () => {},
+    },
+  });
+  assert.equal(result.status, 'skipped');
+  assert.equal(downloaded, false);
+});
+
+test('GUI updates defer recognized standalone launcher migration to app startup', async () => {
+  const accessed: string[] = [];
+  let downloaded = false;
+  const result = await updateLauncherAtPath({
+    launcherPath: '/home/tester/.local/bin/subminer',
+    assetUrl: 'https://example.test/subminer',
+    expectedSha256: launcherHash,
+    deferRecognizedLauncherUpdate: true,
+    download: async () => {
+      downloaded = true;
+      return launcherBytes;
+    },
+    fs: {
+      stat: async () => ({ isFile: () => true }),
+      readFile: async () => Buffer.from('#!/bin/sh\n# SubMiner launcher\n'),
+      access: async (targetPath) => {
+        accessed.push(targetPath);
+      },
+      writeFile: async () => {},
+      chmod: async () => {},
+      rename: async () => {},
+      unlink: async () => {},
+    },
+  });
+
+  assert.deepEqual(result, {
+    status: 'skipped',
+    path: '/home/tester/.local/bin/subminer',
+    message: 'Launcher migration is deferred until the updated SubMiner app starts.',
+    deferred: true,
+  });
+  assert.deepEqual(accessed, ['/home/tester/.local/bin/subminer', '/home/tester/.local/bin']);
+  assert.equal(downloaded, false);
+});
+
+test('release launcher updater propagates GUI migration deferral', async () => {
+  let downloaded = false;
+  const result = await updateLauncherFromRelease({
+    release: {
+      tag_name: 'v0.15.0',
+      prerelease: false,
+      draft: false,
+      assets: [{ name: 'subminer', browser_download_url: 'https://example.test/subminer' }],
+    },
+    sha256Sums: new Map([['subminer', launcherHash]]),
+    launcherPath: '/home/tester/.local/bin/subminer',
+    deferRecognizedLauncherUpdate: true,
+    exists: () => true,
+    downloadAsset: async () => {
+      downloaded = true;
+      return launcherBytes;
+    },
+    fs: {
+      stat: async () => ({ isFile: () => true }),
+      readFile: async () => Buffer.from('#!/bin/sh\n# SubMiner launcher\n'),
+      access: async () => {},
+      writeFile: async () => {},
+      chmod: async () => {},
+      rename: async () => {},
+      unlink: async () => {},
+    },
+  });
+
+  assert.equal(result.status, 'skipped');
+  assert.match(result.message ?? '', /deferred until the updated SubMiner app starts/);
+  assert.equal(downloaded, false);
+});
+
+test('GUI migration reports a protected launcher when its file or parent is not writable', async () => {
+  const launcherPath = '/usr/local/bin/subminer';
+  for (const protectedPath of [launcherPath, '/usr/local/bin']) {
+    const result = await updateLauncherAtPath({
+      launcherPath,
+      assetUrl: 'https://example.test/subminer',
+      expectedSha256: launcherHash,
+      deferRecognizedLauncherUpdate: true,
+      download: async () => {
+        throw new Error('Protected launchers must not download a replacement.');
+      },
+      fs: {
+        stat: async () => ({ isFile: () => true }),
+        readFile: async () => Buffer.from('#!/usr/bin/env bun\n// SubMiner launcher\n'),
+        access: async (targetPath) => {
+          if (targetPath === protectedPath) throw new Error('EACCES');
+        },
+        writeFile: async () => {
+          throw new Error('Protected launchers must not be written.');
+        },
+        chmod: async () => {},
+        rename: async () => {},
+        unlink: async () => {},
+      },
+    });
+    assert.equal(result.status, 'protected', protectedPath);
+    assert.equal(
+      result.command,
+      buildProtectedLauncherUpdateCommand('https://example.test/subminer', launcherPath),
+    );
+  }
+});
diff --git a/src/main/runtime/update/launcher-updater.ts b/src/main/runtime/update/launcher-updater.ts
index 7f69711b..c1ac1488 100644
--- a/src/main/runtime/update/launcher-updater.ts
+++ b/src/main/runtime/update/launcher-updater.ts
@@ -4,6 +4,7 @@ import os from 'node:os';
 import path from 'node:path';
 import type { GitHubRelease } from './release-assets';
 import { findReleaseAsset } from './release-assets';
+import { isManagedLauncher } from '../managed-launcher';
 
 type StatLike = {
   isFile: () => boolean;
@@ -23,6 +24,8 @@ export interface LauncherUpdateResult {
   path?: string;
   command?: string;
   message?: string;
+  // Set when a writable legacy launcher was left for app startup to migrate.
+  deferred?: boolean;
 }
 
 export interface LauncherUpdateFileSystem {
@@ -82,6 +85,7 @@ export async function updateLauncherAtPath(options: {
   assetUrl: string;
   expectedSha256: string;
   download: () => Promise<Buffer>;
+  deferRecognizedLauncherUpdate?: boolean;
   fs?: LauncherUpdateFileSystem;
 }): Promise<LauncherUpdateResult> {
   const fsDeps = options.fs ?? defaultFs();
@@ -96,6 +100,13 @@ export async function updateLauncherAtPath(options: {
   }
 
   const existing = await fsDeps.readFile(options.launcherPath);
+  if (isManagedLauncher(existing.toString())) {
+    return {
+      status: 'skipped',
+      path: options.launcherPath,
+      message: 'This launcher is updated with the SubMiner app.',
+    };
+  }
   if (!looksLikeSubminerLauncher(existing)) {
     return {
       status: 'skipped',
@@ -103,9 +114,9 @@ export async function updateLauncherAtPath(options: {
       message: 'Existing executable does not look like a SubMiner launcher.',
     };
   }
-
   try {
     await fsDeps.access(options.launcherPath);
+    await fsDeps.access(path.dirname(options.launcherPath));
   } catch {
     return {
       status: 'protected',
@@ -114,6 +125,15 @@ export async function updateLauncherAtPath(options: {
     };
   }
 
+  if (options.deferRecognizedLauncherUpdate) {
+    return {
+      status: 'skipped',
+      path: options.launcherPath,
+      message: 'Launcher migration is deferred until the updated SubMiner app starts.',
+      deferred: true,
+    };
+  }
+
   const data = await options.download();
   const actualSha256 = sha256(data);
   if (actualSha256 !== options.expectedSha256.toLowerCase()) {
@@ -160,7 +180,9 @@ export async function updateLauncherFromRelease(options: {
   platform?: NodeJS.Platform;
   homeDir?: string;
   downloadAsset: (url: string) => Promise<Buffer>;
+  deferRecognizedLauncherUpdate?: boolean;
   exists?: (targetPath: string) => boolean;
+  fs?: LauncherUpdateFileSystem;
 }): Promise<LauncherUpdateResult> {
   if (!options.release) return { status: 'missing-asset', message: 'No release found.' };
   const asset = findReleaseAsset(options.release, 'subminer');
@@ -184,5 +206,7 @@ export async function updateLauncherFromRelease(options: {
     assetUrl: asset.browser_download_url,
     expectedSha256,
     download: () => options.downloadAsset(asset.browser_download_url),
+    deferRecognizedLauncherUpdate: options.deferRecognizedLauncherUpdate,
+    fs: options.fs,
   });
 }
diff --git a/src/main/runtime/update/support-assets.test.ts b/src/main/runtime/update/support-assets.test.ts
index 16b23ea9..702cafa7 100644
--- a/src/main/runtime/update/support-assets.test.ts
+++ b/src/main/runtime/update/support-assets.test.ts
@@ -13,7 +13,7 @@ import {
 } from './support-assets';
 
 type SupportAssetsResultWithComponent = SupportAssetsUpdateResult & {
-  component?: 'theme' | 'plugin';
+  component?: 'theme' | 'thumbnailer' | 'plugin';
 };
 
 function sha256(data: Buffer): string {
@@ -22,18 +22,30 @@ function sha256(data: Buffer): string {
 
 function makeSupportAssetsArchive(options?: {
   themeContent?: string;
+  thumbnailerContent?: string;
+  includeThumbnailer?: boolean;
   pluginVersion?: string | null;
   pluginMainContent?: string;
   extraPluginFiles?: Array<{ relativePath: string; content: string }>;
 }): { archive: Buffer; tempDir: string } {
   const themeContent = options?.themeContent ?? 'new theme\n';
+  const thumbnailerContent = options?.thumbnailerContent ?? '[Thumbnailer Entry]\n';
   const pluginVersion = options && 'pluginVersion' in options ? options.pluginVersion : '0.12.0';
   const pluginMainContent = options?.pluginMainContent ?? 'new plugin\n';
   const extraPluginFiles = options?.extraPluginFiles ?? [];
   const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'subminer-support-assets-test-'));
   fs.mkdirSync(path.join(tempDir, 'assets/themes'), { recursive: true });
+  if (options?.includeThumbnailer !== false) {
+    fs.mkdirSync(path.join(tempDir, 'assets/thumbnailers'), { recursive: true });
+  }
   fs.mkdirSync(path.join(tempDir, 'plugin/subminer'), { recursive: true });
   fs.writeFileSync(path.join(tempDir, 'assets/themes/subminer.rasi'), themeContent);
+  if (options?.includeThumbnailer !== false) {
+    fs.writeFileSync(
+      path.join(tempDir, 'assets/thumbnailers/subminer-ffmpegthumbnailer.thumbnailer'),
+      thumbnailerContent,
+    );
+  }
   fs.writeFileSync(path.join(tempDir, 'plugin/subminer/main.lua'), pluginMainContent);
   if (pluginVersion !== null) {
     fs.writeFileSync(
@@ -93,7 +105,7 @@ test('detectSupportAssetDataDirs only returns Linux support-asset locations', ()
   );
 });
 
-test('buildProtectedSupportAssetsCommand installs both theme and plugin assets', () => {
+test('buildProtectedSupportAssetsCommand installs theme, thumbnailer, and plugin assets', () => {
   const command = buildProtectedSupportAssetsCommand(
     "https://example.test/subminer assets.tar.gz?sig='abc'",
     'ABCDEF1234',
@@ -110,11 +122,28 @@ test('buildProtectedSupportAssetsCommand installs both theme and plugin assets',
     command,
     /printf '%s  %s\\n' 'abcdef1234' "\$tmp\/subminer-assets\.tar\.gz" \| sha256sum -c -/,
   );
+  const requiredAssetChecks = [
+    'test -f "$tmp/assets/themes/subminer.rasi"',
+    'test -f "$tmp/assets/thumbnailers/subminer-ffmpegthumbnailer.thumbnailer"',
+    'test -f "$tmp/plugin/subminer/main.lua"',
+    'test -f "$tmp/plugin/subminer/version.lua"',
+  ];
+  const firstSudoIndex = command.indexOf('sudo ');
+  assert.notEqual(firstSudoIndex, -1);
+  for (const check of requiredAssetChecks) {
+    const checkIndex = command.indexOf(check);
+    assert.notEqual(checkIndex, -1);
+    assert.ok(checkIndex < firstSudoIndex);
+  }
   assert.match(command, /sudo mkdir -p '\/usr\/local\/share\/SubMiner'\\''s data'\/themes/);
   assert.match(
     command,
     /sudo cp "\$tmp\/assets\/themes\/subminer\.rasi" '\/usr\/local\/share\/SubMiner'\\''s data'\/themes\/subminer\.rasi/,
   );
+  assert.match(
+    command,
+    /sudo cp "\$tmp\/assets\/thumbnailers\/subminer-ffmpegthumbnailer\.thumbnailer" .*thumbnailers\/subminer-ffmpegthumbnailer\.thumbnailer/,
+  );
   assert.match(command, /sudo mkdir -p '\/usr\/local\/share\/SubMiner'\\''s data'\/plugin/);
   assert.match(command, /sudo rm -rf .*plugin\/subminer\.next/);
   assert.match(command, /sudo cp -R "\$tmp\/plugin\/subminer" .*plugin\/subminer\.next/);
@@ -209,6 +238,12 @@ test('updateSupportAssetsFromRelease installs missing plugin into a root with a
         path: dataDir,
         message: 'Updated theme.',
       },
+      {
+        status: 'updated',
+        component: 'thumbnailer',
+        path: dataDir,
+        message: 'Installed rofi thumbnailer.',
+      },
       {
         status: 'updated',
         component: 'plugin',
@@ -220,6 +255,13 @@ test('updateSupportAssetsFromRelease installs missing plugin into a root with a
       fs.readFileSync(path.join(dataDir, 'themes/subminer.rasi'), 'utf8'),
       'new theme\n',
     );
+    assert.equal(
+      fs.readFileSync(
+        path.join(dataDir, 'thumbnailers/subminer-ffmpegthumbnailer.thumbnailer'),
+        'utf8',
+      ),
+      '[Thumbnailer Entry]\n',
+    );
     assert.equal(
       fs.readFileSync(path.join(dataDir, 'plugin/subminer/main.lua'), 'utf8'),
       'new plugin\n',
@@ -345,8 +387,13 @@ test('updateSupportAssetsFromRelease skips identical theme and up-to-date plugin
   const xdgDataHome = fs.mkdtempSync(path.join(os.tmpdir(), 'subminer-xdg-data-'));
   const dataDir = path.posix.join(xdgDataHome, 'SubMiner');
   fs.mkdirSync(path.join(dataDir, 'themes'), { recursive: true });
+  fs.mkdirSync(path.join(dataDir, 'thumbnailers'), { recursive: true });
   fs.mkdirSync(path.join(dataDir, 'plugin/subminer'), { recursive: true });
   fs.writeFileSync(path.join(dataDir, 'themes/subminer.rasi'), 'same theme\n');
+  fs.writeFileSync(
+    path.join(dataDir, 'thumbnailers/subminer-ffmpegthumbnailer.thumbnailer'),
+    '[Thumbnailer Entry]\n',
+  );
   fs.writeFileSync(path.join(dataDir, 'plugin/subminer/main.lua'), 'same plugin\n');
   fs.writeFileSync(
     path.join(dataDir, 'plugin/subminer/version.lua'),
@@ -371,6 +418,12 @@ test('updateSupportAssetsFromRelease skips identical theme and up-to-date plugin
         path: dataDir,
         message: 'Theme already up to date.',
       },
+      {
+        status: 'skipped',
+        component: 'thumbnailer',
+        path: dataDir,
+        message: 'Rofi thumbnailer already up to date.',
+      },
       {
         status: 'skipped',
         component: 'plugin',
@@ -396,8 +449,13 @@ test('updateSupportAssetsFromRelease updates changed theme and outdated plugin w
   const xdgDataHome = fs.mkdtempSync(path.join(os.tmpdir(), 'subminer-xdg-data-'));
   const dataDir = path.posix.join(xdgDataHome, 'SubMiner');
   fs.mkdirSync(path.join(dataDir, 'themes'), { recursive: true });
+  fs.mkdirSync(path.join(dataDir, 'thumbnailers'), { recursive: true });
   fs.mkdirSync(path.join(dataDir, 'plugin/subminer'), { recursive: true });
   fs.writeFileSync(path.join(dataDir, 'themes/subminer.rasi'), 'old theme\n');
+  fs.writeFileSync(
+    path.join(dataDir, 'thumbnailers/subminer-ffmpegthumbnailer.thumbnailer'),
+    '[Old Thumbnailer]\n',
+  );
   fs.writeFileSync(path.join(dataDir, 'plugin/subminer/main.lua'), 'old plugin\n');
   fs.writeFileSync(
     path.join(dataDir, 'plugin/subminer/version.lua'),
@@ -406,6 +464,7 @@ test('updateSupportAssetsFromRelease updates changed theme and outdated plugin w
   fs.writeFileSync(path.join(dataDir, 'plugin/subminer/stale.lua'), 'stale\n');
   const { archive, tempDir } = makeSupportAssetsArchive({
     themeContent: 'new theme\n',
+    thumbnailerContent: '[Thumbnailer Entry]\n',
     pluginVersion: '0.12.0',
     pluginMainContent: 'new plugin main\n',
     extraPluginFiles: [{ relativePath: 'fresh.lua', content: 'fresh\n' }],
@@ -424,6 +483,12 @@ test('updateSupportAssetsFromRelease updates changed theme and outdated plugin w
         path: dataDir,
         message: 'Updated theme.',
       },
+      {
+        status: 'updated',
+        component: 'thumbnailer',
+        path: dataDir,
+        message: 'Updated rofi thumbnailer.',
+      },
       {
         status: 'updated',
         component: 'plugin',
@@ -435,6 +500,13 @@ test('updateSupportAssetsFromRelease updates changed theme and outdated plugin w
       fs.readFileSync(path.join(dataDir, 'themes/subminer.rasi'), 'utf8'),
       'new theme\n',
     );
+    assert.equal(
+      fs.readFileSync(
+        path.join(dataDir, 'thumbnailers/subminer-ffmpegthumbnailer.thumbnailer'),
+        'utf8',
+      ),
+      '[Thumbnailer Entry]\n',
+    );
     assert.equal(
       fs.readFileSync(path.join(dataDir, 'plugin/subminer/main.lua'), 'utf8'),
       'new plugin main\n',
@@ -479,6 +551,12 @@ test('updateSupportAssetsFromRelease returns protected commands for managed root
           path: dataDir,
           command: true,
         },
+        {
+          status: 'protected',
+          component: 'thumbnailer',
+          path: dataDir,
+          command: true,
+        },
         {
           status: 'protected',
           component: 'plugin',
@@ -488,6 +566,10 @@ test('updateSupportAssetsFromRelease returns protected commands for managed root
       ],
     );
     assert.match(results[0]?.command ?? '', /themes\/subminer\.rasi/);
+    assert.match(
+      results[0]?.command ?? '',
+      /thumbnailers\/subminer-ffmpegthumbnailer\.thumbnailer/,
+    );
     assert.match(results[0]?.command ?? '', /plugin\/subminer/);
   } finally {
     fs.chmodSync(dataDir, originalMode);
@@ -522,3 +604,25 @@ test('updateSupportAssetsFromRelease returns missing-asset when release plugin v
     fs.rmSync(tempDir, { recursive: true, force: true });
   }
 });
+
+test('updateSupportAssetsFromRelease rejects archives without the rofi thumbnailer', async () => {
+  const xdgDataHome = fs.mkdtempSync(path.join(os.tmpdir(), 'subminer-xdg-data-'));
+  const dataDir = path.posix.join(xdgDataHome, 'SubMiner');
+  fs.mkdirSync(path.join(dataDir, 'themes'), { recursive: true });
+  fs.writeFileSync(path.join(dataDir, 'themes/subminer.rasi'), 'managed theme\n');
+  const { archive, tempDir } = makeSupportAssetsArchive({ includeThumbnailer: false });
+
+  try {
+    const results = await runLinuxSupportAssetUpdate({ archive, xdgDataHome });
+
+    assert.deepEqual(results, [
+      {
+        status: 'missing-asset',
+        message: 'Support asset archive is missing the rofi thumbnailer.',
+      },
+    ]);
+  } finally {
+    fs.rmSync(xdgDataHome, { recursive: true, force: true });
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  }
+});
diff --git a/src/main/runtime/update/support-assets.ts b/src/main/runtime/update/support-assets.ts
index dfbdd800..9b4954a0 100644
--- a/src/main/runtime/update/support-assets.ts
+++ b/src/main/runtime/update/support-assets.ts
@@ -9,13 +9,17 @@ import { compareSemverLike, findReleaseAsset } from './release-assets';
 
 const execFileAsync = promisify(execFile);
 const THEME_RELATIVE_PATH = path.join('themes', 'subminer.rasi');
+const THUMBNAILER_RELATIVE_PATH = path.join(
+  'thumbnailers',
+  'subminer-ffmpegthumbnailer.thumbnailer',
+);
 const PLUGIN_ENTRYPOINT_RELATIVE_PATH = path.join('plugin', 'subminer', 'main.lua');
 const PLUGIN_VERSION_RELATIVE_PATH = path.join('plugin', 'subminer', 'version.lua');
 const PLUGIN_DIR_RELATIVE_PATH = path.join('plugin', 'subminer');
 
 export interface SupportAssetsUpdateResult {
   status: 'updated' | 'skipped' | 'protected' | 'hash-mismatch' | 'missing-asset';
-  component?: 'theme' | 'plugin';
+  component?: 'theme' | 'thumbnailer' | 'plugin';
   path?: string;
   command?: string;
   message?: string;
@@ -69,11 +73,12 @@ async function readInstalledPluginVersion(pluginDir: string): Promise<string | n
 async function detectManagedSupportAssetDataDirs(dataDirs: string[]): Promise<string[]> {
   const managedDataDirs: string[] = [];
   for (const dataDir of dataDirs) {
-    const [hasTheme, hasPlugin] = await Promise.all([
+    const [hasTheme, hasThumbnailer, hasPlugin] = await Promise.all([
       pathExists(path.join(dataDir, THEME_RELATIVE_PATH)),
+      pathExists(path.join(dataDir, THUMBNAILER_RELATIVE_PATH)),
       pathExists(path.join(dataDir, PLUGIN_ENTRYPOINT_RELATIVE_PATH)),
     ]);
-    if (hasTheme || hasPlugin) {
+    if (hasTheme || hasThumbnailer || hasPlugin) {
       managedDataDirs.push(dataDir);
     }
   }
@@ -163,8 +168,14 @@ export function buildProtectedSupportAssetsCommand(
     `curl -fSL ${shellQuote(assetUrl)} -o "$tmp/subminer-assets.tar.gz"`,
     `printf '%s  %s\\n' ${quotedExpectedSha256} "$tmp/subminer-assets.tar.gz" | sha256sum -c -`,
     'tar -xzf "$tmp/subminer-assets.tar.gz" -C "$tmp"',
+    'test -f "$tmp/assets/themes/subminer.rasi"',
+    'test -f "$tmp/assets/thumbnailers/subminer-ffmpegthumbnailer.thumbnailer"',
+    'test -f "$tmp/plugin/subminer/main.lua"',
+    'test -f "$tmp/plugin/subminer/version.lua"',
     `sudo mkdir -p ${quotedDir}/themes`,
     `sudo cp "$tmp/assets/themes/subminer.rasi" ${quotedDir}/themes/subminer.rasi`,
+    `sudo mkdir -p ${quotedDir}/thumbnailers`,
+    `sudo cp "$tmp/assets/thumbnailers/subminer-ffmpegthumbnailer.thumbnailer" ${quotedDir}/thumbnailers/subminer-ffmpegthumbnailer.thumbnailer`,
     `sudo mkdir -p ${quotedDir}/plugin`,
     `sudo rm -rf ${quotedStagedPluginDir} ${quotedBackupPluginDir}`,
     `sudo cp -R "$tmp/plugin/subminer" ${quotedStagedPluginDir}`,
@@ -216,6 +227,12 @@ export async function updateSupportAssetsFromRelease(options: {
           dataDir,
           'Support asset path is not a directory.',
         ),
+        makeSupportAssetResult(
+          'skipped',
+          'thumbnailer',
+          dataDir,
+          'Support asset path is not a directory.',
+        ),
         makeSupportAssetResult(
           'skipped',
           'plugin',
@@ -244,6 +261,13 @@ export async function updateSupportAssetsFromRelease(options: {
         'Theme install requires a manual command.',
         command,
       ),
+      makeSupportAssetResult(
+        'protected',
+        'thumbnailer',
+        dataDir,
+        'Rofi thumbnailer install requires a manual command.',
+        command,
+      ),
       makeSupportAssetResult(
         'protected',
         'plugin',
@@ -284,6 +308,17 @@ export async function updateSupportAssetsFromRelease(options: {
     }
     const themeBytes = await fs.promises.readFile(themeSourcePath);
 
+    const thumbnailerSourcePath = path.join(tempDir, 'assets', THUMBNAILER_RELATIVE_PATH);
+    if (!(await pathExists(thumbnailerSourcePath))) {
+      return [
+        {
+          status: 'missing-asset',
+          message: 'Support asset archive is missing the rofi thumbnailer.',
+        },
+      ];
+    }
+    const thumbnailerBytes = await fs.promises.readFile(thumbnailerSourcePath);
+
     const sourcePluginDir = path.join(tempDir, PLUGIN_DIR_RELATIVE_PATH);
     const sourcePluginEntrypoint = path.join(tempDir, PLUGIN_ENTRYPOINT_RELATIVE_PATH);
     if (!(await pathExists(sourcePluginEntrypoint))) {
@@ -328,6 +363,33 @@ export async function updateSupportAssetsFromRelease(options: {
         );
       }
 
+      const targetThumbnailerPath = path.join(dataDir, THUMBNAILER_RELATIVE_PATH);
+      const existingThumbnailerBytes = await readFileIfExists(targetThumbnailerPath);
+      if (
+        existingThumbnailerBytes &&
+        Buffer.compare(existingThumbnailerBytes, thumbnailerBytes) === 0
+      ) {
+        results.push(
+          makeSupportAssetResult(
+            'skipped',
+            'thumbnailer',
+            dataDir,
+            'Rofi thumbnailer already up to date.',
+          ),
+        );
+      } else {
+        await fs.promises.mkdir(path.dirname(targetThumbnailerPath), { recursive: true });
+        await fs.promises.writeFile(targetThumbnailerPath, thumbnailerBytes);
+        results.push(
+          makeSupportAssetResult(
+            'updated',
+            'thumbnailer',
+            dataDir,
+            existingThumbnailerBytes ? 'Updated rofi thumbnailer.' : 'Installed rofi thumbnailer.',
+          ),
+        );
+      }
+
       const targetPluginDir = path.join(dataDir, PLUGIN_DIR_RELATIVE_PATH);
       const targetPluginEntrypoint = path.join(dataDir, PLUGIN_ENTRYPOINT_RELATIVE_PATH);
       const installedPluginVersion = await readInstalledPluginVersion(targetPluginDir);
diff --git a/src/main/runtime/update/update-service-runtime.ts b/src/main/runtime/update/update-service-runtime.ts
index 7ddcd3ac..a9607612 100644
--- a/src/main/runtime/update/update-service-runtime.ts
+++ b/src/main/runtime/update/update-service-runtime.ts
@@ -19,7 +19,11 @@ import { shouldFetchReleaseMetadataForPlatform } from './release-metadata-policy
 import { updateLauncherFromRelease } from './launcher-updater';
 import { notifyUpdateAvailable } from './update-notifications';
 import { createUpdateDialogPresenter } from './update-dialogs';
-import { createFileUpdateStateStore, createUpdateService } from './update-service';
+import {
+  createFileUpdateStateStore,
+  createUpdateService,
+  takePendingLauncherMigrationPath,
+} from './update-service';
 import { updateSupportAssetsFromRelease } from './support-assets';
 import { runSupportAssetUpdatesForLauncherResult } from './update-support-assets-runtime';
 
@@ -38,6 +42,9 @@ export interface UpdateServiceRuntimeDeps {
 
 export function createUpdateServiceRuntime(deps: UpdateServiceRuntimeDeps): {
   getUpdateService: () => ReturnType<typeof createUpdateService>;
+  takePendingLauncherMigrationPath: (
+    refresh: Parameters<typeof takePendingLauncherMigrationPath>[1],
+  ) => Promise<string | undefined>;
 } {
   const updateStateStore = createFileUpdateStateStore(
     path.join(deps.userDataPath, 'update-state.json'),
@@ -79,6 +86,7 @@ export function createUpdateServiceRuntime(deps: UpdateServiceRuntimeDeps): {
       sha256Sums: sums,
       launcherPath,
       downloadAsset: (url) => fetchReleaseAssetBuffer(fetchForUpdater, url),
+      deferRecognizedLauncherUpdate: true,
     });
     return runSupportAssetUpdatesForLauncherResult({
       launcherResult,
@@ -152,8 +160,7 @@ export function createUpdateServiceRuntime(deps: UpdateServiceRuntimeDeps): {
       getConfig: () => deps.getUpdatesConfig(),
       getCurrentVersion: () => app.getVersion(),
       now: () => Date.now(),
-      readState: () => updateStateStore.readState(),
-      writeState: (state) => updateStateStore.writeState(state),
+      stateStore: updateStateStore,
       checkAppUpdate: (channel) => appUpdater.checkForUpdates(channel),
       shouldFetchReleaseMetadata: ({ request, appUpdate }) =>
         shouldFetchReleaseMetadataForPlatform(process.platform, appUpdate, request),
@@ -187,5 +194,9 @@ export function createUpdateServiceRuntime(deps: UpdateServiceRuntimeDeps): {
     return updateService;
   }
 
-  return { getUpdateService };
+  return {
+    getUpdateService,
+    takePendingLauncherMigrationPath: (refresh) =>
+      takePendingLauncherMigrationPath(updateStateStore, refresh),
+  };
 }
diff --git a/src/main/runtime/update/update-service.test.ts b/src/main/runtime/update/update-service.test.ts
index 370a9308..251c80ac 100644
--- a/src/main/runtime/update/update-service.test.ts
+++ b/src/main/runtime/update/update-service.test.ts
@@ -1,7 +1,13 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
 import { shouldFetchReleaseMetadataForPlatform } from './release-metadata-policy';
-import { createUpdateService, type UpdateServiceDeps, type UpdateState } from './update-service';
+import {
+  createUpdateService,
+  createUpdateStateStore,
+  takePendingLauncherMigrationPath,
+  type UpdateServiceDeps,
+  type UpdateState,
+} from './update-service';
 
 function createDeps(overrides: Partial<UpdateServiceDeps> = {}) {
   let state: UpdateState = {};
@@ -15,11 +21,13 @@ function createDeps(overrides: Partial<UpdateServiceDeps> = {}) {
     }),
     getCurrentVersion: () => '0.14.0',
     now: () => 1_000_000,
-    readState: async () => state,
-    writeState: async (nextState) => {
-      state = nextState;
-      calls.push(`state:${JSON.stringify(nextState)}`);
-    },
+    stateStore: createUpdateStateStore({
+      readState: async () => state,
+      writeState: async (nextState) => {
+        state = nextState;
+        calls.push(`state:${JSON.stringify(nextState)}`);
+      },
+    }),
     checkAppUpdate: async () => ({ available: false, version: '0.14.0' }),
     fetchLatestStableRelease: async () => ({
       tag_name: 'v0.14.0',
@@ -286,7 +294,7 @@ test('concurrent update checks share one in-flight check', async () => {
   const first = service.checkForUpdates({ source: 'manual' });
   const second = service.checkForUpdates({ source: 'manual' });
 
-  await Promise.resolve();
+  await new Promise<void>((resolve) => setImmediate(resolve));
   resolveCheck({ available: false, version: '0.14.0' });
   await Promise.all([first, second]);
 
@@ -307,7 +315,7 @@ test('manual install request does not reuse in-flight manual check', async () =>
   const manualCheck = service.checkForUpdates({ source: 'manual' });
   const manualInstall = service.checkForUpdates({ source: 'manual', installWhenAvailable: true });
 
-  await Promise.resolve();
+  await new Promise<void>((resolve) => setImmediate(resolve));
   assert.equal(checkCount, 2);
   for (const resolve of resolveChecks) {
     resolve({ available: false, version: '0.14.0' });
@@ -315,26 +323,32 @@ test('manual install request does not reuse in-flight manual check', async () =>
   await Promise.all([manualCheck, manualInstall]);
 });
 
-test('manual update check does not reuse in-flight automatic check', async () => {
+test('manual update check does not reuse in-flight automatic check and preserves all state', async () => {
   let checkCount = 0;
   const resolveChecks: Array<(value: { available: boolean; version: string }) => void> = [];
-  const { deps } = createDeps({
+  const { deps, getState } = createDeps({
     checkAppUpdate: () =>
       new Promise((resolve) => {
         checkCount += 1;
         resolveChecks.push(resolve);
       }),
+    updateLauncher: async () => ({ status: 'skipped', path: '/x/subminer', deferred: true }),
   });
   const service = createUpdateService(deps);
   const automatic = service.checkForUpdates({ source: 'automatic', force: true });
-  const manual = service.checkForUpdates({ source: 'manual' });
+  const manual = service.checkForUpdates({ source: 'manual', installWhenAvailable: true });
 
-  await Promise.resolve();
+  await new Promise<void>((resolve) => setImmediate(resolve));
   assert.equal(checkCount, 2);
   for (const resolve of resolveChecks) {
-    resolve({ available: false, version: '0.14.0' });
+    resolve({ available: true, version: '0.15.0' });
   }
   await Promise.all([automatic, manual]);
+  assert.deepEqual(getState(), {
+    pendingLauncherMigrationPath: '/x/subminer',
+    lastAutomaticCheckAt: 1_000_000,
+    lastNotifiedVersion: '0.15.0',
+  });
 });
 
 test('manual update check passes selected GitHub release to launcher update', async () => {
@@ -488,3 +502,85 @@ test('manual update check keeps current prerelease builds on configured stable c
   assert.equal(result.status, 'up-to-date');
   assert.deepEqual(calls, ['app:stable', 'fetch:stable', 'no-update:0.15.0-beta.3']);
 });
+
+test('deferred launcher migration is persisted for the next app start', async () => {
+  const launcherPath = '/home/tester/.local/bin/subminer';
+  const { deps, calls } = createDeps({
+    checkAppUpdate: async () => ({ available: true, version: '0.15.0' }),
+    fetchLatestStableRelease: async () => ({
+      tag_name: 'v0.15.0',
+      prerelease: false,
+      draft: false,
+      assets: [],
+    }),
+    showUpdateAvailableDialog: async () => 'update',
+    updateLauncher: async () => ({ status: 'skipped', path: launcherPath, deferred: true }),
+  });
+  const service = createUpdateService(deps);
+
+  const result = await service.checkForUpdates({ source: 'manual', launcherPath });
+
+  assert.equal(result.status, 'updated');
+  assert.ok(
+    calls.includes(`state:${JSON.stringify({ pendingLauncherMigrationPath: launcherPath })}`),
+  );
+});
+
+test('takePendingLauncherMigrationPath hands the path over exactly once', async () => {
+  let state: UpdateState = {
+    lastNotifiedVersion: '0.15.0',
+    pendingLauncherMigrationPath: '/x/subminer',
+  };
+  const store = createUpdateStateStore({
+    readState: async () => state,
+    writeState: async (nextState: UpdateState) => {
+      state = nextState;
+    },
+  });
+
+  const refresh = async () => true;
+  assert.deepEqual(
+    await Promise.all([
+      takePendingLauncherMigrationPath(store, refresh),
+      takePendingLauncherMigrationPath(store, refresh),
+    ]),
+    ['/x/subminer', undefined],
+  );
+  assert.deepEqual(state, { lastNotifiedVersion: '0.15.0' });
+  assert.equal(await takePendingLauncherMigrationPath(store, refresh), undefined);
+});
+
+test('failed migration remains pending and acknowledgement preserves concurrent check state', async () => {
+  const { deps, getState, setState } = createDeps({
+    checkAppUpdate: async () => ({ available: true, version: '0.15.0' }),
+  });
+  setState({ pendingLauncherMigrationPath: '/x/subminer' });
+  await assert.rejects(
+    takePendingLauncherMigrationPath(deps.stateStore, async () => {
+      throw new Error('refresh failed');
+    }),
+    /refresh failed/,
+  );
+  assert.equal(getState().pendingLauncherMigrationPath, '/x/subminer');
+
+  const service = createUpdateService(deps);
+  const check = service.checkForUpdates({ source: 'automatic' });
+  await takePendingLauncherMigrationPath(deps.stateStore, async () => false);
+  await check;
+  assert.deepEqual(getState(), {
+    pendingLauncherMigrationPath: '/x/subminer',
+    lastAutomaticCheckAt: 1_000_000,
+    lastNotifiedVersion: '0.15.0',
+  });
+
+  const nextCheck = service.checkForUpdates({ source: 'automatic', force: true });
+  assert.equal(
+    await takePendingLauncherMigrationPath(deps.stateStore, async () => true),
+    '/x/subminer',
+  );
+  await nextCheck;
+  assert.deepEqual(getState(), {
+    lastAutomaticCheckAt: 1_000_000,
+    lastNotifiedVersion: '0.15.0',
+  });
+});
diff --git a/src/main/runtime/update/update-service.ts b/src/main/runtime/update/update-service.ts
index c9d0c24f..789c3351 100644
--- a/src/main/runtime/update/update-service.ts
+++ b/src/main/runtime/update/update-service.ts
@@ -7,6 +7,8 @@ import { compareSemverLike, parseReleaseVersion } from './release-assets';
 export interface UpdateState {
   lastAutomaticCheckAt?: number;
   lastNotifiedVersion?: string;
+  // Legacy launcher the last update left for the next app start to migrate.
+  pendingLauncherMigrationPath?: string;
 }
 
 export type UpdateCheckSource = 'manual' | 'automatic' | 'launcher';
@@ -41,8 +43,7 @@ export interface UpdateServiceDeps {
   getConfig: () => Required<UpdatesConfig>;
   getCurrentVersion: () => string;
   now: () => number;
-  readState: () => Promise<UpdateState>;
-  writeState: (state: UpdateState) => Promise<void>;
+  stateStore: ReturnType<typeof createUpdateStateStore>;
   checkAppUpdate: (channel: UpdateChannel) => Promise<AppUpdateMetadata>;
   shouldFetchReleaseMetadata?: (input: {
     request: UpdateCheckRequest;
@@ -54,7 +55,7 @@ export interface UpdateServiceDeps {
     launcherPath?: string,
     channel?: UpdateChannel,
     release?: GitHubRelease | null,
-  ) => Promise<{ status: string; command?: string }>;
+  ) => Promise<{ status: string; command?: string; path?: string; deferred?: boolean }>;
   showNoUpdateDialog: (version: string) => Promise<void>;
   showUpdateAvailableDialog: (version: string) => Promise<'update' | 'close'>;
   showUpdateFailedDialog: (message: string) => Promise<void>;
@@ -121,7 +122,7 @@ export function createUpdateService(deps: UpdateServiceDeps) {
     const now = deps.now();
     const config = deps.getConfig();
     const channel = config.channel;
-    const state = await deps.readState();
+    const state = await deps.stateStore.transaction((store) => store.readState());
     const isAutomatic = request.source === 'automatic';
 
     if (isAutomatic && !request.force && shouldSkipAutomaticCheck(config, state, now)) {
@@ -150,15 +151,18 @@ export function createUpdateService(deps: UpdateServiceDeps) {
       const latest = getBestLatestVersion(currentVersion, appUpdate, release);
 
       if (isAutomatic) {
-        const nextState: UpdateState = {
-          ...state,
-          lastAutomaticCheckAt: now,
-        };
-        if (latest.available && state.lastNotifiedVersion !== latest.version) {
-          await deps.notifyUpdateAvailable(latest.version);
-          nextState.lastNotifiedVersion = latest.version;
-        }
-        await deps.writeState(nextState);
+        await deps.stateStore.transaction(async (store) => {
+          const currentState = await store.readState();
+          const nextState: UpdateState = {
+            ...currentState,
+            lastAutomaticCheckAt: now,
+          };
+          if (latest.available && currentState.lastNotifiedVersion !== latest.version) {
+            await deps.notifyUpdateAvailable(latest.version);
+            nextState.lastNotifiedVersion = latest.version;
+          }
+          await store.writeState(nextState);
+        });
       }
 
       if (!latest.available) {
@@ -189,6 +193,12 @@ export function createUpdateService(deps: UpdateServiceDeps) {
       if (launcherResult.status === 'protected' && launcherResult.command) {
         deps.log(`Launcher update requires manual command: ${launcherResult.command}`);
       }
+      if (launcherResult.deferred && launcherResult.path) {
+        const pendingLauncherMigrationPath = launcherResult.path;
+        await deps.stateStore.transaction(async (store) => {
+          await store.writeState({ ...(await store.readState()), pendingLauncherMigrationPath });
+        });
+      }
 
       if (!appUpdateApplied) {
         await deps.showManualUpdateRequiredDialog(latest.version);
@@ -237,11 +247,41 @@ export function createUpdateService(deps: UpdateServiceDeps) {
   };
 }
 
-export function createFileUpdateStateStore(statePath: string): {
+// Keep the path until refresh acknowledges migration or an ineligible candidate.
+export async function takePendingLauncherMigrationPath(
+  stateStore: ReturnType<typeof createUpdateStateStore>,
+  refresh: (launcherPath: string | undefined) => Promise<boolean>,
+): Promise<string | undefined> {
+  return stateStore.transaction(async (store) => {
+    const { pendingLauncherMigrationPath, ...rest } = await store.readState();
+    const acknowledged = await refresh(pendingLauncherMigrationPath);
+    if (!pendingLauncherMigrationPath || !acknowledged) {
+      return undefined;
+    }
+    await store.writeState(rest);
+    return pendingLauncherMigrationPath;
+  });
+}
+
+export function createUpdateStateStore(store: {
   readState: () => Promise<UpdateState>;
   writeState: (state: UpdateState) => Promise<void>;
-} {
+}) {
+  let pending = Promise.resolve();
   return {
+    transaction<T>(operation: (stateStore: typeof store) => Promise<T>): Promise<T> {
+      const result = pending.then(() => operation(store));
+      pending = result.then(
+        () => {},
+        () => {},
+      );
+      return result;
+    },
+  };
+}
+
+export function createFileUpdateStateStore(statePath: string) {
+  return createUpdateStateStore({
     async readState(): Promise<UpdateState> {
       try {
         return JSON.parse(await fs.promises.readFile(statePath, 'utf8')) as UpdateState;
@@ -253,5 +293,5 @@ export function createFileUpdateStateStore(statePath: string): {
       await fs.promises.mkdir(path.dirname(statePath), { recursive: true });
       await fs.promises.writeFile(statePath, `${JSON.stringify(state, null, 2)}\n`, 'utf8');
     },
-  };
+  });
 }
diff --git a/src/main/runtime/windows-launcher-bootstrap.test.ts b/src/main/runtime/windows-launcher-bootstrap.test.ts
new file mode 100644
index 00000000..5f17c30c
--- /dev/null
+++ b/src/main/runtime/windows-launcher-bootstrap.test.ts
@@ -0,0 +1,128 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import test from 'node:test';
+import { getRunCommand } from './command-line-launcher-deps';
+import { windowsLauncherBootstrapContent } from './windows-launcher-bootstrap';
+
+function workspace(t: test.TestContext): string {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'subminer windows bootstrap '));
+  t.after(() => fs.rmSync(root, { recursive: true, force: true }));
+  return root;
+}
+
+test('generic bootstrap searches supported Windows install locations in order', () => {
+  const content = windowsLauncherBootstrapContent();
+  const override = content.indexOf('if defined SUBMINER_BINARY_PATH goto subminer_app_found');
+  const localInstall = content.indexOf('%LOCALAPPDATA%\\Programs\\SubMiner\\SubMiner.exe');
+  const machineInstall = content.indexOf('%ProgramFiles%\\SubMiner\\SubMiner.exe');
+
+  assert.ok(override >= 0);
+  assert.ok(localInstall > override);
+  assert.ok(machineInstall > localInstall);
+  assert.match(content, /SubMiner app not found/);
+});
+
+test('configured app path is an escaped fallback after the environment override', () => {
+  const configured = 'D:\\Apps & Tools\\SubMiner 100% !\\SubMiner.exe';
+  const content = windowsLauncherBootstrapContent(configured);
+
+  assert.ok(
+    content.indexOf('if defined SUBMINER_BINARY_PATH goto subminer_app_found') <
+      content.indexOf('if not exist "D:\\Apps & Tools\\SubMiner 100%% !\\SubMiner.exe"'),
+  );
+  assert.match(
+    content,
+    /set "SUBMINER_BINARY_PATH=D:\\Apps & Tools\\SubMiner 100%% !\\SubMiner\.exe"/,
+  );
+  assert.throws(
+    () => windowsLauncherBootstrapContent('C:\\Bad "Install"\\SubMiner.exe'),
+    /quotes or newlines/,
+  );
+});
+
+test('cached runtime is the fast path and launcher arguments remain opaque to the batch file', () => {
+  const content = windowsLauncherBootstrapContent();
+  const cacheCheck = content.indexOf('if exist "%SUBMINER_BUN_PATH%" goto subminer_run');
+  const electronPrepare = content.indexOf('set "ELECTRON_RUN_AS_NODE=1"');
+  const run = content.indexOf(
+    '"%SUBMINER_BUN_PATH%" "%SUBMINER_RESOURCES_PATH%\\launcher\\subminer.js" %*',
+  );
+
+  assert.match(content, /^@echo off\r\nrem SubMiner managed launcher \(bundled runtime\)/);
+  assert.match(content, /setlocal DisableDelayedExpansion/);
+  assert.ok(cacheCheck >= 0);
+  assert.ok(electronPrepare > cacheCheck);
+  assert.ok(run > electronPrepare);
+  assert.doesNotMatch(content, /powershell/i);
+  assert.doesNotMatch(content, /^\s*(?:call\s+)?bun(?:\.exe)?(?:\s|$)/im);
+});
+
+test('preparation failures keep their exit code and never continue to the launcher', () => {
+  const content = windowsLauncherBootstrapContent();
+
+  assert.match(content, /set "SUBMINER_PREPARE_EXIT=%errorlevel%"/);
+  assert.match(content, /if not "%SUBMINER_PREPARE_EXIT%"=="0" exit \/b %SUBMINER_PREPARE_EXIT%/);
+  assert.match(content, /if not exist "%SUBMINER_BUN_PATH%" goto subminer_prepare_missing/);
+  assert.match(content, /set "ELECTRON_RUN_AS_NODE="/);
+});
+
+test('Windows bootstrap prepares once and forwards metacharacter arguments', async (t) => {
+  if (process.platform !== 'win32') return;
+
+  const root = workspace(t);
+  const appDirectory = path.join(root, 'Installed & App 100% !');
+  const appPath = path.join(appDirectory, 'SubMiner.exe');
+  const resourcesPath = path.join(appDirectory, 'resources');
+  const launcherDirectory = path.join(resourcesPath, 'launcher');
+  const localAppData = path.join(root, 'Local App Data');
+  const bootstrapPath = path.join(root, 'subminer.cmd');
+  const version = '1.2.3-test';
+  const cachedBunPath = path.join(localAppData, 'SubMiner', 'launcher-runtime', version, 'bun.exe');
+  fs.mkdirSync(launcherDirectory, { recursive: true });
+  fs.copyFileSync(process.execPath, appPath);
+  fs.writeFileSync(path.join(launcherDirectory, 'version'), version);
+  fs.writeFileSync(
+    path.join(launcherDirectory, 'subminer.js'),
+    'console.log(JSON.stringify({args:process.argv.slice(2),app:process.env.SUBMINER_BINARY_PATH,resources:process.env.SUBMINER_RESOURCES_PATH,managed:process.env.SUBMINER_MANAGED_LAUNCHER}));',
+  );
+  fs.writeFileSync(
+    path.join(launcherDirectory, 'prepare.cjs'),
+    `const fs=require('node:fs');const path=require('node:path');exports.prepareLauncherRuntime=()=>{const target=${JSON.stringify(cachedBunPath)};fs.mkdirSync(path.dirname(target),{recursive:true});fs.copyFileSync(process.execPath,target);};`,
+  );
+  fs.writeFileSync(bootstrapPath, windowsLauncherBootstrapContent(appPath));
+
+  const args = [
+    'spaces here',
+    '100%',
+    'p%TEMP%q',
+    'bang!',
+    'a&b',
+    'x|y',
+    '<left>',
+    'caret^',
+    'say "hi"',
+    '日本語',
+  ];
+  const env = { ...process.env, PATH: '', Path: '', LOCALAPPDATA: localAppData };
+  const first = await getRunCommand({})(bootstrapPath, args, { env });
+  assert.equal(first.exitCode, 0, first.stderr);
+  assert.ok(fs.existsSync(cachedBunPath));
+  const firstPayload: unknown = JSON.parse(first.stdout);
+  assert.deepEqual(firstPayload, {
+    args,
+    app: appPath,
+    resources: resourcesPath,
+    managed: '1',
+  });
+
+  fs.writeFileSync(
+    path.join(launcherDirectory, 'prepare.cjs'),
+    "throw new Error('cached launch should not prepare');",
+  );
+  const second = await getRunCommand({})(bootstrapPath, args, { env });
+  assert.equal(second.exitCode, 0, second.stderr);
+  const secondPayload: unknown = JSON.parse(second.stdout);
+  assert.deepEqual(secondPayload, firstPayload);
+});
diff --git a/src/main/runtime/windows-launcher-bootstrap.ts b/src/main/runtime/windows-launcher-bootstrap.ts
new file mode 100644
index 00000000..11b74499
--- /dev/null
+++ b/src/main/runtime/windows-launcher-bootstrap.ts
@@ -0,0 +1,75 @@
+const MANAGED_LAUNCHER_MARKER = 'SubMiner managed launcher (bundled runtime)';
+
+function windowsBatchLiteral(value: string): string {
+  if (/["\r\n]/.test(value)) {
+    throw new Error('Launcher paths cannot contain quotes or newlines.');
+  }
+  return value.replaceAll('%', '%%');
+}
+
+function configuredAppCandidate(appPath: string | undefined): string[] {
+  if (!appPath) return [];
+  const literal = windowsBatchLiteral(appPath);
+  return [
+    `if not exist "${literal}" goto subminer_check_local_app`,
+    `set "SUBMINER_BINARY_PATH=${literal}"`,
+    'goto subminer_app_found',
+  ];
+}
+
+// This command file stays valid across app updates. It locates the current app
+// and only starts Electron in Node mode when that version's private Bun is absent.
+export function windowsLauncherBootstrapContent(appPath?: string): string {
+  return [
+    '@echo off',
+    `rem ${MANAGED_LAUNCHER_MARKER}`,
+    'setlocal DisableDelayedExpansion',
+    'set "SUBMINER_MANAGED_LAUNCHER=1"',
+    'set "SUBMINER_LAUNCHER_PATH=%~f0"',
+    'if defined SUBMINER_BINARY_PATH goto subminer_app_found',
+    ...configuredAppCandidate(appPath),
+    ':subminer_check_local_app',
+    'if not defined LOCALAPPDATA goto subminer_check_program_files',
+    'if not exist "%LOCALAPPDATA%\\Programs\\SubMiner\\SubMiner.exe" goto subminer_check_program_files',
+    'set "SUBMINER_BINARY_PATH=%LOCALAPPDATA%\\Programs\\SubMiner\\SubMiner.exe"',
+    'goto subminer_app_found',
+    ':subminer_check_program_files',
+    'if not defined ProgramFiles goto subminer_app_missing',
+    'if not exist "%ProgramFiles%\\SubMiner\\SubMiner.exe" goto subminer_app_missing',
+    'set "SUBMINER_BINARY_PATH=%ProgramFiles%\\SubMiner\\SubMiner.exe"',
+    ':subminer_app_found',
+    'if not exist "%SUBMINER_BINARY_PATH%" goto subminer_app_missing',
+    'if not defined LOCALAPPDATA goto subminer_local_app_data_missing',
+    'for %%I in ("%SUBMINER_BINARY_PATH%") do set "SUBMINER_RESOURCES_PATH=%%~dpIresources"',
+    'if not exist "%SUBMINER_RESOURCES_PATH%\\launcher\\subminer.js" goto subminer_resources_missing',
+    'set "SUBMINER_APP_VERSION="',
+    'if not exist "%SUBMINER_RESOURCES_PATH%\\launcher\\version" goto subminer_resources_missing',
+    'set /p "SUBMINER_APP_VERSION="<"%SUBMINER_RESOURCES_PATH%\\launcher\\version"',
+    'if not defined SUBMINER_APP_VERSION goto subminer_resources_missing',
+    'set "SUBMINER_BUN_PATH=%LOCALAPPDATA%\\SubMiner\\launcher-runtime\\%SUBMINER_APP_VERSION%\\bun.exe"',
+    'if exist "%SUBMINER_BUN_PATH%" goto subminer_run',
+    'if not exist "%SUBMINER_RESOURCES_PATH%\\launcher\\prepare.cjs" goto subminer_resources_missing',
+    'set "ELECTRON_RUN_AS_NODE=1"',
+    "\"%SUBMINER_BINARY_PATH%\" -e \"const p=require('node:path');try{require(p.join(process.env.SUBMINER_RESOURCES_PATH,'launcher','prepare.cjs')).prepareLauncherRuntime({appPath:process.env.SUBMINER_BINARY_PATH,resourcesPath:process.env.SUBMINER_RESOURCES_PATH});}catch(error){console.error('Cannot prepare SubMiner launcher. Update or reinstall the SubMiner app.',error instanceof Error?error.message:String(error));process.exit(1);}\"",
+    'set "SUBMINER_PREPARE_EXIT=%errorlevel%"',
+    'set "ELECTRON_RUN_AS_NODE="',
+    'if not "%SUBMINER_PREPARE_EXIT%"=="0" exit /b %SUBMINER_PREPARE_EXIT%',
+    'if not exist "%SUBMINER_BUN_PATH%" goto subminer_prepare_missing',
+    ':subminer_run',
+    '"%SUBMINER_BUN_PATH%" "%SUBMINER_RESOURCES_PATH%\\launcher\\subminer.js" %*',
+    'exit /b %errorlevel%',
+    ':subminer_app_missing',
+    '>&2 echo SubMiner app not found. Install the app or set SUBMINER_BINARY_PATH to its executable.',
+    'exit /b 1',
+    ':subminer_local_app_data_missing',
+    '>&2 echo LOCALAPPDATA is unavailable. SubMiner cannot locate its private launcher runtime.',
+    'exit /b 1',
+    ':subminer_resources_missing',
+    '>&2 echo This launcher requires a SubMiner app with the included Bun runtime. Update SubMiner.',
+    'exit /b 1',
+    ':subminer_prepare_missing',
+    '>&2 echo SubMiner did not create its private launcher runtime. Update or reinstall SubMiner.',
+    'exit /b 1',
+    '',
+  ].join('\r\n');
+}
diff --git a/src/main/runtime/windows-mpv-launch.test.ts b/src/main/runtime/windows-mpv-launch.test.ts
index e1c806fd..3aba85ba 100644
--- a/src/main/runtime/windows-mpv-launch.test.ts
+++ b/src/main/runtime/windows-mpv-launch.test.ts
@@ -29,12 +29,12 @@ test('resolveWindowsMpvPath prefers SUBMINER_MPV_PATH', () => {
   assert.equal(resolved, 'C:\\mpv\\mpv.exe');
 });
 
-test('resolveWindowsMpvPath prefers configured executable path before PATH', () => {
+test('resolveWindowsMpvPath prefers configured executable path before environment and PATH', () => {
   const resolved = resolveWindowsMpvPath(
     createDeps({
-      getEnv: () => undefined,
+      getEnv: () => 'C:\\other\\mpv.exe',
       runWhere: () => ({ status: 0, stdout: 'C:\\tools\\mpv.exe\r\n' }),
-      fileExists: (candidate) => candidate === 'C:\\mpv\\mpv.exe',
+      fileExists: (candidate) => ['C:\\mpv\\mpv.exe', 'C:\\other\\mpv.exe'].includes(candidate),
     }),
     '  C:\\mpv\\mpv.exe  ',
   );
@@ -53,6 +53,16 @@ test('resolveWindowsMpvPath falls back to where.exe output', () => {
   assert.equal(resolved, 'C:\\tools\\mpv.exe');
 });
 
+test('resolveWindowsMpvPath ignores an invalid environment override but keeps config authoritative', () => {
+  const deps = createDeps({
+    getEnv: () => 'C:\\missing\\mpv.exe',
+    runWhere: () => ({ status: 0, stdout: 'C:\\tools\\mpv.exe\r\n' }),
+    fileExists: (candidate) => candidate === 'C:\\tools\\mpv.exe',
+  });
+  assert.equal(resolveWindowsMpvPath(deps), 'C:\\tools\\mpv.exe');
+  assert.equal(resolveWindowsMpvPath(deps, 'C:\\missing\\mpv.exe'), '');
+});
+
 test('buildWindowsMpvLaunchArgs uses explicit SubMiner defaults and targets', () => {
   assert.deepEqual(
     buildWindowsMpvLaunchArgs(
diff --git a/src/main/runtime/windows-mpv-launch.ts b/src/main/runtime/windows-mpv-launch.ts
index 04d39c0a..c6b4634c 100644
--- a/src/main/runtime/windows-mpv-launch.ts
+++ b/src/main/runtime/windows-mpv-launch.ts
@@ -1,5 +1,3 @@
-import fs from 'node:fs';
-import { spawn, spawnSync } from 'node:child_process';
 import { isLogFileEnabled } from '../../shared/log-files';
 import { canConnectSocket } from '../../shared/socket-probe';
 import { buildMpvLaunchModeArgs } from '../../shared/mpv-launch-mode';
@@ -8,11 +6,19 @@ import { buildSubminerPluginRuntimeScriptOptParts } from '../../shared/subminer-
 import type { MpvLaunchMode } from '../../types/config';
 import type { SubminerPluginRuntimeScriptOptConfig } from '../../shared/subminer-plugin-script-opts';
 import type { InstalledMpvPluginDetection } from './first-run-setup-plugin';
+import {
+  createWindowsMpvPathDeps,
+  resolveWindowsMpvPath,
+  spawnMpvProcess,
+  type WindowsMpvPathDeps,
+} from './mpv-process';
+export {
+  getConfiguredWindowsMpvPathStatus,
+  resolveWindowsMpvPath,
+  type ConfiguredWindowsMpvPathStatus,
+} from './mpv-process';
 
-export interface WindowsMpvLaunchDeps {
-  getEnv: (name: string) => string | undefined;
-  runWhere: () => { status: number | null; stdout: string; error?: Error };
-  fileExists: (candidate: string) => boolean;
+export interface WindowsMpvLaunchDeps extends WindowsMpvPathDeps {
   spawnDetached: (command: string, args: string[], env?: NodeJS.ProcessEnv) => Promise<void>;
   isAppControlServerAvailable?: () => Promise<boolean>;
   sendAppControlCommand?: (
@@ -23,8 +29,6 @@ export interface WindowsMpvLaunchDeps {
   logInfo?: (message: string) => void;
 }
 
-export type ConfiguredWindowsMpvPathStatus = 'blank' | 'configured' | 'invalid';
-
 export interface WindowsMpvRuntimePluginPolicy {
   detectInstalledMpvPlugin?: (mpvPath: string) => InstalledMpvPluginDetection;
   notifyInstalledPluginDetected?: (detection: InstalledMpvPluginDetection) => void;
@@ -38,54 +42,6 @@ function normalizeCandidate(candidate: string | undefined): string {
   return typeof candidate === 'string' ? candidate.trim() : '';
 }
 
-function defaultWindowsMpvFileExists(candidate: string): boolean {
-  try {
-    return fs.statSync(candidate).isFile();
-  } catch {
-    return false;
-  }
-}
-
-export function getConfiguredWindowsMpvPathStatus(
-  configuredMpvPath = '',
-  fileExists: (candidate: string) => boolean = defaultWindowsMpvFileExists,
-): ConfiguredWindowsMpvPathStatus {
-  const configPath = normalizeCandidate(configuredMpvPath);
-  if (!configPath) {
-    return 'blank';
-  }
-  return fileExists(configPath) ? 'configured' : 'invalid';
-}
-
-export function resolveWindowsMpvPath(deps: WindowsMpvLaunchDeps, configuredMpvPath = ''): string {
-  const configPath = normalizeCandidate(configuredMpvPath);
-  const configuredPathStatus = getConfiguredWindowsMpvPathStatus(configPath, deps.fileExists);
-  if (configuredPathStatus === 'configured') {
-    return configPath;
-  }
-  if (configuredPathStatus === 'invalid') {
-    return '';
-  }
-
-  const envPath = normalizeCandidate(deps.getEnv('SUBMINER_MPV_PATH'));
-  if (envPath && deps.fileExists(envPath)) {
-    return envPath;
-  }
-
-  const whereResult = deps.runWhere();
-  if (whereResult.status === 0) {
-    const firstPath = whereResult.stdout
-      .split(/\r?\n/)
-      .map((line) => line.trim())
-      .find((line) => line.length > 0 && deps.fileExists(line));
-    if (firstPath) {
-      return firstPath;
-    }
-  }
-
-  return '';
-}
-
 const DEFAULT_WINDOWS_MPV_SOCKET = '\\\\.\\pipe\\subminer-socket';
 const RUNNING_APP_ATTACH_SOCKET_WAIT_MS = 10000;
 
@@ -332,19 +288,7 @@ export function createWindowsMpvLaunchDeps(options: {
   logInfo?: (message: string) => void;
 }): WindowsMpvLaunchDeps {
   return {
-    getEnv: options.getEnv ?? ((name) => process.env[name]),
-    runWhere: () => {
-      const result = spawnSync('where.exe', ['mpv.exe'], {
-        encoding: 'utf8',
-        windowsHide: true,
-      });
-      return {
-        status: result.status,
-        stdout: result.stdout ?? '',
-        error: result.error ?? undefined,
-      };
-    },
-    fileExists: options.fileExists ?? defaultWindowsMpvFileExists,
+    ...createWindowsMpvPathDeps(options),
     isAppControlServerAvailable: options.isAppControlServerAvailable,
     sendAppControlCommand: options.sendAppControlCommand,
     waitForSocketReady,
@@ -352,12 +296,11 @@ export function createWindowsMpvLaunchDeps(options: {
     spawnDetached: (command, args, env) =>
       new Promise((resolve, reject) => {
         try {
-          const child = spawn(command, args, {
-            detached: true,
-            stdio: 'ignore',
-            windowsHide: true,
-            env: env ? { ...process.env, ...env } : process.env,
-          });
+          const child = spawnMpvProcess(
+            command,
+            args,
+            env ? { ...process.env, ...env } : process.env,
+          );
           let settled = false;
           child.once('error', (error) => {
             if (settled) return;
diff --git a/src/main/state.ts b/src/main/state.ts
index 728a1603..e9a963dd 100644
--- a/src/main/state.ts
+++ b/src/main/state.ts
@@ -206,7 +206,7 @@ export interface AppState {
   anilistSetupPageOpened: boolean;
   anilistRetryQueueState: AnilistRetryQueueState;
   firstRunSetupCompleted: boolean;
-  statsServer: { close: () => void } | null;
+  statsServer: { close: () => Promise<void> } | null;
   statsStartupInProgress: boolean;
 }
 
diff --git a/src/main/sync-cli.ts b/src/main/sync-cli.ts
index 2623ad26..899b9089 100644
--- a/src/main/sync-cli.ts
+++ b/src/main/sync-cli.ts
@@ -14,9 +14,10 @@ import {
   assertSafeSshHost,
   detectRemoteShellFlavor,
   resolveRemoteSubminerCommand,
-  runScp,
   runSsh,
 } from '../core/services/stats-sync/ssh';
+import { createSnapshotTransfer } from '../core/services/stats-sync/snapshot-transfer';
+import { createTransferCache } from '../core/services/stats-sync/transfer-cache';
 import {
   ensureTrackerQuiescentFlow,
   runSyncFlow,
@@ -63,7 +64,8 @@ function buildSyncCliDeps(): SyncFlowDeps {
     assertSafeSshHost,
     detectRemoteShellFlavor,
     resolveRemoteSubminerCommand,
-    runScp,
+    createSnapshotTransfer,
+    transferCache: createTransferCache(),
     runSsh,
     canConnectUnixSocket: canConnectSocket,
     realpathSync: (candidate) => fs.realpathSync(candidate),
diff --git a/src/media-generator.test.ts b/src/media-generator.test.ts
index 68a3fa30..1e48fb38 100644
--- a/src/media-generator.test.ts
+++ b/src/media-generator.test.ts
@@ -10,6 +10,9 @@ import {
   MediaGenerator,
   type MediaGeneratorOptions,
 } from './media-generator';
+import { RemoteMediaWindowCache } from './core/services/remote-media-window-cache';
+
+const REMOTE_STREAM_URL = 'https://jellyfin.example/Videos/abc/stream?static=true';
 
 async function withStubbedFfmpeg(
   run: (generator: MediaGenerator, argsPath: string) => Promise<void>,
@@ -21,6 +24,7 @@ async function withStubbedFfmpeg(
   const root = fs.mkdtempSync(path.join(os.tmpdir(), 'subminer-media-generator-test-'));
   const binDir = path.join(root, 'bin');
   const tempDir = path.join(root, 'media');
+  const windowsDir = path.join(root, 'windows');
   const argsPath = path.join(root, 'ffmpeg-args.txt');
   fs.mkdirSync(binDir, { recursive: true });
   const ffmpegStubPath = path.join(binDir, 'ffmpeg-stub.cjs');
@@ -34,7 +38,7 @@ async function withStubbedFfmpeg(
       "  console.log(' V..... libaom-av1');",
       '  process.exit(0);',
       '}',
-      "fs.writeFileSync(process.env.SUBMINER_TEST_FFMPEG_ARGS, JSON.stringify(args), 'utf8');",
+      "fs.appendFileSync(process.env.SUBMINER_TEST_FFMPEG_ARGS, JSON.stringify(args) + '\\n', 'utf8');",
       'const outputPath = args.at(-1);',
       "if (process.env.SUBMINER_TEST_FFMPEG_SKIP_OUTPUT !== '1') {",
       "  fs.writeFileSync(outputPath, 'avif', 'utf8');",
@@ -61,12 +65,18 @@ async function withStubbedFfmpeg(
   } else {
     delete process.env.SUBMINER_TEST_FFMPEG_SKIP_OUTPUT;
   }
-  const generator = new MediaGenerator(tempDir, options);
+  // Each test gets its own window cache so remote inputs never leak windows between tests.
+  const remoteMediaWindows = new RemoteMediaWindowCache({ tempDir: windowsDir, idleTtlMs: 0 });
+  const generator = new MediaGenerator(tempDir, {
+    remoteMediaWindows,
+    ...options,
+  });
 
   try {
     await run(generator, argsPath);
   } finally {
     generator.cleanup();
+    remoteMediaWindows.cleanup();
     process.env.PATH = originalPath;
     if (originalArgsPath === undefined) {
       delete process.env.SUBMINER_TEST_FFMPEG_ARGS;
@@ -82,8 +92,17 @@ async function withStubbedFfmpeg(
   }
 }
 
+function readAllFfmpegArgs(argsPath: string): string[][] {
+  return fs
+    .readFileSync(argsPath, 'utf8')
+    .split('\n')
+    .filter((line) => line.trim().length > 0)
+    .map((line) => JSON.parse(line) as string[]);
+}
+
+/** Arguments of the most recent ffmpeg invocation. */
 function readFfmpegArgs(argsPath: string): string[] {
-  return JSON.parse(fs.readFileSync(argsPath, 'utf8')) as string[];
+  return readAllFfmpegArgs(argsPath).at(-1) ?? [];
 }
 
 test('buildAnimatedImageVideoFilter holds lead-in until the next frame after the audio boundary', () => {
@@ -272,41 +291,131 @@ test('generateAudio recreates missing temp directory before invoking ffmpeg', as
 });
 
 test('generateAudio adds remote input options before the ffmpeg input', async () => {
-  await withStubbedFfmpeg(async (generator, argsPath) => {
-    await generator.generateAudio(
-      {
-        path: 'https://rr1---sn.example.googlevideo.com/videoplayback?mime=audio%2Fwebm',
-        inputOptions: {
-          reconnect: true,
-          userAgent: 'Mozilla/5.0',
-          headers: {
-            Referer: 'https://www.youtube.com/',
-            Origin: 'https://www.youtube.com',
+  await withStubbedFfmpeg(
+    async (generator, argsPath) => {
+      await generator.generateAudio(
+        {
+          path: 'https://rr1---sn.example.googlevideo.com/videoplayback?mime=audio%2Fwebm',
+          inputOptions: {
+            reconnect: true,
+            userAgent: 'Mozilla/5.0',
+            headers: {
+              Referer: 'https://www.youtube.com/',
+              Origin: 'https://www.youtube.com',
+            },
           },
         },
-      },
+        10,
+        12,
+      );
+
+      const args = readFfmpegArgs(argsPath);
+      const inputIndex = args.indexOf('-i');
+      assert.ok(inputIndex > 0);
+      assert.ok(args.indexOf('-reconnect') > -1);
+      assert.ok(args.indexOf('-reconnect') < inputIndex);
+      assert.equal(args[args.indexOf('-reconnect') + 1], '1');
+      assert.equal(args[args.indexOf('-reconnect_streamed') + 1], '1');
+      assert.equal(args[args.indexOf('-reconnect_on_network_error') + 1], '1');
+      assert.equal(args[args.indexOf('-reconnect_on_http_error') + 1], '403,5xx');
+      assert.equal(args[args.indexOf('-reconnect_delay_max') + 1], '5');
+      assert.equal(args[args.indexOf('-user_agent') + 1], 'Mozilla/5.0');
+      assert.equal(
+        args[args.indexOf('-headers') + 1],
+        'Referer: https://www.youtube.com/\r\nOrigin: https://www.youtube.com\r\n',
+      );
+    },
+    { remoteMediaWindows: null },
+  );
+});
+
+test('generateAudio downloads a remote window once and extracts from it with absolute seeks', async () => {
+  await withStubbedFfmpeg(async (generator, argsPath) => {
+    await generator.generateAudio(
+      { path: REMOTE_STREAM_URL, inputOptions: { reconnect: true } },
       10,
       12,
+      0.5,
+      2,
     );
 
-    const args = readFfmpegArgs(argsPath);
-    const inputIndex = args.indexOf('-i');
-    assert.ok(inputIndex > 0);
-    assert.ok(args.indexOf('-reconnect') > -1);
-    assert.ok(args.indexOf('-reconnect') < inputIndex);
-    assert.equal(args[args.indexOf('-reconnect') + 1], '1');
-    assert.equal(args[args.indexOf('-reconnect_streamed') + 1], '1');
-    assert.equal(args[args.indexOf('-reconnect_on_network_error') + 1], '1');
-    assert.equal(args[args.indexOf('-reconnect_on_http_error') + 1], '403,5xx');
-    assert.equal(args[args.indexOf('-reconnect_delay_max') + 1], '5');
-    assert.equal(args[args.indexOf('-user_agent') + 1], 'Mozilla/5.0');
-    assert.equal(
-      args[args.indexOf('-headers') + 1],
-      'Referer: https://www.youtube.com/\r\nOrigin: https://www.youtube.com\r\n',
-    );
+    const calls = readAllFfmpegArgs(argsPath);
+    assert.equal(calls.length, 2);
+    const [fetchArgs, audioArgs] = calls as [string[], string[]];
+    assert.equal(fetchArgs[fetchArgs.indexOf('-i') + 1], REMOTE_STREAM_URL);
+    assert.ok(fetchArgs.indexOf('-reconnect') < fetchArgs.indexOf('-i'));
+    assert.equal(fetchArgs[fetchArgs.indexOf('-ss') + 1], '9.25');
+    assert.equal(fetchArgs[fetchArgs.lastIndexOf('-map') + 1], '0:2');
+    assert.ok(fetchArgs.includes('-copyts'));
+
+    const windowPath = audioArgs[audioArgs.indexOf('-i') + 1];
+    assert.ok(windowPath?.endsWith('.mkv'));
+    assert.notEqual(windowPath, REMOTE_STREAM_URL);
+    assert.equal(audioArgs[audioArgs.indexOf('-ss') + 1], '9.5');
+    assert.equal(audioArgs[audioArgs.indexOf('-seek_timestamp') + 1], '1');
+    assert.ok(audioArgs.indexOf('-seek_timestamp') < audioArgs.indexOf('-i'));
+    assert.equal(audioArgs.includes('-reconnect'), false);
+    assert.equal(audioArgs.includes('-map'), false);
+    assert.equal(audioArgs.includes('-probesize'), false);
+    assert.ok(audioArgs.includes('loudnorm=I=-23:TP=-2:LRA=11'));
   });
 });
 
+test('generateScreenshot reuses a downloaded window but never downloads one itself', async () => {
+  await withStubbedFfmpeg(async (generator, argsPath) => {
+    await generator.generateScreenshot(REMOTE_STREAM_URL, 11, { format: 'jpg' });
+    let calls = readAllFfmpegArgs(argsPath);
+    assert.equal(calls.length, 1);
+    assert.equal(calls[0]![calls[0]!.indexOf('-i') + 1], REMOTE_STREAM_URL);
+
+    await generator.generateAudio(REMOTE_STREAM_URL, 10, 12);
+    await generator.generateScreenshot(REMOTE_STREAM_URL, 11, { format: 'jpg' });
+    await generator.generateScreenshot(REMOTE_STREAM_URL, 40, { format: 'jpg' });
+
+    calls = readAllFfmpegArgs(argsPath);
+    assert.equal(calls.length, 5);
+    const insideWindow = calls[3]!;
+    assert.ok(insideWindow[insideWindow.indexOf('-i') + 1]?.endsWith('.mkv'));
+    assert.equal(insideWindow[insideWindow.indexOf('-seek_timestamp') + 1], '1');
+    const outsideWindow = calls[4]!;
+    assert.equal(outsideWindow[outsideWindow.indexOf('-i') + 1], REMOTE_STREAM_URL);
+  });
+});
+
+test('generateAnimatedImage downloads the clip window before encoding', async () => {
+  await withStubbedFfmpeg(async (generator, argsPath) => {
+    await generator.generateAnimatedImage(REMOTE_STREAM_URL, 10, 12, 0, { fps: 10 });
+
+    const calls = readAllFfmpegArgs(argsPath).filter(
+      (args) => args[0] !== '-hide_banner' || args[1] !== '-encoders',
+    );
+    assert.equal(calls.length, 2);
+    assert.equal(calls[0]![calls[0]!.indexOf('-i') + 1], REMOTE_STREAM_URL);
+    assert.ok(calls[1]![calls[1]!.indexOf('-i') + 1]?.endsWith('.mkv'));
+    assert.equal(calls[1]![calls[1]!.indexOf('-seek_timestamp') + 1], '1');
+  });
+});
+
+test('generateAudio reads the remote source directly when the window download fails', async () => {
+  await withStubbedFfmpeg(
+    async (generator, argsPath) => {
+      await generator.generateAudio(REMOTE_STREAM_URL, 10, 12);
+
+      const args = readFfmpegArgs(argsPath);
+      assert.equal(args[args.indexOf('-i') + 1], REMOTE_STREAM_URL);
+      assert.equal(args.includes('-seek_timestamp'), false);
+    },
+    {
+      remoteMediaWindows: new RemoteMediaWindowCache({
+        execFile: (_file, _args, _options, callback) =>
+          queueMicrotask(() => callback(Object.assign(new Error('offline'), { code: 1 }))),
+        idleTtlMs: 0,
+        logDebug: () => undefined,
+      }),
+    },
+  );
+});
+
 test('generateAudio skips stale audio stream maps for single resolved streams', async () => {
   await withStubbedFfmpeg(async (generator, argsPath) => {
     await generator.generateAudio(
@@ -320,8 +429,9 @@ test('generateAudio skips stale audio stream maps for single resolved streams',
       22,
     );
 
-    const args = readFfmpegArgs(argsPath);
-    assert.equal(args.includes('-map'), false);
+    const [fetchArgs, audioArgs] = readAllFfmpegArgs(argsPath) as [string[], string[]];
+    assert.equal(fetchArgs[fetchArgs.lastIndexOf('-map') + 1], '0:a');
+    assert.equal(audioArgs.includes('-map'), false);
   });
 });
 
diff --git a/src/media-generator.ts b/src/media-generator.ts
index 037ae50f..0db61d26 100644
--- a/src/media-generator.ts
+++ b/src/media-generator.ts
@@ -22,6 +22,12 @@ import * as path from 'path';
 import * as os from 'os';
 import { createLogger } from './logger';
 import { normalizeMediaInput, type MediaInput } from './media-input';
+import {
+  getSharedRemoteMediaWindowCache,
+  isRemoteMediaWindowSourcePath,
+  type RemoteMediaWindowCache,
+  type RemoteMediaWindowRange,
+} from './core/services/remote-media-window-cache';
 
 const log = createLogger('media');
 const AUDIO_NORMALIZATION_FILTER = 'loudnorm=I=-23:TP=-2:LRA=11';
@@ -86,6 +92,11 @@ export interface MediaGeneratorOptions {
   logDebug?: (message: string) => void;
   now?: () => number;
   execFile?: MediaGeneratorExecFile;
+  /**
+   * Local window cache for http(s) sources. Defaults to the process-wide cache shared
+   * with the timing review; pass `null` to always read remote sources directly.
+   */
+  remoteMediaWindows?: RemoteMediaWindowCache | null;
 }
 
 function sanitizeDebugToken(value: string, fallback: string): string {
@@ -232,6 +243,54 @@ export class MediaGenerator {
     }, delayMs);
   }
 
+  /**
+   * Swaps an http(s) input for the locally cached window that covers `range`, so the
+   * clip is downloaded once instead of per FFmpeg run. `acquire` downloads on a miss;
+   * `lookup` only reuses a window that another step already fetched. Any failure falls
+   * back to reading the remote source directly.
+   */
+  private async resolveRemoteWindowInput(
+    input: MediaInput,
+    range: RemoteMediaWindowRange,
+    audioStreamIndex: number | null | undefined,
+    mode: 'acquire' | 'lookup',
+  ): Promise<MediaInput> {
+    const cache =
+      this.options.remoteMediaWindows === undefined
+        ? getSharedRemoteMediaWindowCache()
+        : this.options.remoteMediaWindows;
+    const sourcePath = typeof input === 'string' ? input : input.path;
+    if (!cache || !isRemoteMediaWindowSourcePath(sourcePath)) {
+      return input;
+    }
+    const source = {
+      path: sourcePath,
+      ...(typeof input === 'object' && input.inputOptions
+        ? { inputOptions: input.inputOptions }
+        : {}),
+      audioStreamIndex:
+        typeof input === 'object' && input.singleResolvedStream ? null : (audioStreamIndex ?? null),
+    };
+    const description = describeMediaInputForDebugLog(input);
+    try {
+      const window =
+        mode === 'acquire' ? await cache.acquire(source, range) : await cache.lookup(source, range);
+      if (!window) {
+        this.logMediaDebug(`window miss ${description} mode=${mode}`);
+        return input;
+      }
+      this.logMediaDebug(
+        `window hit ${description} mode=${mode} start=${window.startTime} end=${window.endTime}`,
+      );
+      return window.media;
+    } catch (error) {
+      this.logMediaDebug(
+        `window failed ${description} mode=${mode} reason=${sanitizeDebugToken((error as Error).message, 'error')}`,
+      );
+      return input;
+    }
+  }
+
   private ffmpegError(label: string, error: ExecFileException): Error {
     if (error.code === 'ENOENT') {
       return new Error('FFmpeg not found. Install FFmpeg to enable media generation.');
@@ -281,7 +340,13 @@ export class MediaGenerator {
     const safePadding = Number.isFinite(padding) ? Math.max(0, padding) : 0;
     const start = Math.max(0, startTime - safePadding);
     const duration = endTime - start + safePadding;
-    const mediaInput = normalizeMediaInput(videoPath);
+    const sourceInput = await this.resolveRemoteWindowInput(
+      videoPath,
+      { startTime: start, endTime: start + duration },
+      audioStreamIndex,
+      'acquire',
+    );
+    const mediaInput = normalizeMediaInput(sourceInput);
     const inputDescription = describeMediaInputForDebugLog(videoPath);
     const hasSelectedAudioStream =
       !mediaInput.singleResolvedStream &&
@@ -385,7 +450,15 @@ export class MediaGenerator {
       png: 'png',
       webp: 'webp',
     };
-    const mediaInput = normalizeMediaInput(videoPath);
+    // A single frame is cheap to fetch remotely, so only reuse a window another step downloaded.
+    const mediaInput = normalizeMediaInput(
+      await this.resolveRemoteWindowInput(
+        videoPath,
+        { startTime: timestamp, endTime: timestamp },
+        null,
+        'lookup',
+      ),
+    );
     const inputDescription = describeMediaInputForDebugLog(videoPath);
 
     const args: string[] = [
@@ -533,9 +606,17 @@ export class MediaGenerator {
       );
     }
 
+    const mediaInput = normalizeMediaInput(
+      await this.resolveRemoteWindowInput(
+        videoPath,
+        { startTime: start, endTime: start + duration },
+        null,
+        'acquire',
+      ),
+    );
+
     return new Promise((resolve, reject) => {
       const outputPath = this.createTempOutputPath('animation', 'avif');
-      const mediaInput = normalizeMediaInput(videoPath);
       const startedAt = this.nowMs();
 
       const encoderArgs: string[] = ['-c:v', av1Encoder];
diff --git a/src/media-input.ts b/src/media-input.ts
index 52349e19..c225354e 100644
--- a/src/media-input.ts
+++ b/src/media-input.ts
@@ -11,6 +11,12 @@ export type MediaInput =
       source?: string;
       inputOptions?: MediaInputOptions;
       singleResolvedStream?: boolean;
+      /**
+       * The file keeps the original media timestamps instead of starting at zero (a
+       * stream-copied window of a longer source). Seek with `-ss` against those
+       * absolute timestamps rather than relative to the file's own start time.
+       */
+      absoluteTimestamps?: boolean;
     };
 
 export type NormalizedMediaInput = {
@@ -89,6 +95,10 @@ export function normalizeMediaInput(input: MediaInput): NormalizedMediaInput {
     inputArgs.push('-headers', headers);
   }
 
+  if (input.absoluteTimestamps) {
+    inputArgs.push('-seek_timestamp', '1');
+  }
+
   return {
     path: input.path,
     inputArgs,
diff --git a/src/preload-clipboard.test.ts b/src/preload-clipboard.test.ts
new file mode 100644
index 00000000..d0bd4224
--- /dev/null
+++ b/src/preload-clipboard.test.ts
@@ -0,0 +1,46 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { runInNewContext } from 'node:vm';
+import { build } from 'esbuild';
+
+test('sidebar clipboard bridge writes exact text without renderer focus and rejects non-text input', async () => {
+  const result = await build({
+    entryPoints: ['src/preload.ts'],
+    bundle: true,
+    platform: 'node',
+    format: 'cjs',
+    external: ['electron'],
+    write: false,
+  });
+  const output = result.outputFiles[0];
+  assert.ok(output);
+  const writes: string[] = [];
+  let exposed: unknown;
+  runInNewContext(output.text, {
+    process: { argv: [] },
+    require: (name: string) => {
+      assert.equal(name, 'electron');
+      return {
+        ipcRenderer: { on: () => {} },
+        clipboard: { writeText: (text: string) => writes.push(text) },
+        contextBridge: {
+          exposeInMainWorld: (_name: string, api: unknown) => {
+            exposed = api;
+          },
+        },
+      };
+    },
+  });
+  assert.ok(
+    typeof exposed === 'object' && exposed !== null && 'copySubtitleSidebarSelection' in exposed,
+  );
+  const copy = exposed.copySubtitleSidebarSelection;
+  if (typeof copy !== 'function') throw new Error('Missing clipboard bridge');
+  const text = '最初の台詞\n二行目\n\n同じ台詞';
+  await copy(text);
+  assert.deepEqual(writes, [text]);
+  for (const value of [null, undefined, 42, { text }, ['台詞']]) {
+    await assert.rejects(async () => copy(value), /Subtitle selection must be text/);
+  }
+  assert.deepEqual(writes, [text]);
+});
diff --git a/src/preload.ts b/src/preload.ts
index a48fdb0c..16d9e7b5 100644
--- a/src/preload.ts
+++ b/src/preload.ts
@@ -16,7 +16,7 @@
  * along with this program.  If not, see <https://www.gnu.org/licenses/>.
  */
 
-import { contextBridge, ipcRenderer, IpcRendererEvent, webUtils } from 'electron';
+import { clipboard, contextBridge, ipcRenderer, IpcRendererEvent, webUtils } from 'electron';
 import { resolveOverlayLayerFromArgv } from './preload-args';
 import type {
   SubtitleData,
@@ -69,10 +69,20 @@ import type {
   OverlayNotificationEventPayload,
   OverlayNotificationPosition,
   ChangelogSnapshot,
+  MediaTimingReviewActionResult,
+  MediaTimingReviewOpenPayload,
+  MediaTimingReviewPreviewRequest,
+  MediaTimingReviewResolveRequest,
+  MediaTimingReviewFrameRequest,
+  MediaTimingReviewFrameResult,
+  MediaTimingReviewWaveformRequest,
 } from './types';
 import { IPC_CHANNELS } from './shared/ipc/contracts';
+import type { SubtitleGenerationProgress } from './shared/subtitle-generation';
 
 const overlayLayer = resolveOverlayLayerFromArgv(process.argv);
+const onSubtitleSelectionOpen = createQueuedIpcListener(IPC_CHANNELS.event.subtitleSelectionOpen);
+const onSubtitleGenerationOpen = createQueuedIpcListener(IPC_CHANNELS.event.subtitleGenerationOpen);
 
 type EmptyListener = () => void;
 type PayloadedListener<T> = (payload: T) => void;
@@ -181,6 +191,15 @@ const onOpenYoutubeTrackPickerEvent = createQueuedIpcListenerWithPayload<Youtube
   IPC_CHANNELS.event.youtubePickerOpen,
   (payload) => payload as YoutubePickerOpenPayload,
 );
+const onOpenMediaTimingReviewEvent =
+  createQueuedIpcListenerWithPayload<MediaTimingReviewOpenPayload>(
+    IPC_CHANNELS.event.mediaTimingReviewOpen,
+    (payload) => payload as MediaTimingReviewOpenPayload,
+  );
+const onMediaTimingReviewPreviewEndedEvent = createQueuedIpcListenerWithPayload<string>(
+  IPC_CHANNELS.event.mediaTimingReviewPreviewEnded,
+  (payload) => (typeof payload === 'string' ? payload : ''),
+);
 const onOpenPlaylistBrowserEvent = createQueuedIpcListener(IPC_CHANNELS.event.playlistBrowserOpen);
 const onCancelYoutubeTrackPickerEvent = createQueuedIpcListener(
   IPC_CHANNELS.event.youtubePickerCancel,
@@ -247,6 +266,28 @@ const onSecondarySubtitleModeEvent = createLatestValueIpcListenerWithPayload<Sec
 );
 
 const electronAPI: ElectronAPI = {
+  requestSubtitleGenerationOpen: () =>
+    ipcRenderer.invoke(IPC_CHANNELS.request.requestSubtitleGenerationOpen),
+  onSubtitleGenerationOpen,
+  getSubtitleGenerationStatus: () =>
+    ipcRenderer.invoke(IPC_CHANNELS.request.getSubtitleGenerationStatus),
+  selectSubtitleGenerationModel: (model) =>
+    ipcRenderer.invoke(IPC_CHANNELS.request.selectSubtitleGenerationModel, model),
+  startSubtitleGeneration: () => ipcRenderer.invoke(IPC_CHANNELS.request.startSubtitleGeneration),
+  downloadSubtitleGenerationModel: () =>
+    ipcRenderer.invoke(IPC_CHANNELS.request.downloadSubtitleGenerationModel),
+  downloadSubtitleGenerationVadModel: () =>
+    ipcRenderer.invoke(IPC_CHANNELS.request.downloadSubtitleGenerationVadModel),
+  setSubtitleGenerationVadEnabled: (enabled) =>
+    ipcRenderer.invoke(IPC_CHANNELS.request.setSubtitleGenerationVadEnabled, enabled),
+  cancelSubtitleGeneration: () => ipcRenderer.invoke(IPC_CHANNELS.request.cancelSubtitleGeneration),
+  onSubtitleGenerationProgress: (callback) => {
+    const listener = (_event: IpcRendererEvent, progress: SubtitleGenerationProgress) =>
+      callback(progress);
+    ipcRenderer.on(IPC_CHANNELS.event.subtitleGenerationProgress, listener);
+    return () =>
+      ipcRenderer.removeListener(IPC_CHANNELS.event.subtitleGenerationProgress, listener);
+  },
   getOverlayLayer: () => overlayLayer,
   getPathForFile: (file: File) => webUtils.getPathForFile(file),
   onSubtitle: (callback: (data: SubtitleData) => void) => {
@@ -287,6 +328,10 @@ const electronAPI: ElectronAPI = {
     ipcRenderer.invoke(IPC_CHANNELS.request.getSubtitleSidebarOpen),
   getSubtitleSidebarSnapshot: () =>
     ipcRenderer.invoke(IPC_CHANNELS.request.getSubtitleSidebarSnapshot),
+  copySubtitleSidebarSelection: async (text: unknown) => {
+    if (typeof text !== 'string') throw new TypeError('Subtitle selection must be text.');
+    clipboard.writeText(text);
+  },
   getPlaybackPaused: (): Promise<boolean | null> =>
     ipcRenderer.invoke(IPC_CHANNELS.request.getPlaybackPaused),
   onSubtitleAss: (callback: (assText: string) => void) => {
@@ -332,6 +377,7 @@ const electronAPI: ElectronAPI = {
 
   getKeybindings: (): Promise<Keybinding[]> =>
     ipcRenderer.invoke(IPC_CHANNELS.request.getKeybindings),
+  getMpvInputBindings: () => ipcRenderer.invoke(IPC_CHANNELS.request.getMpvInputBindings),
   getSessionBindings: () => ipcRenderer.invoke(IPC_CHANNELS.request.getSessionBindings),
   getConfiguredShortcuts: (): Promise<Required<ShortcutsConfig>> =>
     ipcRenderer.invoke(IPC_CHANNELS.request.getConfigShortcuts),
@@ -418,6 +464,11 @@ const electronAPI: ElectronAPI = {
     ) as Promise<boolean>,
   getSubtitleStyle: (): Promise<SubtitleStyleConfig | null> =>
     ipcRenderer.invoke(IPC_CHANNELS.request.getSubtitleStyle),
+  onSubtitleSelectionOpen,
+  getSubtitleSelection: () => ipcRenderer.invoke(IPC_CHANNELS.request.getSubtitleSelection),
+  applySubtitleSelection: (
+    request: import('./shared/subtitle-selection').SubtitleSelectionRequest,
+  ) => ipcRenderer.invoke(IPC_CHANNELS.request.applySubtitleSelection, request),
   onSubsyncManualOpen: onSubsyncManualOpenEvent,
   runSubsyncManual: (request: SubsyncManualRunRequest): Promise<SubsyncResult> =>
     ipcRenderer.invoke(IPC_CHANNELS.request.runSubsyncManual, request),
@@ -458,6 +509,24 @@ const electronAPI: ElectronAPI = {
   onOpenJimaku: onOpenJimakuEvent,
   onOpenTsukihime: onOpenTsukihimeEvent,
   onOpenYoutubeTrackPicker: onOpenYoutubeTrackPickerEvent,
+  onOpenMediaTimingReview: onOpenMediaTimingReviewEvent,
+  onMediaTimingReviewPreviewEnded: onMediaTimingReviewPreviewEndedEvent,
+  previewMediaTimingReview: (
+    request: MediaTimingReviewPreviewRequest,
+  ): Promise<MediaTimingReviewActionResult> =>
+    ipcRenderer.invoke(IPC_CHANNELS.request.mediaTimingReviewPreview, request),
+  getMediaTimingReviewFrame: (
+    request: MediaTimingReviewFrameRequest,
+  ): Promise<MediaTimingReviewFrameResult> =>
+    ipcRenderer.invoke(IPC_CHANNELS.request.mediaTimingReviewFrame, request),
+  getMediaTimingReviewWaveform: (request: MediaTimingReviewWaveformRequest) =>
+    ipcRenderer.invoke(IPC_CHANNELS.request.mediaTimingReviewWaveform, request),
+  stopMediaTimingReviewPreview: (reviewId: string): Promise<MediaTimingReviewActionResult> =>
+    ipcRenderer.invoke(IPC_CHANNELS.request.mediaTimingReviewStopPreview, reviewId),
+  resolveMediaTimingReview: (
+    request: MediaTimingReviewResolveRequest,
+  ): Promise<MediaTimingReviewActionResult> =>
+    ipcRenderer.invoke(IPC_CHANNELS.request.mediaTimingReviewResolve, request),
   onOpenPlaylistBrowser: onOpenPlaylistBrowserEvent,
   onOpenCharacterDictionaryManager: onOpenCharacterDictionaryManagerEvent,
   onSubtitleSidebarToggle: onSubtitleSidebarToggleEvent,
@@ -517,6 +586,14 @@ const electronAPI: ElectronAPI = {
   reportOverlayContentBounds: (measurement: OverlayContentMeasurement) => {
     ipcRenderer.send(IPC_CHANNELS.command.reportOverlayContentBounds, measurement);
   },
+  onSessionBindingsChanged: (
+    callback: (bindings: import('./types').CompiledSessionBinding[]) => void,
+  ) => {
+    ipcRenderer.on(
+      IPC_CHANNELS.event.sessionBindingsChanged,
+      (_event, bindings: import('./types').CompiledSessionBinding[]) => callback(bindings),
+    );
+  },
   onConfigHotReload: (callback: (payload: ConfigHotReloadPayload) => void) => {
     ipcRenderer.on(
       IPC_CHANNELS.event.configHotReload,
diff --git a/src/prerelease-workflow.test.ts b/src/prerelease-workflow.test.ts
index 08c68086..29127f0b 100644
--- a/src/prerelease-workflow.test.ts
+++ b/src/prerelease-workflow.test.ts
@@ -2,9 +2,24 @@ import test from 'node:test';
 import assert from 'node:assert/strict';
 import { readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
+import {
+  jobSteps,
+  readWorkflow,
+  stepRunsCommand,
+  stepsMissingEnvDeclaration,
+  templateExpressionsInRunBodies,
+} from './workflow-test-helpers';
 
 const prereleaseWorkflowPath = resolve(__dirname, '../.github/workflows/prerelease.yml');
 const prereleaseWorkflow = readFileSync(prereleaseWorkflowPath, 'utf8').replace(/\r\n/g, '\n');
+const packageWorkflow = readFileSync(
+  resolve(__dirname, '../.github/workflows/package-release.yml'),
+  'utf8',
+);
+const parsedPrereleaseWorkflow = readWorkflow(prereleaseWorkflowPath);
+const parsedPackageWorkflow = readWorkflow(
+  resolve(__dirname, '../.github/workflows/package-release.yml'),
+);
 const packageJsonPath = resolve(__dirname, '../package.json');
 const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf8')) as {
   scripts: Record<string, string>;
@@ -34,15 +49,10 @@ test('prerelease workflow uses committed prerelease notes and never calls claude
 });
 
 test('prerelease delegates its quality gate instead of duplicating quality steps', () => {
-  assert.match(
-    prereleaseWorkflow,
-    /quality-gate:\s*\n\s*permissions:\s*\n\s*contents: read\s*\n\s*uses: \.\/\.github\/workflows\/quality-gate\.yml/,
-  );
-  const qualityGateJob = prereleaseWorkflow.match(/quality-gate:[\s\S]*?(?=\n  build-linux:)/)?.[0];
-  assert.ok(qualityGateJob);
-  assert.doesNotMatch(qualityGateJob, /oven-sh\/setup-bun/);
-  assert.doesNotMatch(qualityGateJob, /bun run test:coverage:src/);
-  assert.doesNotMatch(qualityGateJob, /bun run test:env/);
+  assert.deepEqual(parsedPrereleaseWorkflow.jobs?.['quality-gate'], {
+    permissions: { contents: 'read' },
+    uses: './.github/workflows/quality-gate.yml',
+  });
 });
 
 test('prerelease workflow publishes GitHub prereleases and keeps them off latest', () => {
@@ -52,10 +62,10 @@ test('prerelease workflow publishes GitHub prereleases and keeps them off latest
 });
 
 test('prerelease packaging workflows scope dependency caches by runner architecture', () => {
-  const archScopedCacheKeyMatches = prereleaseWorkflow.match(
+  const archScopedCacheKeyMatches = (prereleaseWorkflow + packageWorkflow).match(
     /key:\s*\${{\s*runner\.os\s*}}-\${{\s*runner\.arch\s*}}-bun-/g,
   );
-  const archScopedRestoreKeyMatches = prereleaseWorkflow.match(
+  const archScopedRestoreKeyMatches = (prereleaseWorkflow + packageWorkflow).match(
     /\${{\s*runner\.os\s*}}-\${{\s*runner\.arch\s*}}-bun-/g,
   );
   assert.equal(archScopedCacheKeyMatches?.length, 4);
@@ -63,22 +73,89 @@ test('prerelease packaging workflows scope dependency caches by runner architect
 });
 
 test('prerelease workflow builds and uploads all release platforms', () => {
-  assert.match(prereleaseWorkflow, /build-linux:/);
-  assert.match(prereleaseWorkflow, /build-macos:/);
-  assert.match(prereleaseWorkflow, /build-windows:/);
-  assert.match(prereleaseWorkflow, /name: appimage/);
-  assert.match(prereleaseWorkflow, /name: macos/);
-  assert.match(prereleaseWorkflow, /name: windows/);
+  assert.deepEqual(Object.keys(parsedPrereleaseWorkflow.jobs ?? {}).sort(), [
+    'package',
+    'quality-gate',
+    'release',
+  ]);
+  assert.equal(
+    parsedPrereleaseWorkflow.jobs?.package?.uses,
+    './.github/workflows/package-release.yml',
+  );
+  assert.deepEqual(parsedPrereleaseWorkflow.jobs?.package?.needs, ['quality-gate']);
+  assert.deepEqual(parsedPrereleaseWorkflow.jobs?.release?.needs, ['package']);
+  assert.deepEqual(Object.keys(parsedPackageWorkflow.jobs ?? {}).sort(), [
+    'build-linux',
+    'build-macos',
+    'build-windows',
+  ]);
+  for (const [job, name, paths] of [
+    ['build-linux', 'appimage', ['release/*.AppImage']],
+    ['build-macos', 'macos', ['release/*.dmg', 'release/*.zip']],
+    ['build-windows', 'windows', ['release/*.exe', 'release/*.zip']],
+  ] as const) {
+    const uploads = jobSteps(parsedPackageWorkflow, job).filter(
+      (step) => step.uses === 'actions/upload-artifact@v4',
+    );
+    assert.equal(uploads.length, 1);
+    const upload = uploads[0];
+    assert.ok(upload);
+    assert.equal(upload.with?.name, name);
+    assert.equal(upload.with?.['if-no-files-found'], 'error');
+    const uploadPath = upload.with?.path;
+    assert.ok(typeof uploadPath === 'string');
+    assert.deepEqual(uploadPath.trim().split('\n'), [
+      ...paths,
+      'release/latest*.yml',
+      'release/*.blockmap',
+    ]);
+    const download = jobSteps(parsedPrereleaseWorkflow, 'release').find(
+      (step) => step.uses === 'actions/download-artifact@v4' && step.with?.name === name,
+    );
+    assert.equal(download?.with?.path, 'release');
+  }
 });
 
-test('prerelease workflow publishes the same release assets as the stable workflow', () => {
+test('release callers pass only the declared packaging secrets', () => {
+  const signingSecrets = [
+    'CSC_LINK',
+    'CSC_KEY_PASSWORD',
+    'APPLE_ID',
+    'APPLE_APP_SPECIFIC_PASSWORD',
+    'APPLE_TEAM_ID',
+  ];
+  // The bundled TMDB key is optional: artifacts stay valid without it and
+  // users fall back to their own tmdb.apiKey.
+  const optionalSecrets = ['SUBMINER_TMDB_API_KEY'];
+  assert.deepEqual(parsedPackageWorkflow.on?.workflow_call?.secrets, {
+    ...Object.fromEntries(signingSecrets.map((name) => [name, { required: true }])),
+    ...Object.fromEntries(optionalSecrets.map((name) => [name, { required: false }])),
+  });
+  for (const workflow of [
+    parsedPrereleaseWorkflow,
+    readWorkflow(resolve(__dirname, '../.github/workflows/release.yml')),
+  ]) {
+    assert.equal(workflow.jobs?.package?.uses, './.github/workflows/package-release.yml');
+    assert.deepEqual(
+      workflow.jobs?.package?.secrets,
+      Object.fromEntries(
+        [...signingSecrets, ...optionalSecrets].map((name) => [
+          name,
+          '${{ secrets.' + name + ' }}',
+        ]),
+      ),
+    );
+  }
+});
+
+test('prerelease workflow publishes both launcher wrappers with the platform packages', () => {
   assert.match(
     prereleaseWorkflow,
-    /files=\(release\/\*\.AppImage release\/\*\.dmg release\/\*\.exe release\/\*\.zip release\/\*\.tar\.gz release\/latest\*\.yml release\/\*\.blockmap dist\/launcher\/subminer\)/,
+    /files=\(release\/\*\.AppImage release\/\*\.dmg release\/\*\.exe release\/\*\.zip release\/\*\.tar\.gz release\/latest\*\.yml release\/\*\.blockmap dist\/launcher\/subminer dist\/launcher\/subminer\.cmd\)/,
   );
   assert.match(
     prereleaseWorkflow,
-    /artifacts=\([\s\S]*release\/\*\.exe[\s\S]*release\/latest\*\.yml[\s\S]*release\/\*\.blockmap[\s\S]*release\/SHA256SUMS\.txt[\s\S]*\)/,
+    /artifacts=\([\s\S]*release\/\*\.exe[\s\S]*release\/latest\*\.yml[\s\S]*release\/\*\.blockmap[\s\S]*release\/SHA256SUMS\.txt[\s\S]*dist\/launcher\/subminer[\s\S]*dist\/launcher\/subminer\.cmd[\s\S]*\)/,
   );
 });
 
@@ -122,3 +199,33 @@ test('prerelease workflow does not publish to AUR', () => {
   assert.doesNotMatch(prereleaseWorkflow, /AUR_SSH_PRIVATE_KEY/);
   assert.doesNotMatch(prereleaseWorkflow, /scripts\/update-aur-package\.sh/);
 });
+
+test('prerelease workflow rejects committed notes generated for a different beta or rc', () => {
+  assert.equal(
+    packageJson.scripts['changelog:check-prerelease-notes'],
+    'bun run scripts/build-changelog.ts check-prerelease-notes',
+  );
+
+  // Matched at command positions only, so commenting the check out or quoting it
+  // inside an echo fails the test rather than silently satisfying it.
+  const steps = jobSteps(parsedPrereleaseWorkflow, 'release');
+  const checkIndex = steps.findIndex((step) =>
+    stepRunsCommand(
+      step,
+      /^bun run changelog:check-prerelease-notes --version "\$RELEASE_VERSION"/,
+    ),
+  );
+  const publishIndex = steps.findIndex((step) =>
+    stepRunsCommand(step, /^gh release (create|edit)\b/),
+  );
+
+  assert.notEqual(checkIndex, -1);
+  assert.notEqual(publishIndex, -1);
+  // Stale notes are already published if the check runs after the release.
+  assert.ok(checkIndex < publishIndex);
+});
+
+test('prerelease workflow keeps tag-derived values out of shell bodies', () => {
+  assert.deepEqual(templateExpressionsInRunBodies(parsedPrereleaseWorkflow), []);
+  assert.deepEqual(stepsMissingEnvDeclaration(parsedPrereleaseWorkflow, 'RELEASE_VERSION'), []);
+});
diff --git a/src/quality-gate-workflow.test.ts b/src/quality-gate-workflow.test.ts
index 2178a0de..cd99a7c2 100644
--- a/src/quality-gate-workflow.test.ts
+++ b/src/quality-gate-workflow.test.ts
@@ -22,12 +22,28 @@ test('quality gate checkout does not persist GitHub credentials', () => {
   );
 });
 
-test('quality gate installs Lua and runs the environment suite before coverage', () => {
+test('quality gate runs non-covered source suites and lets coverage gate the src lane', () => {
   assert.match(qualityGateWorkflow, /name: Install Lua/);
-  assert.match(qualityGateWorkflow, /apt-get install -y lua5\.4/);
   assert.match(
     qualityGateWorkflow,
-    /Test suite \(source\)\n\s*run: bun run test:fast\n\s*\n\s*- name: Environment suite\n\s*run: bun run test:env\n\s*\n\s*- name: Coverage suite \(maintained source lane\)/,
+    /apt_sources=\(-o Dir::Etc::sourcelist=sources\.list\.d\/ubuntu\.sources -o Dir::Etc::sourceparts=-\)/,
+  );
+  assert.match(qualityGateWorkflow, /apt-get\s+"\$\{apt_sources\[@\]\}"\s+update/);
+  assert.match(qualityGateWorkflow, /apt-get\s+"\$\{apt_sources\[@\]\}"\s+install\s+-y\s+lua5\.4/);
+  assert.match(
+    qualityGateWorkflow,
+    /Launcher unit and script suites\n\s*run: bun run test:launcher:unit:src && bun run test:scripts/,
+  );
+  assert.doesNotMatch(qualityGateWorkflow, /bun run test:fast/);
+  assert.match(qualityGateWorkflow, /run: bun run test:coverage:src/);
+});
+
+test('quality gate runs launcher smoke once through the environment suite and keeps artifacts', () => {
+  assert.match(qualityGateWorkflow, /name: Environment suite\n\s*run: bun run test:env/);
+  assert.doesNotMatch(qualityGateWorkflow, /run: bun run test:launcher:smoke:src/);
+  assert.match(
+    qualityGateWorkflow,
+    /name: Upload launcher smoke artifacts \(on failure\)[\s\S]*?if: failure\(\)[\s\S]*?path: \.tmp\/launcher-smoke\/\*\*/,
   );
 });
 
@@ -37,6 +53,13 @@ test('quality gate uploads maintained source coverage', () => {
   assert.match(qualityGateWorkflow, /path: coverage\/test-src\/lcov\.info/);
 });
 
+test('quality gate preserves stats, compiled SQLite, and dist runtime checks', () => {
+  assert.match(qualityGateWorkflow, /run: bun run test:stats/);
+  assert.match(qualityGateWorkflow, /run: bun run build/);
+  assert.match(qualityGateWorkflow, /run: bun run test:immersion:sqlite:dist/);
+  assert.match(qualityGateWorkflow, /run: bun run test:smoke:dist/);
+});
+
 test('quality gate keeps pull request changelog enforcement event-aware', () => {
   assert.match(qualityGateWorkflow, /bun run changelog:lint/);
   assert.match(qualityGateWorkflow, /if: github\.event_name == 'pull_request'/);
diff --git a/src/release-workflow.test.ts b/src/release-workflow.test.ts
index 0cfda411..9946d1de 100644
--- a/src/release-workflow.test.ts
+++ b/src/release-workflow.test.ts
@@ -2,13 +2,27 @@ import test from 'node:test';
 import assert from 'node:assert/strict';
 import { readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
+import {
+  jobSteps,
+  readWorkflow,
+  stepsMissingEnvDeclaration,
+  templateExpressionsInRunBodies,
+} from './workflow-test-helpers';
 
 const releaseWorkflowPath = resolve(__dirname, '../.github/workflows/release.yml');
 const releaseWorkflow = readFileSync(releaseWorkflowPath, 'utf8');
+const packageWorkflow = readFileSync(
+  resolve(__dirname, '../.github/workflows/package-release.yml'),
+  'utf8',
+);
 const docsPagesWorkflowPath = resolve(__dirname, '../.github/workflows/docs-pages.yml');
 const docsPagesWorkflow = readFileSync(docsPagesWorkflowPath, 'utf8');
+const parsedReleaseWorkflow = readWorkflow(releaseWorkflowPath);
+const parsedDocsPagesWorkflow = readWorkflow(docsPagesWorkflowPath);
 const makefilePath = resolve(__dirname, '../Makefile');
 const makefile = readFileSync(makefilePath, 'utf8');
+const buildLauncherPath = resolve(__dirname, '../scripts/build-launcher.ts');
+const buildLauncher = readFileSync(buildLauncherPath, 'utf8');
 const packageJsonPath = resolve(__dirname, '../package.json');
 const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf8')) as {
   desktopName?: string;
@@ -25,6 +39,7 @@ const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf8')) as {
     extraResources?: Array<{
       from?: string;
       to?: string;
+      filter?: string[];
     }>;
     mac?: {
       artifactName?: string;
@@ -57,7 +72,7 @@ test('stable release tags publish docs and prereleases do not update stable docs
   assert.match(docsPagesWorkflow, /tags:\s*\n\s*-\s*'v\*'/);
   assert.match(docsPagesWorkflow, /github\.ref_name/);
   assert.match(docsPagesWorkflow, /\^v\[0-9\]\+\\\.\[0-9\]\+\\\.\[0-9\]\+\$/);
-  assert.match(docsPagesWorkflow, /bun run docs:build:versioned/);
+  assert.match(docsPagesWorkflow, /bun run scripts\/build-versioned-docs\.ts/);
   assert.doesNotMatch(docsPagesWorkflow, /beta/);
 });
 
@@ -86,20 +101,25 @@ test('release delegates its quality gate instead of duplicating quality steps',
     releaseWorkflow,
     /quality-gate:\s*\n\s*permissions:\s*\n\s*contents: read\s*\n\s*uses: \.\/\.github\/workflows\/quality-gate\.yml/,
   );
-  const qualityGateJob = releaseWorkflow.match(/quality-gate:[\s\S]*?(?=\n  build-linux:)/)?.[0];
+  const qualityGateJob = releaseWorkflow.match(/quality-gate:[\s\S]*?(?=\n  package:)/)?.[0];
   assert.ok(qualityGateJob);
   assert.doesNotMatch(qualityGateJob, /oven-sh\/setup-bun/);
   assert.doesNotMatch(qualityGateJob, /bun run test:coverage:src/);
   assert.doesNotMatch(qualityGateJob, /bun run test:env/);
 });
 
-test('release build jobs install and cache stats dependencies before packaging', () => {
-  assert.match(releaseWorkflow, /build-linux:[\s\S]*stats\/node_modules/);
-  assert.match(releaseWorkflow, /build-macos:[\s\S]*stats\/node_modules/);
-  assert.match(releaseWorkflow, /build-windows:[\s\S]*stats\/node_modules/);
-  assert.match(releaseWorkflow, /build-linux:[\s\S]*cd stats && bun install --frozen-lockfile/);
-  assert.match(releaseWorkflow, /build-macos:[\s\S]*cd stats && bun install --frozen-lockfile/);
-  assert.match(releaseWorkflow, /build-windows:[\s\S]*cd stats && bun install --frozen-lockfile/);
+test('each release build job installs stats dependencies before packaging', () => {
+  const workflow = readWorkflow(resolve(__dirname, '../.github/workflows/package-release.yml'));
+  for (const job of ['build-linux', 'build-macos', 'build-windows']) {
+    const steps = jobSteps(workflow, job);
+    const install = steps.findIndex((step) =>
+      step.run?.includes('cd stats && bun install --frozen-lockfile'),
+    );
+    const build = steps.findIndex((step) =>
+      /bun run build:(appimage|mac|win)/.test(step.run ?? ''),
+    );
+    assert(install >= 0 && build > install, `${job} must install stats before packaging`);
+  }
 });
 
 test('release workflow generates release notes from committed changelog output', () => {
@@ -107,14 +127,14 @@ test('release workflow generates release notes from committed changelog output',
   assert.ok(!releaseWorkflow.includes('git log --pretty=format:"- %s"'));
 });
 
-test('release workflow includes the Windows installer in checksums and uploaded assets', () => {
+test('release workflow includes the Windows installer and both launcher wrappers in release assets', () => {
   assert.match(
     releaseWorkflow,
-    /files=\(release\/\*\.AppImage release\/\*\.dmg release\/\*\.exe release\/\*\.zip release\/\*\.tar\.gz release\/latest\*\.yml release\/\*\.blockmap dist\/launcher\/subminer\)/,
+    /files=\(release\/\*\.AppImage release\/\*\.dmg release\/\*\.exe release\/\*\.zip release\/\*\.tar\.gz release\/latest\*\.yml release\/\*\.blockmap dist\/launcher\/subminer dist\/launcher\/subminer\.cmd\)/,
   );
   assert.match(
     releaseWorkflow,
-    /artifacts=\([\s\S]*release\/\*\.exe[\s\S]*release\/latest\*\.yml[\s\S]*release\/\*\.blockmap[\s\S]*release\/SHA256SUMS\.txt[\s\S]*\)/,
+    /artifacts=\([\s\S]*release\/\*\.exe[\s\S]*release\/latest\*\.yml[\s\S]*release\/\*\.blockmap[\s\S]*release\/SHA256SUMS\.txt[\s\S]*dist\/launcher\/subminer[\s\S]*dist\/launcher\/subminer\.cmd[\s\S]*\)/,
   );
 });
 
@@ -153,51 +173,22 @@ test('top-level package metadata keeps Linux Electron runtime app identity canon
   assert.equal(packageJson.desktopName, 'SubMiner.desktop');
 });
 
-test('release packaging keeps default file inclusion and excludes large source-only trees explicitly', () => {
-  const files = packageJson.build?.files ?? [];
-  assert.ok(files.includes('**/*'));
-  assert.ok(files.includes('!src{,/**/*}'));
-  assert.ok(files.includes('!launcher{,/**/*}'));
-  assert.ok(files.includes('!stats/src{,/**/*}'));
-  assert.ok(files.includes('!.tmp{,/**/*}'));
-  assert.ok(files.includes('!release-*{,/**/*}'));
-  assert.ok(files.includes('!vendor/subminer-yomitan{,/**/*}'));
-  assert.ok(files.includes('!vendor/texthooker-ui/src{,/**/*}'));
-  assert.ok(files.includes('!assets{,/**/*}'));
-  assert.ok(files.includes('!plugin{,/**/*}'));
-  assert.ok(files.includes('!vendor/yomitan-jlpt-vocab{,/**/*}'));
-  assert.ok(files.includes('!docs{,/**/*}'));
-  assert.ok(files.includes('!tests{,/**/*}'));
-  assert.ok(files.includes('!packaging{,/**/*}'));
-  assert.ok(files.includes('!README.md'));
-  assert.ok(files.includes('!CHANGELOG.md'));
-  assert.ok(files.includes('!AGENTS.md'));
-  assert.ok(files.includes('!CLAUDE.md'));
-  assert.ok(files.includes('!stats/public{,/**/*}'));
-  assert.ok(files.includes('!stats/package.json'));
-  assert.ok(files.includes('!stats/tsconfig.json'));
-  assert.ok(files.includes('!stats/vite.config.ts'));
-  assert.ok(files.includes('!dist/**/*.map'));
-  assert.ok(files.includes('!dist/**/*.test.*'));
-  assert.ok(files.includes('!dist/**/__tests__{,/**/*}'));
-  assert.ok(files.includes('!scripts/**/*.test.*'));
-  assert.ok(files.includes('!vendor/texthooker-ui/public{,/**/*}'));
-  assert.ok(files.includes('!vendor/texthooker-ui/.vscode{,/**/*}'));
-  assert.ok(files.includes('!vendor/texthooker-ui/README.md'));
-  assert.ok(files.includes('!vendor/texthooker-ui/package.json'));
-  assert.ok(files.includes('!vendor/texthooker-ui/tsconfig*.json'));
-  assert.ok(files.includes('!node_modules/@libsql/linux-x64-musl{,/**/*}'));
-});
-
-test('release packaging stages generated launcher as an app resource', () => {
-  assert.ok(
-    packageJson.build?.extraResources?.some(
-      (resource) =>
-        resource.from === 'dist/launcher/subminer' && resource.to === 'launcher/subminer',
-    ),
+test('release packaging stages only the generated launcher runtime artifacts', () => {
+  const launcherResource = packageJson.build?.extraResources?.find(
+    (resource) => resource.from === 'dist/launcher' && resource.to === 'launcher',
   );
+  assert.deepEqual(launcherResource?.filter, [
+    'subminer',
+    'subminer.cmd',
+    'subminer.js',
+    'prepare.cjs',
+    'version',
+  ]);
   assert.match(packageJson.scripts.build ?? '', /bun run build:launcher/);
-  assert.match(packageJson.scripts['build:launcher'] ?? '', /--banner='#!\/usr\/bin\/env bun'/);
+  assert.equal(packageJson.scripts['build:launcher'], 'bun run scripts/build-launcher.ts');
+  assert.match(buildLauncher, /banner: '#!\/usr\/bin\/env bun'/);
+  assert.match(buildLauncher, /posixLauncherBootstrapContent\(\)/);
+  assert.match(buildLauncher, /windowsLauncherBootstrapContent\(\)/);
 });
 
 test('release packaging does not reference removed Windows window helper script', () => {
@@ -222,12 +213,12 @@ test('config example generation runs directly from source without unrelated bund
 });
 
 test('windows release workflow publishes unsigned artifacts directly without SignPath', () => {
-  assert.match(releaseWorkflow, /Build unsigned Windows artifacts/);
-  assert.match(releaseWorkflow, /run: bun run build:win:unsigned/);
-  assert.match(releaseWorkflow, /name: windows/);
-  assert.match(releaseWorkflow, /path: \|\n\s+release\/\*\.exe\n\s+release\/\*\.zip/);
-  assert.ok(!releaseWorkflow.includes('signpath/github-action-submit-signing-request'));
-  assert.ok(!releaseWorkflow.includes('SIGNPATH_'));
+  assert.match(packageWorkflow, /Build unsigned Windows artifacts/);
+  assert.match(packageWorkflow, /run: bun run build:win:unsigned/);
+  assert.match(packageWorkflow, /name: windows/);
+  assert.match(packageWorkflow, /path: \|\n\s+release\/\*\.exe\n\s+release\/\*\.zip/);
+  assert.ok(!packageWorkflow.includes('signpath/github-action-submit-signing-request'));
+  assert.ok(!packageWorkflow.includes('SIGNPATH_'));
 });
 
 test('release artifact names are distinct before upload', () => {
@@ -249,7 +240,7 @@ test('release workflow publishes subminer-bin to AUR from tagged release artifac
     releaseWorkflow,
     /cp packaging\/aur\/subminer-bin\/\.SRCINFO aur-subminer-bin\/\.SRCINFO/,
   );
-  assert.match(releaseWorkflow, /version_no_v="\$\{\{ steps\.version\.outputs\.VERSION \}\}"/);
+  assert.match(releaseWorkflow, /version_no_v="\$RELEASE_VERSION"/);
   assert.match(releaseWorkflow, /SubMiner-\$\{version_no_v\}\.AppImage/);
   assert.doesNotMatch(
     releaseWorkflow,
@@ -278,3 +269,31 @@ test('Makefile uninstall targets remove bundled runtime plugin app-data copies',
   assert.match(makefile, /Removed:[\s\S]*\$\(LINUX_DATA_DIR\)\/plugin\/subminer/);
   assert.match(makefile, /Removed:[\s\S]*\$\(MACOS_DATA_DIR\)\/plugin\/subminer/);
 });
+
+test('release and docs workflows keep tag-derived values out of shell bodies', () => {
+  assert.deepEqual(templateExpressionsInRunBodies(parsedReleaseWorkflow), []);
+  assert.deepEqual(templateExpressionsInRunBodies(parsedDocsPagesWorkflow), []);
+  assert.deepEqual(stepsMissingEnvDeclaration(parsedReleaseWorkflow, 'RELEASE_VERSION'), []);
+  assert.deepEqual(stepsMissingEnvDeclaration(parsedDocsPagesWorkflow, 'TAG_NAME'), []);
+
+  // The docs tag guard must test the shell variable, not an interpolated value
+  // that would be substituted into the condition before the shell reads it.
+  assert.match(docsPagesWorkflow, /if \[\[ ! "\$TAG_NAME" =~/);
+});
+
+test('stable and prerelease builds use the same packaging gate', () => {
+  const prerelease = readFileSync(
+    resolve(__dirname, '../.github/workflows/prerelease.yml'),
+    'utf8',
+  );
+  for (const workflow of [releaseWorkflow, prerelease]) {
+    assert.match(workflow, /uses: \.\/\.github\/workflows\/package-release\.yml/);
+    assert.match(workflow, /needs: \[package\]/);
+  }
+  assert.deepEqual(
+    templateExpressionsInRunBodies(
+      readWorkflow(resolve(__dirname, '../.github/workflows/package-release.yml')),
+    ),
+    [],
+  );
+});
diff --git a/src/renderer/controller-interaction-blocking.ts b/src/renderer/controller-interaction-blocking.ts
index 55e2fd77..02b6b425 100644
--- a/src/renderer/controller-interaction-blocking.ts
+++ b/src/renderer/controller-interaction-blocking.ts
@@ -4,7 +4,9 @@ type ControllerInteractionModalState = {
   jimakuModalOpen: boolean;
   kikuModalOpen: boolean;
   runtimeOptionsModalOpen: boolean;
+  subtitleSelectionModalOpen?: boolean;
   subsyncModalOpen: boolean;
+  subtitleGenerationModalOpen?: boolean;
   youtubePickerModalOpen: boolean;
   sessionHelpModalOpen: boolean;
   subtitleSidebarModalOpen: boolean;
@@ -17,7 +19,9 @@ export function isControllerInteractionBlocked(state: ControllerInteractionModal
     state.jimakuModalOpen ||
     state.kikuModalOpen ||
     state.runtimeOptionsModalOpen ||
+    state.subtitleSelectionModalOpen ||
     state.subsyncModalOpen ||
+    Boolean(state.subtitleGenerationModalOpen) ||
     state.youtubePickerModalOpen ||
     state.sessionHelpModalOpen
   );
diff --git a/src/renderer/handlers/keyboard.test.ts b/src/renderer/handlers/keyboard.test.ts
index 0e79ed19..a8dfcb5d 100644
--- a/src/renderer/handlers/keyboard.test.ts
+++ b/src/renderer/handlers/keyboard.test.ts
@@ -6,6 +6,7 @@ import test from 'node:test';
 import { createKeyboardHandlers } from './keyboard.js';
 import { createRendererState } from '../state.js';
 import type { CompiledSessionBinding } from '../../types';
+import type { MpvInputBindingsSnapshot } from '../../types/session-bindings';
 import { DEFAULT_KEYBINDINGS, SPECIAL_COMMANDS } from '../../config/definitions';
 import { compileSessionBindings } from '../../core/services/session-bindings';
 import type { ConfiguredShortcuts } from '../../core/utils/shortcut-config';
@@ -91,6 +92,8 @@ function createEmptyShortcuts(): ConfiguredShortcuts {
     openRuntimeOptions: null,
     openJimaku: null,
     openTsukihime: null,
+    openSubtitleSelection: null,
+    openSubtitleGeneration: null,
     openSessionHelp: null,
     openControllerSelect: null,
     openControllerDebug: null,
@@ -115,6 +118,10 @@ function installKeyboardTestGlobals() {
   const sessionActions: Array<{ actionId: string; payload?: unknown }> = [];
   const interactionActivations: string[] = [];
   let sessionBindings: CompiledSessionBinding[] = [];
+  let getMpvInputBindings: () => Promise<MpvInputBindingsSnapshot> = async () => ({
+    keys: [],
+    blockedKeys: [],
+  });
   let getSessionBindingsImpl: () => Promise<CompiledSessionBinding[]> = async () => sessionBindings;
   let playbackPausedResponse: boolean | null = false;
   let statsToggleKey = 'Backquote';
@@ -238,6 +245,7 @@ function installKeyboardTestGlobals() {
       },
       electronAPI: {
         getKeybindings: async () => [],
+        getMpvInputBindings: () => getMpvInputBindings(),
         getSessionBindings: () => getSessionBindingsImpl(),
         getConfiguredShortcuts: async () => configuredShortcuts,
         sendMpvCommand: (command: Array<string | number>) => {
@@ -308,6 +316,7 @@ function installKeyboardTestGlobals() {
     altKey?: boolean;
     shiftKey?: boolean;
     repeat?: boolean;
+    target?: unknown;
   }): void {
     const listeners = documentListeners.get('keydown') ?? [];
     const keyboardEvent = {
@@ -319,7 +328,7 @@ function installKeyboardTestGlobals() {
       shiftKey: event.shiftKey ?? false,
       repeat: event.repeat ?? false,
       preventDefault: () => {},
-      target: null,
+      target: event.target ?? null,
     };
     for (const listener of listeners) {
       listener(keyboardEvent);
@@ -369,6 +378,7 @@ function installKeyboardTestGlobals() {
   }
 
   function restore() {
+    dispatchWindowEvent('beforeunload');
     Object.defineProperty(globalThis, 'window', { configurable: true, value: previousWindow });
     Object.defineProperty(globalThis, 'document', { configurable: true, value: previousDocument });
     Object.defineProperty(globalThis, 'MutationObserver', {
@@ -421,6 +431,9 @@ function installKeyboardTestGlobals() {
     setConfiguredShortcuts: (value: typeof configuredShortcuts) => {
       configuredShortcuts = value;
     },
+    setGetMpvInputBindings: (value: typeof getMpvInputBindings) => {
+      getMpvInputBindings = value;
+    },
     setSessionBindings: (value: CompiledSessionBinding[]) => {
       sessionBindings = value;
     },
@@ -452,6 +465,7 @@ function createKeyboardHandlerHarness() {
   const testGlobals = installKeyboardTestGlobals();
   const subtitleRootClassList = createClassList();
   const subtitleContainerClassList = createClassList();
+  let mediaTimingReviewKeydownCount = 0;
   let controllerSelectKeydownCount = 0;
   let openControllerSelectCount = 0;
   let openControllerDebugCount = 0;
@@ -494,6 +508,10 @@ function createKeyboardHandlerHarness() {
     handleKikuKeydown: () => false,
     handleJimakuKeydown: () => false,
     handleTsukihimeKeydown: () => false,
+    handleMediaTimingReviewKeydown: () => {
+      mediaTimingReviewKeydownCount += 1;
+      return false;
+    },
     handleControllerSelectKeydown: () => {
       controllerSelectKeydownCount += 1;
       return true;
@@ -523,6 +541,7 @@ function createKeyboardHandlerHarness() {
     ctx,
     handlers,
     testGlobals,
+    mediaTimingReviewKeydownCount: () => mediaTimingReviewKeydownCount,
     controllerSelectKeydownCount: () => controllerSelectKeydownCount,
     openControllerSelectCount: () => openControllerSelectCount,
     openControllerDebugCount: () => openControllerDebugCount,
@@ -1367,6 +1386,29 @@ test('keyboard mode: controller select modal handles arrow keys before yomitan p
   }
 });
 
+test('media timing review modal handles keys before later modal handlers', async () => {
+  const {
+    ctx,
+    testGlobals,
+    handlers,
+    mediaTimingReviewKeydownCount,
+    controllerSelectKeydownCount,
+  } = createKeyboardHandlerHarness();
+
+  try {
+    await handlers.setupMpvInputForwarding();
+    ctx.state.mediaTimingReviewModalOpen = true;
+    ctx.state.controllerSelectModalOpen = true;
+
+    testGlobals.dispatchKeydown({ key: 'ArrowDown', code: 'ArrowDown' });
+
+    assert.equal(mediaTimingReviewKeydownCount(), 1);
+    assert.equal(controllerSelectKeydownCount(), 0);
+  } finally {
+    testGlobals.restore();
+  }
+});
+
 test('keyboard mode: playlist browser modal handles arrow keys before yomitan popup', async () => {
   const { ctx, testGlobals, handlers, playlistBrowserKeydownCount } =
     createKeyboardHandlerHarness();
@@ -1551,6 +1593,28 @@ test('session binding: Ctrl+Alt+S dispatches subsync action locally', async () =
   }
 });
 
+test('session binding: Ctrl+Shift+G dispatches subtitle generation with the sidebar closed', async () => {
+  const { handlers, testGlobals } = createKeyboardHandlerHarness();
+  try {
+    await handlers.setupMpvInputForwarding();
+    handlers.updateSessionBindings([
+      {
+        sourcePath: 'shortcuts.openSubtitleGeneration',
+        originalKey: 'Ctrl+Shift+G',
+        key: { code: 'KeyG', modifiers: ['ctrl', 'shift'] },
+        actionType: 'session-action',
+        actionId: 'openSubtitleGeneration',
+      },
+    ]);
+    testGlobals.dispatchKeydown({ key: 'G', code: 'KeyG', ctrlKey: true, shiftKey: true });
+    assert.deepEqual(testGlobals.sessionActions, [
+      { actionId: 'openSubtitleGeneration', payload: undefined },
+    ]);
+  } finally {
+    testGlobals.restore();
+  }
+});
+
 test('session binding: Ctrl+Shift+J dispatches jimaku action locally', async () => {
   const { handlers, testGlobals } = createKeyboardHandlerHarness();
 
@@ -1834,6 +1898,29 @@ test('keyboard mode: popup hidden after mode off clears stale selected token hig
   }
 });
 
+test('Yomitan popup dismissal and subtitle updates preserve selection outside the overlay subtitle', async () => {
+  const { ctx, handlers, testGlobals } = createKeyboardHandlerHarness();
+  let cleared = false;
+  try {
+    Object.defineProperty(window, 'getSelection', {
+      configurable: true,
+      value: () => ({
+        anchorNode: {},
+        removeAllRanges: () => {
+          cleared = true;
+        },
+      }),
+    });
+    Object.assign(ctx.dom.subtitleRoot, { contains: () => false });
+    await handlers.setupMpvInputForwarding();
+    testGlobals.dispatchWindowEvent(YOMITAN_POPUP_HIDDEN_EVENT);
+    handlers.syncKeyboardTokenSelection();
+    assert.equal(cleared, false);
+  } finally {
+    testGlobals.restore();
+  }
+});
+
 test('keyboard mode: closing lookup keeps controller selection but clears native text selection', async () => {
   const { ctx, handlers, testGlobals } = createKeyboardHandlerHarness();
 
@@ -2255,3 +2342,149 @@ test('mark-watched keybinding does not send mpv commands when no active session'
     testGlobals.restore();
   }
 });
+
+test('discovered mpv keys only run after SubMiner controls and stay out of session help', async () => {
+  const { handlers, testGlobals, ctx } = createKeyboardHandlerHarness();
+  try {
+    testGlobals.setGetMpvInputBindings(async () => ({
+      keys: ['r', 'SPACE', 'y', 'v'],
+      blockedKeys: [],
+    }));
+    testGlobals.setSessionBindings([
+      {
+        sourcePath: 'keybindings[0].key',
+        originalKey: 'Space',
+        key: { code: 'Space', modifiers: [] },
+        actionType: 'mpv-command',
+        command: ['cycle', 'pause'],
+      },
+    ]);
+    await handlers.setupMpvInputForwarding();
+    await wait(0);
+    testGlobals.dispatchKeydown({ key: 'r', code: 'KeyR' });
+    testGlobals.dispatchKeydown({ key: ' ', code: 'Space' });
+    assert.deepEqual(testGlobals.mpvCommands, [
+      ['keydown', 'r'],
+      ['cycle', 'pause'],
+    ]);
+    assert.equal(ctx.state.sessionBindings.length, 1);
+    testGlobals.dispatchWindowEvent('blur');
+    const before = testGlobals.mpvCommands.length;
+    ctx.state.playlistBrowserModalOpen = true;
+    testGlobals.dispatchKeydown({ key: 'r', code: 'KeyR' });
+    ctx.state.playlistBrowserModalOpen = false;
+    ctx.state.yomitanPopupVisible = true;
+    testGlobals.setPopupVisible(true);
+    testGlobals.dispatchKeydown({ key: 'r', code: 'KeyR' });
+    ctx.state.yomitanPopupVisible = false;
+    testGlobals.setPopupVisible(false);
+    testGlobals.dispatchKeydown({ key: 'r', code: 'KeyR', target: { closest: () => ({}) } });
+    assert.equal(testGlobals.mpvCommands.length, before);
+  } finally {
+    testGlobals.restore();
+  }
+});
+
+test('stalled mpv discovery does not delay configured overlay controls', async () => {
+  const { handlers, testGlobals } = createKeyboardHandlerHarness();
+  try {
+    testGlobals.setGetMpvInputBindings(() => new Promise(() => {}));
+    testGlobals.setSessionBindings([
+      {
+        sourcePath: 'keybindings[0].key',
+        originalKey: 'Space',
+        key: { code: 'Space', modifiers: [] },
+        actionType: 'mpv-command',
+        command: ['cycle', 'pause'],
+      },
+    ]);
+    await handlers.setupMpvInputForwarding();
+    testGlobals.dispatchKeydown({ key: ' ', code: 'Space' });
+    assert.deepEqual(testGlobals.mpvCommands, [['cycle', 'pause']]);
+  } finally {
+    testGlobals.restore();
+  }
+});
+
+test('session binding: g-s opens subtitle selection only after the complete sequence', async () => {
+  const { handlers, testGlobals } = createKeyboardHandlerHarness();
+  try {
+    await handlers.setupMpvInputForwarding();
+    handlers.updateSessionBindings([
+      {
+        sourcePath: 'shortcuts.openSubtitleSelection',
+        originalKey: 'g-s',
+        key: { code: 'KeyG-KeyS', modifiers: [] },
+        actionType: 'session-action',
+        actionId: 'openSubtitleSelection',
+      },
+    ]);
+    testGlobals.dispatchKeydown({ key: 's', code: 'KeyS' });
+    testGlobals.dispatchKeydown({ key: 'g', code: 'KeyG' });
+    assert.deepEqual(testGlobals.sessionActions, []);
+    testGlobals.dispatchKeydown({ key: 's', code: 'KeyS' });
+    assert.deepEqual(testGlobals.sessionActions, [
+      { actionId: 'openSubtitleSelection', payload: undefined },
+    ]);
+    testGlobals.dispatchKeydown({ key: 'g', code: 'KeyG' });
+    handlers.updateSessionBindings([]);
+    testGlobals.dispatchKeydown({ key: 's', code: 'KeyS' });
+    assert.equal(testGlobals.sessionActions.length, 1);
+  } finally {
+    testGlobals.restore();
+  }
+});
+
+test('single-key actions run immediately even if a conflicting sequence reaches the renderer', async () => {
+  const { handlers, testGlobals } = createKeyboardHandlerHarness();
+  try {
+    await handlers.setupMpvInputForwarding();
+    handlers.updateSessionBindings([
+      {
+        sourcePath: 'sequence',
+        originalKey: 'g-s',
+        key: { code: 'KeyG-KeyS', modifiers: [] },
+        actionType: 'session-action',
+        actionId: 'openSubtitleSelection',
+      },
+      {
+        sourcePath: 'single',
+        originalKey: 'g',
+        key: { code: 'KeyG', modifiers: [] },
+        actionType: 'mpv-command',
+        command: ['show-text', 'single'],
+      },
+    ]);
+    testGlobals.dispatchKeydown({ key: 'g', code: 'KeyG' });
+    assert.deepEqual(testGlobals.mpvCommands, [['show-text', 'single']]);
+    testGlobals.dispatchKeydown({ key: 's', code: 'KeyS' });
+    assert.deepEqual(testGlobals.sessionActions, []);
+  } finally {
+    testGlobals.restore();
+  }
+});
+
+test('an unfinished built-in y chord cannot start a configured sequence', async () => {
+  const { handlers, testGlobals } = createKeyboardHandlerHarness();
+  try {
+    await handlers.setupMpvInputForwarding();
+    handlers.updateSessionBindings([
+      {
+        sourcePath: 'sequence',
+        originalKey: 'g-s',
+        key: { code: 'KeyG-KeyS', modifiers: [] },
+        actionType: 'session-action',
+        actionId: 'openSubtitleSelection',
+      },
+    ]);
+    testGlobals.dispatchKeydown({ key: 'y', code: 'KeyY' });
+    testGlobals.dispatchKeydown({ key: 'g', code: 'KeyG' });
+    testGlobals.dispatchKeydown({ key: 's', code: 'KeyS' });
+    assert.deepEqual(testGlobals.sessionActions, []);
+    testGlobals.dispatchKeydown({ key: 'g', code: 'KeyG' });
+    testGlobals.dispatchKeydown({ key: 's', code: 'KeyS' });
+    assert.equal(testGlobals.sessionActions.length, 1);
+  } finally {
+    testGlobals.restore();
+  }
+});
diff --git a/src/renderer/handlers/keyboard.ts b/src/renderer/handlers/keyboard.ts
index 04f63381..68db6a1f 100644
--- a/src/renderer/handlers/keyboard.ts
+++ b/src/renderer/handlers/keyboard.ts
@@ -1,5 +1,6 @@
 import type { CompiledSessionBinding, PrimarySubMode, ShortcutsConfig } from '../../types';
 import type { RendererContext } from '../context';
+import { createMpvInputForwarding } from './mpv-input-forwarding';
 import {
   YOMITAN_POPUP_HIDDEN_EVENT,
   YOMITAN_POPUP_SHOWN_EVENT,
@@ -14,10 +15,13 @@ export function createKeyboardHandlers(
     handleRuntimeOptionsKeydown: (e: KeyboardEvent) => boolean;
     handleCharacterDictionaryKeydown: (e: KeyboardEvent) => boolean;
     handleSubsyncKeydown: (e: KeyboardEvent) => boolean;
+    handleSubtitleSelectionKeydown?: (e: KeyboardEvent) => boolean;
+    handleSubtitleGenerationKeydown?: (e: KeyboardEvent) => boolean;
     handleKikuKeydown: (e: KeyboardEvent) => boolean;
     handleJimakuKeydown: (e: KeyboardEvent) => boolean;
     handleTsukihimeKeydown: (e: KeyboardEvent) => boolean;
     handleYoutubePickerKeydown: (e: KeyboardEvent) => boolean;
+    handleMediaTimingReviewKeydown: (e: KeyboardEvent) => boolean;
     handlePlaylistBrowserKeydown: (e: KeyboardEvent) => boolean;
     handleControllerSelectKeydown: (e: KeyboardEvent) => boolean;
     handleControllerDebugKeydown: (e: KeyboardEvent) => boolean;
@@ -54,6 +58,11 @@ export function createKeyboardHandlers(
     timeout: ReturnType<typeof setTimeout> | null;
   } | null = null;
   let mpvInputForwardingListenersInstalled = false;
+  let keyboardConfigLoaded = false;
+  const importedMpvBindings = createMpvInputForwarding({
+    load: () => window.electronAPI.getMpvInputBindings(),
+    send: (command) => window.electronAPI.sendMpvCommand(command),
+  });
 
   const CHORD_MAP = new Map<
     string,
@@ -125,11 +134,15 @@ export function createKeyboardHandlers(
     updateConfiguredShortcuts(shortcuts, statsToggleKey, markWatchedKey);
   }
 
+  let pendingSequence: { prefix: string; expires: number } | null = null;
+
   function updateSessionBindings(bindings: CompiledSessionBinding[]): void {
+    pendingSequence = null;
     ctx.state.sessionBindings = bindings;
     ctx.state.sessionBindingMap = new Map(
       bindings.map((binding) => [keyEventToStringFromBinding(binding), binding]),
     );
+    void importedMpvBindings.refresh();
   }
 
   function keyEventToStringFromBinding(binding: CompiledSessionBinding): string {
@@ -435,7 +448,10 @@ export function createKeyboardHandlers(
   }
 
   function clearNativeSubtitleSelection(): void {
-    window.getSelection()?.removeAllRanges();
+    const selection = window.getSelection();
+    if (!selection?.anchorNode || ctx.dom.subtitleRoot.contains(selection.anchorNode)) {
+      selection?.removeAllRanges();
+    }
     ctx.dom.subtitleRoot.classList.remove('has-selection');
   }
 
@@ -980,6 +996,7 @@ export function createKeyboardHandlers(
     ]);
     updateSessionBindings(sessionBindings);
     updateConfiguredShortcuts(shortcuts, statsToggleKey, markWatchedKey);
+    keyboardConfigLoaded = true;
     syncKeyboardTokenSelection();
   }
 
@@ -1030,6 +1047,21 @@ export function createKeyboardHandlers(
       return;
     }
     mpvInputForwardingListenersInstalled = true;
+    const lateScriptRefresh = setTimeout(() => {
+      void importedMpvBindings.refresh();
+    }, 1500);
+    window.addEventListener('focus', () => {
+      void importedMpvBindings.refresh();
+    });
+    window.addEventListener('blur', () => {
+      pendingSequence = null;
+      importedMpvBindings.releaseAll();
+    });
+    window.addEventListener('beforeunload', () => {
+      clearTimeout(lateScriptRefresh);
+      importedMpvBindings.dispose();
+    });
+    document.addEventListener('keyup', importedMpvBindings.keyup, true);
 
     const subtitleMutationObserver = new MutationObserver(() => {
       syncKeyboardTokenSelection();
@@ -1078,6 +1110,23 @@ export function createKeyboardHandlers(
     );
 
     document.addEventListener('keydown', (e: KeyboardEvent) => {
+      const sequence = pendingSequence;
+      pendingSequence = null;
+      if (ctx.state.subtitleSelectionModalOpen) {
+        pendingSequence = null;
+        options.handleSubtitleSelectionKeydown?.(e);
+        return;
+      }
+      if (ctx.state.subtitleGenerationModalOpen) {
+        options.handleSubtitleGenerationKeydown?.(e);
+        return;
+      }
+
+      if (ctx.state.mediaTimingReviewModalOpen) {
+        options.handleMediaTimingReviewKeydown(e);
+        return;
+      }
+
       if (isKeyboardDrivenModeToggle(e) && ctx.platform.isModalLayer) {
         e.preventDefault();
         handleKeyboardModeToggleRequested();
@@ -1152,6 +1201,7 @@ export function createKeyboardHandlers(
       }
 
       if (isTextEntryTarget(e.target)) {
+        pendingSequence = null;
         return;
       }
 
@@ -1159,6 +1209,16 @@ export function createKeyboardHandlers(
         return;
       }
 
+      const sequenceKey = keyEventToString(e);
+      if (sequence && !ctx.state.chordPending && Date.now() <= sequence.expires && !e.repeat) {
+        const binding = ctx.state.sessionBindingMap.get(`${sequence.prefix}-${sequenceKey}`);
+        if (binding) {
+          e.preventDefault();
+          dispatchSessionBinding(binding);
+          return;
+        }
+      }
+
       if (isStatsOverlayToggle(e)) {
         e.preventDefault();
         window.electronAPI.toggleStatsOverlay();
@@ -1239,7 +1299,28 @@ export function createKeyboardHandlers(
       if (binding) {
         e.preventDefault();
         dispatchSessionBinding(binding);
+        return;
       }
+      if (
+        !e.repeat &&
+        ctx.state.sessionBindings.some((binding) =>
+          keyEventToStringFromBinding(binding).startsWith(`${sequenceKey}-`),
+        )
+      ) {
+        pendingSequence = { prefix: sequenceKey, expires: Date.now() + 1000 };
+        e.preventDefault();
+        return;
+      }
+      if (
+        keyboardConfigLoaded &&
+        !ctx.state.playlistBrowserModalOpen &&
+        !ctx.state.youtubePickerModalOpen &&
+        !ctx.state.subtitleSidebarModalOpen &&
+        !ctx.state.yomitanPopupVisible &&
+        !isYomitanPopupVisible(document) &&
+        !isInteractiveTarget(e.target)
+      )
+        importedMpvBindings.keydown(e);
     });
 
     document.addEventListener('mousedown', (e: MouseEvent) => {
diff --git a/src/renderer/handlers/mpv-input-forwarding.test.ts b/src/renderer/handlers/mpv-input-forwarding.test.ts
new file mode 100644
index 00000000..919da743
--- /dev/null
+++ b/src/renderer/handlers/mpv-input-forwarding.test.ts
@@ -0,0 +1,112 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { createMpvInputForwarding } from './mpv-input-forwarding';
+import type { MpvInputBindingsSnapshot } from '../../types/session-bindings';
+
+function keyEvent(
+  overrides: Partial<Parameters<ReturnType<typeof createMpvInputForwarding>['keydown']>[0]> = {},
+) {
+  return {
+    key: 'r',
+    code: 'KeyR',
+    ctrlKey: false,
+    altKey: false,
+    shiftKey: false,
+    metaKey: false,
+    repeat: false,
+    defaultPrevented: false,
+    isComposing: false,
+    getModifierState: () => false,
+    preventDefault: () => {},
+    ...overrides,
+  };
+}
+
+test('forwarded keys use mpv repeat and retain the pressed key through modifier changes', async () => {
+  const commands: (string | number)[][] = [];
+  const forwarding = createMpvInputForwarding({
+    load: async () => ({ keys: ['r', 'ctrl+A'], blockedKeys: [] }),
+    send: (command) => commands.push(command),
+  });
+  await forwarding.refresh();
+  assert.equal(forwarding.keydown(keyEvent()), true);
+  assert.equal(forwarding.keydown(keyEvent({ repeat: true })), true);
+  forwarding.keyup(keyEvent());
+  forwarding.keydown(keyEvent({ key: 'A', code: 'KeyA', ctrlKey: true, shiftKey: true }));
+  forwarding.keyup(keyEvent({ key: 'a', code: 'KeyA' }));
+  assert.deepEqual(commands, [
+    ['keydown', 'r'],
+    ['keyup', 'r'],
+    ['keydown', 'ctrl+A'],
+    ['keyup', 'ctrl+A'],
+  ]);
+});
+
+test('configured and disabled keys, handled input, and unknown keys are not forwarded', async () => {
+  const commands: (string | number)[][] = [];
+  const forwarding = createMpvInputForwarding({
+    load: async () => ({ keys: ['r', 't', '1'], blockedKeys: [{ code: 'KeyR', modifiers: [] }] }),
+    send: (command) => commands.push(command),
+  });
+  await forwarding.refresh();
+  assert.equal(forwarding.keydown(keyEvent()), false);
+  assert.equal(
+    forwarding.keydown(keyEvent({ key: 't', code: 'KeyT', defaultPrevented: true })),
+    false,
+  );
+  assert.equal(forwarding.keydown(keyEvent({ key: 'z', code: 'KeyZ' })), false);
+  assert.equal(forwarding.keydown(keyEvent({ key: '1', code: 'Numpad1' })), false);
+  assert.deepEqual(commands, []);
+});
+
+test('refresh discards stale responses and coalesces concurrent requests', async () => {
+  let resolveFirst: (snapshot: MpvInputBindingsSnapshot) => void = () => {};
+  let requests = 0;
+  const forwarding = createMpvInputForwarding({
+    load: () => {
+      requests += 1;
+      if (requests === 1)
+        return new Promise((resolve) => {
+          resolveFirst = resolve;
+        });
+      return Promise.resolve({ keys: ['t'], blockedKeys: [] });
+    },
+    send: () => {},
+  });
+  const first = forwarding.refresh();
+  const second = forwarding.refresh();
+  forwarding.refresh();
+  assert.equal(requests, 1);
+  resolveFirst({ keys: ['r'], blockedKeys: [] });
+  await Promise.all([first, second]);
+  assert.equal(requests, 2);
+  assert.equal(forwarding.keydown(keyEvent()), false);
+  assert.equal(forwarding.keydown(keyEvent({ key: 't', code: 'KeyT' })), true);
+});
+
+test('focus loss releases held keys and failed refresh clears stale bindings', async () => {
+  let fail = false;
+  const commands: (string | number)[][] = [];
+  const forwarding = createMpvInputForwarding({
+    load: async () => {
+      if (fail) throw new Error('disconnected');
+      return { keys: ['r'], blockedKeys: [] };
+    },
+    send: (command) => commands.push(command),
+  });
+  await forwarding.refresh();
+  forwarding.keydown(keyEvent());
+  forwarding.releaseAll();
+  forwarding.keyup(keyEvent());
+  assert.deepEqual(commands, [
+    ['keydown', 'r'],
+    ['keyup', 'r'],
+  ]);
+  fail = true;
+  await forwarding.refresh();
+  assert.equal(forwarding.keydown(keyEvent()), false);
+  forwarding.dispose();
+  fail = false;
+  await forwarding.refresh();
+  assert.equal(forwarding.keydown(keyEvent()), false);
+});
diff --git a/src/renderer/handlers/mpv-input-forwarding.ts b/src/renderer/handlers/mpv-input-forwarding.ts
new file mode 100644
index 00000000..53cca512
--- /dev/null
+++ b/src/renderer/handlers/mpv-input-forwarding.ts
@@ -0,0 +1,91 @@
+import { keyboardEventToMpvKey } from '../../shared/mpv-input-bindings';
+import type { MpvInputBindingsSnapshot } from '../../types/session-bindings';
+
+type ForwardedKeyEvent = Parameters<typeof keyboardEventToMpvKey>[0] &
+  Pick<KeyboardEvent, 'code' | 'repeat' | 'defaultPrevented' | 'preventDefault'>;
+
+export function createMpvInputForwarding(deps: {
+  load: () => Promise<MpvInputBindingsSnapshot>;
+  send: (command: (string | number)[]) => void;
+}) {
+  let keys = new Set<string>();
+  let blockedKeys: MpvInputBindingsSnapshot['blockedKeys'] = [];
+  const heldKeys = new Map<string, string>();
+  let generation = 0;
+  let disposed = false;
+  let pending: Promise<void> | null = null;
+
+  function releaseAll(): void {
+    for (const key of heldKeys.values()) deps.send(['keyup', key]);
+    heldKeys.clear();
+  }
+
+  function refresh(): Promise<void> {
+    if (disposed) return Promise.resolve();
+    generation += 1;
+    keys.clear();
+    blockedKeys = [];
+    releaseAll();
+    if (pending) return pending;
+    pending = (async () => {
+      let requestedGeneration: number;
+      do {
+        requestedGeneration = generation;
+        try {
+          const snapshot = await deps.load();
+          if (!disposed && requestedGeneration === generation) {
+            keys = new Set(snapshot.keys);
+            blockedKeys = snapshot.blockedKeys;
+          }
+        } catch {
+          // Discovery is optional. Keep the existing overlay controls available.
+        }
+      } while (!disposed && requestedGeneration !== generation);
+    })().finally(() => {
+      pending = null;
+    });
+    return pending;
+  }
+
+  function keydown(event: ForwardedKeyEvent): boolean {
+    if (disposed || event.defaultPrevented) return false;
+    if (heldKeys.has(event.code)) {
+      event.preventDefault();
+      return true;
+    }
+    if (event.repeat || event.code.startsWith('Numpad')) return false;
+    if (
+      blockedKeys.some(
+        ({ code, modifiers }) =>
+          code === event.code &&
+          modifiers.includes('ctrl') === event.ctrlKey &&
+          modifiers.includes('alt') === event.altKey &&
+          modifiers.includes('shift') === event.shiftKey &&
+          modifiers.includes('meta') === event.metaKey,
+      )
+    )
+      return false;
+    const key = keyboardEventToMpvKey(event);
+    if (!key || !keys.has(key)) return false;
+    heldKeys.set(event.code, key);
+    deps.send(['keydown', key]);
+    event.preventDefault();
+    return true;
+  }
+
+  function keyup(event: Pick<KeyboardEvent, 'code' | 'preventDefault'>): void {
+    const key = heldKeys.get(event.code);
+    if (!key) return;
+    heldKeys.delete(event.code);
+    deps.send(['keyup', key]);
+    event.preventDefault();
+  }
+
+  function dispose(): void {
+    disposed = true;
+    keys.clear();
+    releaseAll();
+  }
+
+  return { refresh, keydown, keyup, releaseAll, dispose };
+}
diff --git a/src/renderer/index.html b/src/renderer/index.html
index 49c09027..4ec0f0f3 100644
--- a/src/renderer/index.html
+++ b/src/renderer/index.html
@@ -86,10 +86,30 @@
             <button id="jimakuClose" class="modal-close" type="button">Close</button>
           </div>
           <div class="modal-body">
+            <div class="jimaku-tabs" role="tablist">
+              <button
+                id="jimakuTabAnime"
+                class="jimaku-tab active"
+                type="button"
+                role="tab"
+                aria-selected="true"
+              >
+                Anime
+              </button>
+              <button
+                id="jimakuTabLiveAction"
+                class="jimaku-tab"
+                type="button"
+                role="tab"
+                aria-selected="false"
+              >
+                Live action
+              </button>
+            </div>
             <div class="jimaku-form">
               <label class="jimaku-field">
                 <span>Title</span>
-                <input id="jimakuTitle" type="text" placeholder="Anime title" />
+                <input id="jimakuTitle" type="text" placeholder="Title" />
               </label>
               <label class="jimaku-field">
                 <span>Season</span>
@@ -196,6 +216,351 @@
           </div>
         </div>
       </div>
+      <div
+        id="mediaTimingReviewModal"
+        class="modal media-timing-review-modal hidden"
+        aria-hidden="true"
+      >
+        <div
+          class="modal-content media-timing-review-content"
+          role="dialog"
+          aria-modal="true"
+          aria-labelledby="mediaTimingReviewTitle"
+        >
+          <div class="media-timing-review-header">
+            <div class="media-timing-review-heading">
+              <div id="mediaTimingReviewTitle" class="media-timing-review-title">
+                Review media timing
+              </div>
+              <div id="mediaTimingReviewKind" class="media-timing-review-kind">Sentence card</div>
+            </div>
+            <button
+              id="mediaTimingReviewCancel"
+              class="media-timing-review-quiet-button"
+              type="button"
+            >
+              Cancel
+            </button>
+          </div>
+
+          <div id="mediaTimingReviewEditor" class="media-timing-review-editor">
+            <div class="media-timing-review-sentence-header">
+              <div class="media-timing-review-sentence-heading">
+                <span class="media-timing-review-sentence-label">Sentence on card</span>
+                <span id="mediaTimingReviewLineCount" class="media-timing-review-line-count">
+                  1 line
+                </span>
+              </div>
+              <div
+                id="mediaTimingReviewLineControls"
+                class="media-timing-review-line-controls hidden"
+              >
+                <div class="media-timing-review-line-stepper">
+                  <span>Prev</span>
+                  <button
+                    id="mediaTimingReviewPrevRemove"
+                    type="button"
+                    aria-label="Remove the earliest added previous subtitle line from the card sentence"
+                    title="Remove the earliest previous line (Shift+P)"
+                  >
+                    &minus;
+                  </button>
+                  <button
+                    id="mediaTimingReviewPrevAdd"
+                    type="button"
+                    aria-label="Add the previous subtitle line to the card sentence"
+                    title="Add the previous line (P)"
+                  >
+                    +
+                  </button>
+                </div>
+                <div class="media-timing-review-line-stepper">
+                  <span>Next</span>
+                  <button
+                    id="mediaTimingReviewNextRemove"
+                    type="button"
+                    aria-label="Remove the latest added next subtitle line from the card sentence"
+                    title="Remove the latest next line (Shift+N)"
+                  >
+                    &minus;
+                  </button>
+                  <button
+                    id="mediaTimingReviewNextAdd"
+                    type="button"
+                    aria-label="Add the next subtitle line to the card sentence"
+                    title="Add the next line (N)"
+                  >
+                    +
+                  </button>
+                </div>
+              </div>
+            </div>
+            <blockquote id="mediaTimingReviewText" class="media-timing-review-text"></blockquote>
+
+            <div id="mediaTimingReviewFramePicker" class="media-timing-frame-picker hidden">
+              <div class="media-timing-frame-image-shell">
+                <img
+                  id="mediaTimingReviewFrameImage"
+                  class="hidden"
+                  alt="Selected card screenshot"
+                />
+              </div>
+              <div class="media-timing-frame-controls">
+                <div class="media-timing-frame-heading">
+                  <label for="mediaTimingReviewFrameSlider">Card screenshot</label>
+                  <output id="mediaTimingReviewFrameTime" for="mediaTimingReviewFrameSlider"
+                    >—</output
+                  >
+                </div>
+                <input
+                  id="mediaTimingReviewFrameSlider"
+                  type="range"
+                  min="0"
+                  max="1"
+                  step="0.001"
+                  value="0"
+                  aria-label="Screenshot time"
+                />
+                <div class="media-timing-frame-buttons">
+                  <button
+                    id="mediaTimingReviewFramePrevious"
+                    type="button"
+                    aria-label="Previous video frame"
+                  >
+                    ← Frame
+                  </button>
+                  <button
+                    id="mediaTimingReviewFrameNext"
+                    type="button"
+                    aria-label="Next video frame"
+                  >
+                    Frame →
+                  </button>
+                  <button
+                    id="mediaTimingReviewFrameReset"
+                    type="button"
+                    aria-label="Reset screenshot"
+                  >
+                    Reset
+                  </button>
+                </div>
+                <p id="mediaTimingReviewFrameStatus" role="status"></p>
+              </div>
+            </div>
+
+            <div class="media-timing-review-readout" aria-live="polite">
+              <div>
+                <span>Starts</span>
+                <strong id="mediaTimingReviewStartValue">00:00.000</strong>
+              </div>
+              <div class="media-timing-review-duration">
+                <span>Clip length</span>
+                <strong id="mediaTimingReviewDuration">0.00s</strong>
+              </div>
+              <div>
+                <span>Ends</span>
+                <strong id="mediaTimingReviewEndValue">00:00.000</strong>
+              </div>
+            </div>
+
+            <div class="media-timing-review-timeline-shell">
+              <div class="media-timing-review-timeline-labels">
+                <span id="mediaTimingReviewTimelineStart">00:00</span>
+                <span id="mediaTimingReviewWaveformLabel">speech-weighted waveform</span>
+                <span id="mediaTimingReviewTimelineEnd">00:00</span>
+              </div>
+              <div id="mediaTimingReviewSelectionTrack" class="media-timing-review-track">
+                <svg
+                  class="media-timing-review-waveform"
+                  viewBox="0 0 1000 100"
+                  preserveAspectRatio="none"
+                  aria-hidden="true"
+                >
+                  <defs>
+                    <linearGradient id="mediaTimingReviewWaveformFill" x1="0" y1="0" x2="0" y2="1">
+                      <stop class="media-timing-review-waveform-edge-stop" offset="0%" />
+                      <stop class="media-timing-review-waveform-core-stop" offset="50%" />
+                      <stop class="media-timing-review-waveform-edge-stop" offset="100%" />
+                    </linearGradient>
+                  </defs>
+                  <path id="mediaTimingReviewWaveformPath"></path>
+                </svg>
+                <div
+                  class="media-timing-review-original-range"
+                  title="Mined subtitle timing"
+                  aria-hidden="true"
+                >
+                  <span class="media-timing-review-original-boundary is-start"></span>
+                  <span class="media-timing-review-original-boundary is-end"></span>
+                </div>
+                <span class="media-timing-review-original-label is-start" aria-hidden="true">
+                  Line start
+                </span>
+                <span class="media-timing-review-original-label is-end" aria-hidden="true">
+                  Line end
+                </span>
+                <div
+                  id="mediaTimingReviewSelectedRange"
+                  class="media-timing-review-selected-range"
+                  aria-hidden="true"
+                ></div>
+                <div class="media-timing-review-playhead" aria-hidden="true"></div>
+                <div
+                  id="mediaTimingReviewStartHandle"
+                  class="media-timing-review-handle media-timing-review-handle-start"
+                  role="slider"
+                  tabindex="0"
+                  aria-label="Clip start"
+                  aria-orientation="horizontal"
+                ></div>
+                <div
+                  id="mediaTimingReviewEndHandle"
+                  class="media-timing-review-handle media-timing-review-handle-end"
+                  role="slider"
+                  tabindex="0"
+                  aria-label="Clip end"
+                  aria-orientation="horizontal"
+                ></div>
+              </div>
+              <div class="media-timing-review-expand-row">
+                <button
+                  id="mediaTimingReviewShowEarlier"
+                  class="media-timing-review-expand-button"
+                  type="button"
+                  aria-label="Show two more seconds before the visible timeline without moving the selected clip"
+                  title="Show 2 more seconds before the visible timeline. The selected clip does not move."
+                >
+                  Earlier &minus;2s
+                </button>
+                <span>Drag an edge to trim, or drag the highlighted clip to move it.</span>
+                <button
+                  id="mediaTimingReviewShowLater"
+                  class="media-timing-review-expand-button"
+                  type="button"
+                  aria-label="Show two more seconds after the visible timeline without moving the selected clip"
+                  title="Show 2 more seconds after the visible timeline. The selected clip does not move."
+                >
+                  Later +2s
+                </button>
+              </div>
+            </div>
+
+            <div class="media-timing-review-fine-grid">
+              <div class="media-timing-review-fine-control">
+                <span>Start</span>
+                <button
+                  id="mediaTimingReviewStartBack"
+                  type="button"
+                  aria-label="Move start backward 100 milliseconds"
+                >
+                  &minus;0.1s
+                </button>
+                <button
+                  id="mediaTimingReviewStartForward"
+                  type="button"
+                  aria-label="Move start forward 100 milliseconds"
+                >
+                  +0.1s
+                </button>
+              </div>
+              <div class="media-timing-review-fine-control">
+                <span>End</span>
+                <button
+                  id="mediaTimingReviewEndBack"
+                  type="button"
+                  aria-label="Move end backward 100 milliseconds"
+                >
+                  &minus;0.1s
+                </button>
+                <button
+                  id="mediaTimingReviewEndForward"
+                  type="button"
+                  aria-label="Move end forward 100 milliseconds"
+                >
+                  +0.1s
+                </button>
+              </div>
+            </div>
+
+            <div
+              id="mediaTimingReviewStatus"
+              class="media-timing-review-status"
+              role="status"
+              aria-live="polite"
+            ></div>
+            <div class="media-timing-review-footer">
+              <div class="media-timing-review-preview-actions">
+                <button
+                  id="mediaTimingReviewPlay"
+                  class="media-timing-review-play-button"
+                  type="button"
+                >
+                  <span class="media-timing-review-play-glyph" aria-hidden="true"></span>
+                  <span id="mediaTimingReviewPlayLabel">Play selection</span>
+                </button>
+                <button
+                  id="mediaTimingReviewReset"
+                  class="media-timing-review-quiet-button"
+                  type="button"
+                >
+                  Reset timing
+                </button>
+              </div>
+              <button
+                id="mediaTimingReviewConfirm"
+                class="media-timing-review-confirm-button"
+                type="button"
+              >
+                Use this timing
+              </button>
+            </div>
+            <div class="media-timing-review-hints" aria-hidden="true">
+              <span><kbd>Space</kbd> preview</span>
+              <span><kbd>&larr;</kbd><kbd>&rarr;</kbd> nudge focused edge</span>
+              <span><kbd>P</kbd>/<kbd>N</kbd> add prev/next line</span>
+              <span><kbd>Enter</kbd> confirm</span>
+              <span><kbd>Esc</kbd> cancel</span>
+            </div>
+          </div>
+
+          <div id="mediaTimingReviewCancelStep" class="media-timing-review-cancel-step hidden">
+            <div class="media-timing-review-cancel-mark" aria-hidden="true">?</div>
+            <h2>Stop reviewing?</h2>
+            <p id="mediaTimingReviewCancelMessage">Choose what should happen to this card.</p>
+            <div class="media-timing-review-cancel-actions">
+              <button
+                id="mediaTimingReviewCancelBack"
+                class="media-timing-review-quiet-button"
+                type="button"
+              >
+                Keep editing
+              </button>
+              <button
+                id="mediaTimingReviewUseOriginal"
+                class="media-timing-review-original-button"
+                type="button"
+              >
+                Use original timing
+              </button>
+              <button
+                id="mediaTimingReviewSkipMedia"
+                class="media-timing-review-skip-button"
+                type="button"
+                title="Keep this card but do not add audio or an image."
+              >
+                Keep without media
+              </button>
+              <button
+                id="mediaTimingReviewDiscard"
+                class="media-timing-review-discard-button"
+                type="button"
+              >
+                Delete card
+              </button>
+            </div>
+          </div>
+        </div>
+      </div>
       <div id="kikuFieldGroupingModal" class="modal hidden" aria-hidden="true">
         <div class="modal-content">
           <div class="modal-header">
@@ -205,8 +570,8 @@
             <div id="kikuSelectionStep">
               <div class="kiku-info-text">
                 A card with the same expression already exists. Select which card to keep. The other
-                card's content will be merged using Kiku field grouping. You can choose whether to
-                delete the duplicate.
+                card's content will be merged using field grouping. You can choose whether to delete
+                the duplicate.
               </div>
               <div class="kiku-cards-container">
                 <div id="kikuCard1" class="kiku-card active" tabindex="0">
@@ -340,6 +705,171 @@
           </div>
         </div>
       </div>
+      <div
+        id="subtitleGenerationModal"
+        class="modal hidden"
+        aria-hidden="true"
+        role="dialog"
+        aria-modal="true"
+        aria-labelledby="subtitleGenerationTitle"
+      >
+        <div class="modal-content subtitle-generation-content">
+          <div class="modal-header">
+            <div id="subtitleGenerationTitle" class="modal-title">Generate Japanese subtitles</div>
+            <button id="subtitleGenerationClose" class="modal-close" type="button">Close</button>
+          </div>
+          <div class="modal-body subtitle-generation-body">
+            <p class="subtitle-generation-intro">
+              Turn the current audio track into timed Japanese subtitles. Audio stays on this
+              device.
+            </p>
+            <div class="subtitle-generation-detail">
+              <span class="subtitle-generation-label">Current media</span>
+              <div id="subtitleGenerationMedia">Checking current media...</div>
+            </div>
+            <div class="subtitle-generation-detail">
+              <span class="subtitle-generation-label">Local tools</span>
+              <div id="subtitleGenerationTools">Checking local tools...</div>
+              <p class="subtitle-generation-hint">
+                SubMiner downloads models, not whisper.cpp or FFmpeg. Install them, or set their
+                paths in Settings → Integrations → Japanese Subtitle Generation.
+              </p>
+            </div>
+            <div class="subtitle-generation-detail">
+              <span class="subtitle-generation-label">Speech model</span>
+              <div id="subtitleGenerationModel">Checking local models...</div>
+              <div
+                id="subtitleGenerationModelPicker"
+                class="subtitle-generation-model-picker hidden"
+              >
+                <label for="subtitleGenerationModelSelect">Model</label>
+                <select
+                  id="subtitleGenerationModelSelect"
+                  aria-describedby="subtitleGenerationModelDescription subtitleGenerationModelRecommendation"
+                ></select>
+                <p id="subtitleGenerationModelDescription" class="subtitle-generation-hint"></p>
+                <p id="subtitleGenerationModelRecommendation" class="subtitle-generation-hint">
+                  Start with small for a balance of accuracy and CPU time. Larger models need more
+                  memory; speed depends on your hardware. Sizes shown are downloads.
+                </p>
+                <p class="subtitle-generation-hint">
+                  This choice lasts for this SubMiner session. Set the default model in Settings.
+                </p>
+              </div>
+              <p class="subtitle-generation-hint">
+                Use your own model in Settings → Integrations → Japanese Subtitle Generation → Model
+                Path.
+              </p>
+              <button
+                id="subtitleGenerationDownload"
+                class="kiku-cancel-button hidden"
+                type="button"
+              >
+                Download model
+              </button>
+            </div>
+            <div class="subtitle-generation-detail">
+              <label class="subtitle-generation-vad-toggle" for="subtitleGenerationVadEnabled">
+                <input
+                  id="subtitleGenerationVadEnabled"
+                  type="checkbox"
+                  aria-describedby="subtitleGenerationVadHint"
+                />
+                Focus on spoken dialogue <span class="subtitle-generation-hint">Optional</span>
+              </label>
+              <div id="subtitleGenerationVadModel" class="subtitle-generation-hint"></div>
+              <p id="subtitleGenerationVadHint" class="subtitle-generation-hint">
+                Keeps uncertain audio to avoid losing dialogue under music. Songs may also be
+                transcribed. Requires whisper.cpp's speech detector.
+              </p>
+              <p class="subtitle-generation-hint">
+                Applies for this session. Set VAD Model Path in Settings to enable it by default.
+              </p>
+              <button
+                id="subtitleGenerationVadDownload"
+                class="kiku-cancel-button hidden"
+                type="button"
+              >
+                Download speech detection model
+              </button>
+            </div>
+            <div id="subtitleGenerationActivity" class="subtitle-generation-activity hidden">
+              <div class="subtitle-generation-progress-heading">
+                <span id="subtitleGenerationStage">Preparing</span>
+                <span id="subtitleGenerationPercent"></span>
+              </div>
+              <progress
+                id="subtitleGenerationProgress"
+                max="100"
+                aria-label="Subtitle generation progress"
+              ></progress>
+            </div>
+            <div
+              id="subtitleGenerationStatus"
+              class="runtime-options-status"
+              role="status"
+              aria-live="polite"
+            ></div>
+            <div class="subtitle-generation-actions">
+              <button id="subtitleGenerationRefresh" class="kiku-cancel-button" type="button">
+                Check again
+              </button>
+              <button id="subtitleGenerationCancel" class="kiku-cancel-button hidden" type="button">
+                Cancel
+              </button>
+              <button
+                id="subtitleGenerationStart"
+                class="kiku-confirm-button"
+                type="button"
+                disabled
+              >
+                Generate subtitles
+              </button>
+            </div>
+            <p class="subtitle-generation-hint">
+              The generated SRT will be saved locally and loaded into the player. You can close this
+              window while it runs.
+            </p>
+          </div>
+        </div>
+      </div>
+      <div id="subtitleSelectionModal" class="modal hidden" aria-hidden="true">
+        <div
+          class="modal-content subsync-modal-content"
+          role="dialog"
+          aria-modal="true"
+          aria-labelledby="subtitleSelectionTitle"
+        >
+          <div class="modal-header">
+            <h2 id="subtitleSelectionTitle">Select subtitles</h2>
+            <button id="subtitleSelectionClose" class="modal-close" type="button">Close</button>
+          </div>
+          <div class="modal-body">
+            <div class="subsync-form">
+              <label class="subsync-field">
+                <span>Primary subtitle</span>
+                <select id="subtitleSelectionPrimary"></select>
+              </label>
+              <label class="subsync-field">
+                <span>Secondary subtitle</span>
+                <select id="subtitleSelectionSecondary"></select>
+              </label>
+            </div>
+            <div
+              id="subtitleSelectionStatus"
+              class="runtime-options-status"
+              role="status"
+              aria-live="polite"
+            ></div>
+            <div class="subsync-footer">
+              <button id="subtitleSelectionApply" class="kiku-confirm-button" type="button">
+                Apply
+              </button>
+            </div>
+          </div>
+        </div>
+      </div>
+
       <div id="subsyncModal" class="modal hidden" aria-hidden="true">
         <div class="modal-content subsync-modal-content">
           <div class="modal-header">
@@ -437,9 +967,17 @@
         <div id="subtitleSidebarContent" class="modal-content subtitle-sidebar-content">
           <div class="modal-header">
             <div class="modal-title">Subtitle Sidebar</div>
+            <button id="subtitleSidebarCopy" class="modal-close" type="button" hidden>Copy</button>
             <button id="subtitleSidebarClose" class="modal-close" type="button">Close</button>
           </div>
           <div class="modal-body subtitle-sidebar-body">
+            <button
+              id="subtitleGenerationOpen"
+              class="kiku-cancel-button subtitle-generation-open"
+              type="button"
+            >
+              Generate Japanese subtitles
+            </button>
             <div id="subtitleSidebarStatus" class="runtime-options-status"></div>
             <ul id="subtitleSidebarList" class="subtitle-sidebar-list"></ul>
           </div>
diff --git a/src/renderer/modals/jimaku.test.ts b/src/renderer/modals/jimaku.test.ts
index d3328b87..e8e59ed7 100644
--- a/src/renderer/modals/jimaku.test.ts
+++ b/src/renderer/modals/jimaku.test.ts
@@ -119,6 +119,8 @@ test('successful Jimaku subtitle selection closes modal', async () => {
           classList: jimakuBroadenButtonClassList,
           addEventListener: () => {},
         },
+        jimakuTabAnimeButton: { classList: createClassList(['active']), setAttribute: () => {} },
+        jimakuTabLiveActionButton: { classList: createClassList(), setAttribute: () => {} },
       },
       state,
     };
@@ -147,3 +149,427 @@ test('successful Jimaku subtitle selection closes modal', async () => {
     Object.defineProperty(globalThis, 'document', { configurable: true, value: previousDocument });
   }
 });
+
+test('switching to the Live action tab re-runs the search with the live action category', async () => {
+  const globals = globalThis as typeof globalThis & { window?: unknown; document?: unknown };
+  const previousWindow = globals.window;
+  const previousDocument = globals.document;
+
+  const searchQueries: Array<{ query: string; category?: string }> = [];
+  const electronAPI = {
+    jimakuSearchEntries: async (query: { query: string; category?: string }) => {
+      searchQueries.push(query);
+      return { ok: true, data: [] };
+    },
+  } as unknown as ElectronAPI;
+
+  Object.defineProperty(globalThis, 'window', {
+    configurable: true,
+    value: { electronAPI },
+  });
+  Object.defineProperty(globalThis, 'document', {
+    configurable: true,
+    value: {
+      activeElement: null,
+      createElement: () => createElementStub(),
+    },
+  });
+
+  try {
+    const state = createRendererState();
+    state.jimakuModalOpen = true;
+    const animeTabClassList = createClassList(['active']);
+    const liveActionTabClassList = createClassList();
+    const status = { textContent: '', style: { color: '' } };
+
+    const ctx = {
+      dom: {
+        overlay: { classList: createClassList(['interactive']) },
+        jimakuModal: { classList: createClassList(), setAttribute: () => {} },
+        jimakuTitleInput: { value: 'Shinzanmono' },
+        jimakuSeasonInput: { value: '' },
+        jimakuEpisodeInput: { value: '3' },
+        jimakuSearchButton: { addEventListener: () => {} },
+        jimakuCloseButton: { addEventListener: () => {} },
+        jimakuStatus: status,
+        jimakuEntriesSection: { classList: createClassList(['hidden']) },
+        jimakuEntriesList: createListStub(),
+        jimakuFilesSection: { classList: createClassList(['hidden']) },
+        jimakuFilesList: createListStub(),
+        jimakuBroadenButton: { classList: createClassList(['hidden']), addEventListener: () => {} },
+        jimakuTabAnimeButton: { classList: animeTabClassList, setAttribute: () => {} },
+        jimakuTabLiveActionButton: { classList: liveActionTabClassList, setAttribute: () => {} },
+      },
+      state,
+    };
+
+    const jimakuModal = createJimakuModal(ctx as never, {
+      modalStateReader: { isAnyModalOpen: () => false },
+      syncSettingsModalSubtitleSuppression: () => {},
+    });
+
+    jimakuModal.handleJimakuKeydown({
+      key: 'ArrowRight',
+      preventDefault: () => {},
+    } as KeyboardEvent);
+    await flushAsyncWork();
+
+    assert.equal(state.jimakuActiveTab, 'liveAction');
+    assert.equal(liveActionTabClassList.contains('active'), true);
+    assert.equal(animeTabClassList.contains('active'), false);
+    assert.deepEqual(searchQueries, [{ query: 'Shinzanmono', category: 'liveAction' }]);
+    assert.equal(status.textContent, 'No live action entries found. Try the Anime tab.');
+
+    // Same tab again is a no-op: no duplicate request.
+    jimakuModal.handleJimakuKeydown({
+      key: 'ArrowRight',
+      preventDefault: () => {},
+    } as KeyboardEvent);
+    await flushAsyncWork();
+    assert.equal(searchQueries.length, 1);
+  } finally {
+    Object.defineProperty(globalThis, 'window', { configurable: true, value: previousWindow });
+    Object.defineProperty(globalThis, 'document', { configurable: true, value: previousDocument });
+  }
+});
+
+test('a slow reply from a superseded search does not overwrite the newer results', async () => {
+  const globals = globalThis as typeof globalThis & { window?: unknown; document?: unknown };
+  const previousWindow = globals.window;
+  const previousDocument = globals.document;
+
+  const pending: Array<(entries: unknown[]) => void> = [];
+  const electronAPI = {
+    jimakuSearchEntries: () =>
+      new Promise((resolve) => {
+        pending.push((entries) => resolve({ ok: true, data: entries }));
+      }),
+    jimakuListFiles: async () => ({ ok: true, data: [] }),
+  } as unknown as ElectronAPI;
+
+  Object.defineProperty(globalThis, 'window', {
+    configurable: true,
+    value: { electronAPI },
+  });
+  Object.defineProperty(globalThis, 'document', {
+    configurable: true,
+    value: {
+      activeElement: null,
+      createElement: () => createElementStub(),
+    },
+  });
+
+  try {
+    const state = createRendererState();
+    state.jimakuModalOpen = true;
+
+    const ctx = {
+      dom: {
+        overlay: { classList: createClassList(['interactive']) },
+        jimakuModal: { classList: createClassList(), setAttribute: () => {} },
+        jimakuTitleInput: { value: 'Shinzanmono' },
+        jimakuSeasonInput: { value: '' },
+        jimakuEpisodeInput: { value: '' },
+        jimakuSearchButton: { addEventListener: () => {} },
+        jimakuCloseButton: { addEventListener: () => {} },
+        jimakuStatus: { textContent: '', style: { color: '' } },
+        jimakuEntriesSection: { classList: createClassList(['hidden']) },
+        jimakuEntriesList: createListStub(),
+        jimakuFilesSection: { classList: createClassList(['hidden']) },
+        jimakuFilesList: createListStub(),
+        jimakuBroadenButton: { classList: createClassList(['hidden']), addEventListener: () => {} },
+        jimakuTabAnimeButton: { classList: createClassList(['active']), setAttribute: () => {} },
+        jimakuTabLiveActionButton: { classList: createClassList(), setAttribute: () => {} },
+      },
+      state,
+    };
+
+    const jimakuModal = createJimakuModal(ctx as never, {
+      modalStateReader: { isAnyModalOpen: () => false },
+      syncSettingsModalSubtitleSuppression: () => {},
+    });
+
+    // Anime -> Live action -> Anime, all before any reply arrives.
+    jimakuModal.handleJimakuKeydown({
+      key: 'ArrowRight',
+      preventDefault: () => {},
+    } as KeyboardEvent);
+    jimakuModal.handleJimakuKeydown({
+      key: 'ArrowLeft',
+      preventDefault: () => {},
+    } as KeyboardEvent);
+    await flushAsyncWork();
+    assert.equal(pending.length, 2);
+
+    // The stale live action reply lands after the newer anime search was issued.
+    pending[0]!([{ id: 1, name: 'Stale live action entry' }]);
+    await flushAsyncWork();
+    assert.equal(state.jimakuEntries.length, 0);
+
+    pending[1]!([
+      { id: 2, name: 'Anime A' },
+      { id: 3, name: 'Anime B' },
+    ]);
+    await flushAsyncWork();
+    assert.deepEqual(
+      state.jimakuEntries.map((entry) => entry.id),
+      [2, 3],
+    );
+  } finally {
+    Object.defineProperty(globalThis, 'window', { configurable: true, value: previousWindow });
+    Object.defineProperty(globalThis, 'document', { configurable: true, value: previousDocument });
+  }
+});
+
+test('closing the modal discards an in-flight search reply', async () => {
+  const globals = globalThis as typeof globalThis & { window?: unknown; document?: unknown };
+  const previousWindow = globals.window;
+  const previousDocument = globals.document;
+
+  let resolveSearch!: (entries: unknown[]) => void;
+  let listFilesCalls = 0;
+  const electronAPI = {
+    jimakuSearchEntries: () =>
+      new Promise((resolve) => {
+        resolveSearch = (entries) => resolve({ ok: true, data: entries });
+      }),
+    jimakuListFiles: async () => {
+      listFilesCalls += 1;
+      return { ok: true, data: [] };
+    },
+    notifyOverlayModalClosed: () => {},
+  } as unknown as ElectronAPI;
+
+  Object.defineProperty(globalThis, 'window', {
+    configurable: true,
+    value: { electronAPI },
+  });
+  Object.defineProperty(globalThis, 'document', {
+    configurable: true,
+    value: {
+      activeElement: null,
+      createElement: () => createElementStub(),
+    },
+  });
+
+  try {
+    const state = createRendererState();
+    state.jimakuModalOpen = true;
+
+    const ctx = {
+      dom: {
+        overlay: { classList: createClassList(['interactive']) },
+        jimakuModal: { classList: createClassList(), setAttribute: () => {} },
+        jimakuTitleInput: { value: 'Shinzanmono' },
+        jimakuSeasonInput: { value: '' },
+        jimakuEpisodeInput: { value: '' },
+        jimakuSearchButton: { addEventListener: () => {} },
+        jimakuCloseButton: { addEventListener: () => {} },
+        jimakuStatus: { textContent: '', style: { color: '' } },
+        jimakuEntriesSection: { classList: createClassList(['hidden']) },
+        jimakuEntriesList: createListStub(),
+        jimakuFilesSection: { classList: createClassList(['hidden']) },
+        jimakuFilesList: createListStub(),
+        jimakuBroadenButton: { classList: createClassList(['hidden']), addEventListener: () => {} },
+        jimakuTabAnimeButton: { classList: createClassList(['active']), setAttribute: () => {} },
+        jimakuTabLiveActionButton: { classList: createClassList(), setAttribute: () => {} },
+      },
+      state,
+    };
+
+    const jimakuModal = createJimakuModal(ctx as never, {
+      modalStateReader: { isAnyModalOpen: () => false },
+      syncSettingsModalSubtitleSuppression: () => {},
+    });
+
+    jimakuModal.handleJimakuKeydown({ key: 'Enter', preventDefault: () => {} } as KeyboardEvent);
+    await flushAsyncWork();
+    jimakuModal.closeJimakuModal();
+
+    // A single entry would normally auto-select and fetch its files.
+    resolveSearch([{ id: 7, name: 'Only entry' }]);
+    await flushAsyncWork();
+
+    assert.equal(state.jimakuEntries.length, 0);
+    assert.equal(state.currentEntryId, null);
+    assert.equal(listFilesCalls, 0);
+  } finally {
+    Object.defineProperty(globalThis, 'window', { configurable: true, value: previousWindow });
+    Object.defineProperty(globalThis, 'document', { configurable: true, value: previousDocument });
+  }
+});
+
+test('a slow files reply for a previously selected entry is ignored', async () => {
+  const globals = globalThis as typeof globalThis & { window?: unknown; document?: unknown };
+  const previousWindow = globals.window;
+  const previousDocument = globals.document;
+
+  const pending = new Map<number, (files: unknown[]) => void>();
+  const electronAPI = {
+    jimakuListFiles: (query: { entryId: number }) =>
+      new Promise((resolve) => {
+        pending.set(query.entryId, (files) => resolve({ ok: true, data: files }));
+      }),
+  } as unknown as ElectronAPI;
+
+  Object.defineProperty(globalThis, 'window', {
+    configurable: true,
+    value: { electronAPI },
+  });
+  Object.defineProperty(globalThis, 'document', {
+    configurable: true,
+    value: {
+      activeElement: null,
+      createElement: () => createElementStub(),
+    },
+  });
+
+  try {
+    const state = createRendererState();
+    state.jimakuModalOpen = true;
+    state.jimakuEntries = [
+      { id: 1, name: 'Entry A' },
+      { id: 2, name: 'Entry B' },
+    ];
+
+    const ctx = {
+      dom: {
+        overlay: { classList: createClassList(['interactive']) },
+        jimakuModal: { classList: createClassList(), setAttribute: () => {} },
+        jimakuTitleInput: { value: '' },
+        jimakuSeasonInput: { value: '' },
+        jimakuEpisodeInput: { value: '' },
+        jimakuSearchButton: { addEventListener: () => {} },
+        jimakuCloseButton: { addEventListener: () => {} },
+        jimakuStatus: { textContent: '', style: { color: '' } },
+        jimakuEntriesSection: { classList: createClassList() },
+        jimakuEntriesList: createListStub(),
+        jimakuFilesSection: { classList: createClassList(['hidden']) },
+        jimakuFilesList: createListStub(),
+        jimakuBroadenButton: { classList: createClassList(['hidden']), addEventListener: () => {} },
+        jimakuTabAnimeButton: { classList: createClassList(['active']), setAttribute: () => {} },
+        jimakuTabLiveActionButton: { classList: createClassList(), setAttribute: () => {} },
+      },
+      state,
+    };
+
+    const jimakuModal = createJimakuModal(ctx as never, {
+      modalStateReader: { isAnyModalOpen: () => false },
+      syncSettingsModalSubtitleSuppression: () => {},
+    });
+
+    // Select entry A, then move to entry B before A's files arrive.
+    jimakuModal.handleJimakuKeydown({ key: 'Enter', preventDefault: () => {} } as KeyboardEvent);
+    jimakuModal.handleJimakuKeydown({
+      key: 'ArrowDown',
+      preventDefault: () => {},
+    } as KeyboardEvent);
+    jimakuModal.handleJimakuKeydown({ key: 'Enter', preventDefault: () => {} } as KeyboardEvent);
+    await flushAsyncWork();
+    assert.equal(state.currentEntryId, 2);
+
+    pending.get(1)!([
+      { name: 'a.srt', url: 'https://jimaku.cc/a.srt', size: 1, last_modified: '' },
+    ]);
+    await flushAsyncWork();
+    assert.equal(state.jimakuFiles.length, 0);
+
+    pending.get(2)!([
+      { name: 'b1.srt', url: 'https://jimaku.cc/b1.srt', size: 1, last_modified: '' },
+      { name: 'b2.srt', url: 'https://jimaku.cc/b2.srt', size: 1, last_modified: '' },
+    ]);
+    await flushAsyncWork();
+    assert.deepEqual(
+      state.jimakuFiles.map((file) => file.name),
+      ['b1.srt', 'b2.srt'],
+    );
+  } finally {
+    Object.defineProperty(globalThis, 'window', { configurable: true, value: previousWindow });
+    Object.defineProperty(globalThis, 'document', { configurable: true, value: previousDocument });
+  }
+});
+
+test('media info arriving after the modal closed does not fill inputs or search', async () => {
+  const globals = globalThis as typeof globalThis & { window?: unknown; document?: unknown };
+  const previousWindow = globals.window;
+  const previousDocument = globals.document;
+
+  let resolveMediaInfo!: (info: unknown) => void;
+  let searchCalls = 0;
+  const electronAPI = {
+    getJimakuMediaInfo: () =>
+      new Promise((resolve) => {
+        resolveMediaInfo = resolve;
+      }),
+    jimakuSearchEntries: async () => {
+      searchCalls += 1;
+      return { ok: true, data: [] };
+    },
+    notifyOverlayModalClosed: () => {},
+  } as unknown as ElectronAPI;
+
+  Object.defineProperty(globalThis, 'window', {
+    configurable: true,
+    value: { electronAPI },
+  });
+  Object.defineProperty(globalThis, 'document', {
+    configurable: true,
+    value: {
+      activeElement: null,
+      createElement: () => createElementStub(),
+    },
+  });
+
+  try {
+    const state = createRendererState();
+    const titleInput = { value: '' };
+    const status = { textContent: '', style: { color: '' } };
+
+    const ctx = {
+      dom: {
+        overlay: { classList: createClassList() },
+        jimakuModal: { classList: createClassList(['hidden']), setAttribute: () => {} },
+        jimakuTitleInput: titleInput,
+        jimakuSeasonInput: { value: '' },
+        jimakuEpisodeInput: { value: '' },
+        jimakuSearchButton: { addEventListener: () => {} },
+        jimakuCloseButton: { addEventListener: () => {} },
+        jimakuStatus: status,
+        jimakuEntriesSection: { classList: createClassList(['hidden']) },
+        jimakuEntriesList: createListStub(),
+        jimakuFilesSection: { classList: createClassList(['hidden']) },
+        jimakuFilesList: createListStub(),
+        jimakuBroadenButton: { classList: createClassList(['hidden']), addEventListener: () => {} },
+        jimakuTabAnimeButton: { classList: createClassList(['active']), setAttribute: () => {} },
+        jimakuTabLiveActionButton: { classList: createClassList(), setAttribute: () => {} },
+      },
+      state,
+    };
+
+    const jimakuModal = createJimakuModal(ctx as never, {
+      modalStateReader: { isAnyModalOpen: () => false },
+      syncSettingsModalSubtitleSuppression: () => {},
+    });
+
+    jimakuModal.openJimakuModal();
+    await flushAsyncWork();
+    jimakuModal.closeJimakuModal();
+
+    resolveMediaInfo({
+      title: 'Shinzanmono',
+      season: 1,
+      episode: 3,
+      confidence: 'high',
+      filename: 'Shinzanmono S01E03.mkv',
+      rawTitle: 'Shinzanmono S01E03',
+    });
+    await flushAsyncWork();
+
+    assert.equal(titleInput.value, '');
+    assert.equal(searchCalls, 0);
+    assert.equal(status.textContent, 'Loading media info...');
+  } finally {
+    Object.defineProperty(globalThis, 'window', { configurable: true, value: previousWindow });
+    Object.defineProperty(globalThis, 'document', { configurable: true, value: previousDocument });
+  }
+});
diff --git a/src/renderer/modals/jimaku.ts b/src/renderer/modals/jimaku.ts
index e6278dcb..086baf92 100644
--- a/src/renderer/modals/jimaku.ts
+++ b/src/renderer/modals/jimaku.ts
@@ -4,6 +4,7 @@ import type {
   JimakuEntry,
   JimakuFileEntry,
   JimakuMediaInfo,
+  JimakuSearchCategory,
 } from '../../types';
 import type { ModalStateReader, RendererContext } from '../context';
 
@@ -21,7 +22,12 @@ export function createJimakuModal(
       : 'rgba(255, 255, 255, 0.8)';
   }
 
+  // Bumped whenever the lists are reset (new search, tab switch, open, close)
+  // so any in-flight entries or files reply for the old state is discarded.
+  let searchGeneration = 0;
+
   function resetJimakuLists(): void {
+    searchGeneration += 1;
     ctx.state.jimakuEntries = [];
     ctx.state.jimakuFiles = [];
     ctx.state.selectedEntryIndex = 0;
@@ -35,6 +41,33 @@ export function createJimakuModal(
     ctx.dom.jimakuBroadenButton.classList.add('hidden');
   }
 
+  function renderTabs(): void {
+    const liveActionActive = ctx.state.jimakuActiveTab === 'liveAction';
+    const active = liveActionActive
+      ? ctx.dom.jimakuTabLiveActionButton
+      : ctx.dom.jimakuTabAnimeButton;
+    const inactive = liveActionActive
+      ? ctx.dom.jimakuTabAnimeButton
+      : ctx.dom.jimakuTabLiveActionButton;
+    active.classList.add('active');
+    active.setAttribute('aria-selected', 'true');
+    inactive.classList.remove('active');
+    inactive.setAttribute('aria-selected', 'false');
+  }
+
+  // Tabs map to Jimaku's anime / live-action catalogues, so switching re-runs
+  // the search server-side instead of filtering a shared result list.
+  function setActiveTab(tab: JimakuSearchCategory): void {
+    if (ctx.state.jimakuActiveTab === tab) return;
+    ctx.state.jimakuActiveTab = tab;
+    renderTabs();
+    if (getSearchQuery().query) {
+      void performJimakuSearch();
+    } else {
+      resetJimakuLists();
+    }
+  }
+
   function formatEntryLabel(entry: JimakuEntry): string {
     if (entry.english_name && entry.english_name !== entry.name) {
       return `${entry.name} / ${entry.english_name}`;
@@ -133,9 +166,12 @@ export function createJimakuModal(
     setJimakuStatus('Searching Jimaku...');
     ctx.state.currentEpisodeFilter = episode;
 
+    const category = ctx.state.jimakuActiveTab;
+    const generation = searchGeneration;
     const response: JimakuApiResponse<JimakuEntry[]> = await window.electronAPI.jimakuSearchEntries(
-      { query },
+      { query, category },
     );
+    if (generation !== searchGeneration) return;
     if (!response.ok) {
       const retry = response.error.retryAfter
         ? ` Retry after ${response.error.retryAfter.toFixed(1)}s.`
@@ -148,7 +184,11 @@ export function createJimakuModal(
     ctx.state.selectedEntryIndex = 0;
 
     if (ctx.state.jimakuEntries.length === 0) {
-      setJimakuStatus('No entries found.');
+      setJimakuStatus(
+        category === 'anime'
+          ? 'No anime entries found. Try the Live action tab.'
+          : 'No live action entries found. Try the Anime tab.',
+      );
       return;
     }
 
@@ -167,12 +207,15 @@ export function createJimakuModal(
     ctx.dom.jimakuFilesList.innerHTML = '';
     ctx.dom.jimakuFilesSection.classList.add('hidden');
 
+    const generation = searchGeneration;
     const response: JimakuApiResponse<JimakuFileEntry[]> = await window.electronAPI.jimakuListFiles(
       {
         entryId,
         episode,
       },
     );
+    // The user may have picked another entry or reset the modal meanwhile.
+    if (generation !== searchGeneration || ctx.state.currentEntryId !== entryId) return;
     if (!response.ok) {
       const retry = response.error.retryAfter
         ? ` Retry after ${response.error.retryAfter.toFixed(1)}s.`
@@ -262,10 +305,15 @@ export function createJimakuModal(
 
     setJimakuStatus('Loading media info...');
     resetJimakuLists();
+    renderTabs();
 
+    // Media info can resolve after the user already closed the modal or
+    // started their own search; a stale reply must not touch the inputs.
+    const generation = searchGeneration;
     window.electronAPI
       .getJimakuMediaInfo()
       .then((info: JimakuMediaInfo) => {
+        if (generation !== searchGeneration) return;
         ctx.dom.jimakuTitleInput.value = info.title || '';
         ctx.dom.jimakuSeasonInput.value = info.season ? String(info.season) : '';
         ctx.dom.jimakuEpisodeInput.value = info.episode ? String(info.episode) : '';
@@ -280,6 +328,7 @@ export function createJimakuModal(
         }
       })
       .catch(() => {
+        if (generation !== searchGeneration) return;
         setJimakuStatus('Failed to load media info.', true);
       });
   }
@@ -315,6 +364,18 @@ export function createJimakuModal(
       return true;
     }
 
+    if (e.key === 'ArrowLeft') {
+      e.preventDefault();
+      setActiveTab('anime');
+      return true;
+    }
+
+    if (e.key === 'ArrowRight') {
+      e.preventDefault();
+      setActiveTab('liveAction');
+      return true;
+    }
+
     if (e.key === 'ArrowDown') {
       e.preventDefault();
       if (ctx.state.jimakuFiles.length > 0) {
@@ -367,6 +428,12 @@ export function createJimakuModal(
     ctx.dom.jimakuCloseButton.addEventListener('click', () => {
       closeJimakuModal();
     });
+    ctx.dom.jimakuTabAnimeButton.addEventListener('click', () => {
+      setActiveTab('anime');
+    });
+    ctx.dom.jimakuTabLiveActionButton.addEventListener('click', () => {
+      setActiveTab('liveAction');
+    });
     ctx.dom.jimakuBroadenButton.addEventListener('click', () => {
       if (ctx.state.currentEntryId !== null) {
         ctx.dom.jimakuBroadenButton.classList.add('hidden');
diff --git a/src/renderer/modals/media-timing-frame-picker.test.ts b/src/renderer/modals/media-timing-frame-picker.test.ts
new file mode 100644
index 00000000..84c22d46
--- /dev/null
+++ b/src/renderer/modals/media-timing-frame-picker.test.ts
@@ -0,0 +1,116 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { setTimeout as tick } from 'node:timers/promises';
+import { createMediaTimingFramePicker } from './media-timing-frame-picker';
+import type { MediaTimingReviewFrameRequest, MediaTimingReviewFrameResult } from '../../types/anki';
+
+function fixture() {
+  const requests: Array<{
+    request: MediaTimingReviewFrameRequest;
+    resolve: (result: MediaTimingReviewFrameResult) => void;
+  }> = [];
+  let stale = false;
+  const picker = createMediaTimingFramePicker({
+    debounceMs: 0,
+    load: (request) => new Promise((resolve) => requests.push({ request, resolve })),
+    onChange: () => {},
+    onStale: () => {
+      stale = true;
+      picker.close();
+    },
+  });
+  const complete = async (index: number, result: number | MediaTimingReviewFrameResult) => {
+    requests[index]!.resolve(
+      typeof result === 'number'
+        ? { ok: true, timestamp: result, dataUrl: `data:image/jpeg;base64,${result}` }
+        : result,
+    );
+    await tick(0);
+  };
+  return { picker, requests, complete, isStale: () => stale };
+}
+
+test('a chosen frame stays fixed until Reset restores midpoint tracking', async () => {
+  const { picker, requests, complete } = fixture();
+  picker.open('r', true, 11);
+  await tick(5);
+  await complete(0, 11);
+  assert.equal(picker.getScreenshotTime(), undefined);
+  picker.choose(13);
+  await tick(5);
+  await complete(1, 13);
+  picker.updateMidpoint(12);
+  await tick(5);
+  assert.equal(picker.getScreenshotTime(), 13);
+  assert.equal(requests.length, 2);
+  picker.reset();
+  await tick(5);
+  assert.equal(requests[2]?.request.timestamp, 12);
+  await complete(2, 12);
+  assert.equal(picker.getScreenshotTime(), undefined);
+  picker.updateMidpoint(14);
+  await tick(5);
+  assert.equal(requests[3]?.request.timestamp, 14);
+  await complete(3, 14);
+  picker.close();
+});
+
+test('scrubbing keeps only the latest requested frame', async () => {
+  const { picker, requests, complete } = fixture();
+  picker.open('r', true, 11);
+  await tick(5);
+  picker.choose(12);
+  picker.choose(13);
+  picker.choose(14);
+  await tick(5);
+  assert.equal(requests.length, 1);
+  assert.equal(picker.getState().blockConfirm, true);
+  await complete(0, 11);
+  await tick(5);
+  assert.equal(picker.getState().timestamp, undefined);
+  assert.equal(requests[1]?.request.timestamp, 14);
+  await complete(1, 14);
+  assert.equal(picker.getScreenshotTime(), 14);
+  assert.equal(picker.getState().blockConfirm, false);
+  picker.close();
+});
+
+test('failed manual previews block confirmation; Reset allows the default fallback', async () => {
+  const { picker, complete } = fixture();
+  picker.open('r', true, 11);
+  await tick(5);
+  await complete(0, { ok: false });
+  assert.equal(picker.getState().blockConfirm, false);
+  picker.choose(12);
+  await tick(5);
+  await complete(1, { ok: false });
+  assert.equal(picker.getState().blockConfirm, true);
+  picker.reset();
+  assert.equal(picker.getState().blockConfirm, false);
+  picker.close();
+});
+
+test('replacing a review ignores old frames; stale responses close the current review', async () => {
+  const { picker, requests, complete, isStale } = fixture();
+  picker.open('old', true, 11);
+  await tick(5);
+  picker.close();
+  picker.open('new', true, 22);
+  await tick(5);
+  await complete(0, 11);
+  await tick(5);
+  assert.equal(picker.getState().timestamp, undefined);
+  assert.equal(requests[1]?.request.reviewId, 'new');
+  await complete(1, { ok: false, stale: true });
+  assert.equal(isStale(), true);
+  assert.equal(picker.getState().enabled, false);
+});
+
+test('disabled screenshots perform no extraction', async () => {
+  const { picker, requests } = fixture();
+  picker.open('r', false, 11);
+  picker.updateMidpoint(12);
+  await tick(5);
+  assert.equal(requests.length, 0);
+  picker.close();
+});
diff --git a/src/renderer/modals/media-timing-frame-picker.ts b/src/renderer/modals/media-timing-frame-picker.ts
new file mode 100644
index 00000000..41138862
--- /dev/null
+++ b/src/renderer/modals/media-timing-frame-picker.ts
@@ -0,0 +1,129 @@
+import type { MediaTimingReviewFrameRequest, MediaTimingReviewFrameResult } from '../../types/anki';
+
+export interface MediaTimingFramePickerState {
+  enabled: boolean;
+  manual: boolean;
+  loading: boolean;
+  timestamp?: number;
+  requestedTime?: number;
+  dataUrl?: string;
+  message: string;
+  blockConfirm: boolean;
+}
+
+/** Coalesces scrubbing into one active extraction and the latest requested frame. */
+export function createMediaTimingFramePicker(options: {
+  load: (request: MediaTimingReviewFrameRequest) => Promise<MediaTimingReviewFrameResult>;
+  onChange: (state: MediaTimingFramePickerState) => void;
+  onStale: () => void;
+  debounceMs?: number;
+}) {
+  let reviewId: string | null = null;
+  let midpoint = 0;
+  let sequence = 0;
+  let inFlight = false;
+  let pending: (MediaTimingReviewFrameRequest & { sequence: number }) | null = null;
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  let state: MediaTimingFramePickerState = emptyState();
+
+  function emptyState(): MediaTimingFramePickerState {
+    return { enabled: false, manual: false, loading: false, message: '', blockConfirm: false };
+  }
+
+  function publish(): void {
+    options.onChange({ ...state });
+  }
+
+  async function drain(): Promise<void> {
+    if (inFlight || !pending) return;
+    const request = pending;
+    pending = null;
+    inFlight = true;
+    try {
+      const result = await options.load(request);
+      if (reviewId !== request.reviewId || sequence !== request.sequence) return;
+      if (result.stale) {
+        options.onStale();
+        return;
+      }
+      if (
+        !result.ok ||
+        !Number.isFinite(result.timestamp) ||
+        !result.dataUrl?.startsWith('data:image/jpeg;base64,')
+      ) {
+        throw new Error(result.message ?? 'Screenshot preview is unavailable.');
+      }
+      state.timestamp = result.timestamp;
+      state.dataUrl = result.dataUrl;
+      state.blockConfirm = false;
+      state.message = state.manual
+        ? 'Selected frame stays fixed when you trim audio.'
+        : 'Following the audio midpoint.';
+    } catch (error) {
+      if (reviewId !== request.reviewId || sequence !== request.sequence) return;
+      state.message = error instanceof Error ? error.message : 'Screenshot preview is unavailable.';
+      state.blockConfirm = state.manual;
+    } finally {
+      inFlight = false;
+      if (reviewId === request.reviewId && sequence === request.sequence) {
+        state.loading = false;
+        publish();
+      }
+      if (timer === null) void drain();
+    }
+  }
+
+  function request(timestamp: number, direction?: -1 | 1): void {
+    if (!reviewId || !state.enabled) return;
+    sequence += 1;
+    pending = { reviewId, timestamp, ...(direction ? { direction } : {}), sequence };
+    state.requestedTime = timestamp;
+    state.loading = true;
+    state.blockConfirm = state.manual;
+    state.message = 'Loading screenshot…';
+    publish();
+    if (timer !== null) clearTimeout(timer);
+    timer = setTimeout(() => {
+      timer = null;
+      void drain();
+    }, options.debounceMs ?? 120);
+  }
+
+  function close(): void {
+    sequence += 1;
+    reviewId = null;
+    pending = null;
+    if (timer !== null) clearTimeout(timer);
+    timer = null;
+    state = emptyState();
+    publish();
+  }
+
+  return {
+    open(id: string, enabled: boolean, time: number) {
+      close();
+      reviewId = id;
+      midpoint = time;
+      state.enabled = enabled;
+      publish();
+      if (enabled) request(time);
+    },
+    updateMidpoint(time: number) {
+      if (midpoint === time) return;
+      midpoint = time;
+      if (!state.manual) request(time);
+    },
+    choose(time: number, direction?: -1 | 1) {
+      if (!Number.isFinite(time) || time < 0) return;
+      state.manual = true;
+      request(time, direction);
+    },
+    reset() {
+      state.manual = false;
+      request(midpoint);
+    },
+    close,
+    getState: () => ({ ...state }),
+    getScreenshotTime: () => (state.manual && !state.blockConfirm ? state.timestamp : undefined),
+  };
+}
diff --git a/src/renderer/modals/media-timing-review.test.ts b/src/renderer/modals/media-timing-review.test.ts
new file mode 100644
index 00000000..ec8ec79d
--- /dev/null
+++ b/src/renderer/modals/media-timing-review.test.ts
@@ -0,0 +1,157 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import {
+  buildMediaTimingLineSelection,
+  buildMediaTimingWaveformPath,
+  constrainMediaTimingSelection,
+  createMediaTimingPreviewRequestGuard,
+  formatMediaTimingTimestamp,
+  mediaTimingTimeFromPointer,
+  slideMediaTimingSelection,
+  trimMediaTimingSelectionEnd,
+} from './media-timing-review';
+
+test('waveform path mirrors normalized peaks around its center line', () => {
+  const path = buildMediaTimingWaveformPath([0, 0.5, 1]);
+
+  assert.match(path, /^M 0\.00 50\.00 L 500\.00 28\.00 L 1000\.00 6\.00/);
+  assert.match(path, /1000\.00 94\.00 L 500\.00 72\.00 L 0\.00 50\.00 Z$/);
+  assert.equal(buildMediaTimingWaveformPath([1]), '');
+});
+
+test('formatMediaTimingTimestamp renders stable review readouts', () => {
+  assert.equal(formatMediaTimingTimestamp(65.4321), '01:05.432');
+  assert.equal(formatMediaTimingTimestamp(65.4321, false), '01:05');
+  assert.equal(formatMediaTimingTimestamp(-1), '00:00.000');
+  assert.equal(formatMediaTimingTimestamp(119.9999), '02:00.000');
+  assert.equal(formatMediaTimingTimestamp(119.6, false), '02:00');
+});
+
+test('selection constraints preserve the handle that did not move', () => {
+  assert.deepEqual(
+    constrainMediaTimingSelection({
+      nextStart: 3,
+      nextEnd: 2,
+      currentStart: 1,
+      timelineStart: 0,
+      timelineEnd: 10,
+      mediaEnd: 10,
+      maxMediaDuration: 30,
+    }),
+    { start: 1.9, end: 2 },
+  );
+  assert.deepEqual(
+    constrainMediaTimingSelection({
+      nextStart: 1,
+      nextEnd: 0.5,
+      currentStart: 1,
+      timelineStart: 0,
+      timelineEnd: 10,
+      mediaEnd: 10,
+      maxMediaDuration: 30,
+    }),
+    { start: 1, end: 1.1 },
+  );
+});
+
+test('pointer positions map onto the visible timeline and clamp past its edges', () => {
+  const track = { trackLeft: 100, trackWidth: 400, timelineStart: 10, timelineEnd: 20 };
+
+  assert.equal(mediaTimingTimeFromPointer({ clientX: 100, ...track }), 10);
+  assert.equal(mediaTimingTimeFromPointer({ clientX: 300, ...track }), 15);
+  assert.equal(mediaTimingTimeFromPointer({ clientX: -40, ...track }), 10);
+  assert.equal(mediaTimingTimeFromPointer({ clientX: 900, ...track }), 20);
+  assert.equal(mediaTimingTimeFromPointer({ ...track, clientX: 300, trackWidth: 0 }), 10);
+});
+
+test('sliding keeps the clip length and stops at the timeline and media bounds', () => {
+  const timeline = { span: 2, timelineStart: 4, timelineEnd: 12, mediaEnd: 10 };
+
+  assert.deepEqual(slideMediaTimingSelection({ nextStart: 6, ...timeline }), { start: 6, end: 8 });
+  assert.deepEqual(slideMediaTimingSelection({ nextStart: 1, ...timeline }), { start: 4, end: 6 });
+  assert.deepEqual(slideMediaTimingSelection({ nextStart: 99, ...timeline }), {
+    start: 8,
+    end: 10,
+  });
+});
+
+test('line selection combines adjacent lines around the mined one and tracks their range', () => {
+  const base = {
+    previousLines: [
+      { text: '一行目', startTime: 0, endTime: 2 },
+      { text: '二行目', startTime: 2.5, endTime: 4 },
+    ],
+    nextLines: [
+      { text: '四行目', startTime: 7.5, endTime: 9 },
+      { text: '五行目', startTime: 9.5, endTime: 11 },
+    ],
+    text: '採掘行',
+    originalStartTime: 5,
+    originalEndTime: 7,
+  };
+
+  const none = buildMediaTimingLineSelection({ ...base, previousCount: 0, nextCount: 0 });
+  assert.deepEqual(none.lineTexts, ['採掘行']);
+  assert.equal(none.currentLineIndex, 0);
+  assert.equal(none.rangeStart, 5);
+  assert.equal(none.rangeEnd, 7);
+
+  const expanded = buildMediaTimingLineSelection({ ...base, previousCount: 1, nextCount: 2 });
+  assert.deepEqual(expanded.lineTexts, ['二行目', '採掘行', '四行目', '五行目']);
+  assert.equal(expanded.currentLineIndex, 1);
+  assert.equal(expanded.sentence, '二行目 採掘行 四行目 五行目');
+  assert.equal(expanded.rangeStart, 2.5);
+  assert.equal(expanded.rangeEnd, 11);
+});
+
+test('preview request guard blocks overlap and invalidates stale responses', () => {
+  const guard = createMediaTimingPreviewRequestGuard();
+  const first = guard.begin();
+
+  assert.equal(typeof first, 'number');
+  assert.equal(guard.begin(), null);
+  assert.equal(guard.isCurrent(first!), true);
+
+  guard.invalidate();
+  assert.equal(guard.isCurrent(first!), false);
+  assert.equal(guard.isInFlight(), false);
+
+  const second = guard.begin();
+  assert.equal(typeof second, 'number');
+  guard.finish(first!);
+  assert.equal(guard.isCurrent(second!), true);
+  guard.finish(second!);
+  assert.equal(guard.isInFlight(), false);
+});
+
+test('trailing silence trim follows the last speech slice and keeps cut-off or silent lines', () => {
+  // 10 slices over a 10 s timeline: one slice per second, speech in seconds 2-4 only.
+  const peaks = [0, 0, 0.9, 0.8, 0.7, 0.1, 0.2, 0, 0, 0];
+  const base = { peaks, timelineStart: 0, timelineEnd: 10, lineStart: 2, lineEnd: 8 };
+
+  const trimmed = trimMediaTimingSelectionEnd({ ...base, selectionEnd: 8, endPadSeconds: 0 });
+  assert.ok(trimmed !== null && Math.abs(trimmed - 5.15) < 1e-9);
+
+  const padded = trimMediaTimingSelectionEnd({ ...base, selectionEnd: 8.5, endPadSeconds: 0.5 });
+  assert.ok(padded !== null && Math.abs(padded - 5.65) < 1e-9);
+
+  // Speech running through the line end means the subtitle cuts the audio off; keep it.
+  assert.equal(
+    trimMediaTimingSelectionEnd({ ...base, lineEnd: 5, selectionEnd: 5, endPadSeconds: 0 }),
+    null,
+  );
+  // No speech inside the line at all: keep the subtitle timing rather than guess.
+  assert.equal(
+    trimMediaTimingSelectionEnd({ ...base, lineStart: 6, selectionEnd: 8, endPadSeconds: 0 }),
+    null,
+  );
+  // A saving below the minimum trim is not worth moving the handle for.
+  assert.equal(
+    trimMediaTimingSelectionEnd({ ...base, lineEnd: 5.2, selectionEnd: 5.2, endPadSeconds: 0 }),
+    null,
+  );
+  assert.equal(
+    trimMediaTimingSelectionEnd({ ...base, peaks: [1], selectionEnd: 8, endPadSeconds: 0 }),
+    null,
+  );
+});
diff --git a/src/renderer/modals/media-timing-review.ts b/src/renderer/modals/media-timing-review.ts
new file mode 100644
index 00000000..52a755b6
--- /dev/null
+++ b/src/renderer/modals/media-timing-review.ts
@@ -0,0 +1,1033 @@
+import { createMediaTimingFramePicker } from './media-timing-frame-picker';
+import type {
+  MediaTimingReviewContextLine,
+  MediaTimingReviewDecision,
+  MediaTimingReviewOpenPayload,
+} from '../../types/anki';
+import type { ModalStateReader, RendererContext } from '../context';
+import { createModalFocusGuard } from './modal-focus-guard';
+
+const MINIMUM_CLIP_SECONDS = 0.1;
+const FINE_ADJUST_SECONDS = 0.1;
+const COARSE_ADJUST_SECONDS = 0.5;
+const TIMELINE_EXPANSION_SECONDS = 2;
+const LINE_REVEAL_MARGIN_SECONDS = 1;
+/**
+ * Subtitles usually linger past the dialogue for readability, so an untouched clip end
+ * follows the last speech-weighted waveform slice above this level (0..1, relative to the
+ * clip's own noise floor) plus a short tail, when that saves at least the minimum trim.
+ */
+const SPEECH_LEVEL_THRESHOLD = 0.3;
+const SPEECH_TAIL_SECONDS = 0.15;
+const MINIMUM_TRAILING_TRIM_SECONDS = 0.1;
+/** Slack past the clip length before the UI gives up waiting for mpv's end-of-clip signal. */
+const PREVIEW_END_GRACE_MS = 2_500;
+
+function clamp(value: number, minimum: number, maximum: number): number {
+  return Math.min(maximum, Math.max(minimum, value));
+}
+
+export function formatMediaTimingTimestamp(seconds: number, includeMilliseconds = true): string {
+  const unitsPerSecond = includeMilliseconds ? 1_000 : 1;
+  const totalUnits = Math.max(0, Math.round(seconds * unitsPerSecond));
+  const unitsPerMinute = 60 * unitsPerSecond;
+  const minutes = Math.floor(totalUnits / unitsPerMinute);
+  const remainingUnits = totalUnits % unitsPerMinute;
+  const remaining = includeMilliseconds
+    ? (remainingUnits / unitsPerSecond).toFixed(3)
+    : String(remainingUnits);
+  return `${String(minutes).padStart(2, '0')}:${remaining.padStart(includeMilliseconds ? 6 : 2, '0')}`;
+}
+
+/**
+ * Resolves which subtitle lines the card sentence currently includes. The counts say
+ * how many adjacent lines were pulled in on each side; the range covers those lines'
+ * subtitle timings so the clip edges can follow them.
+ */
+export function buildMediaTimingLineSelection(options: {
+  previousLines: MediaTimingReviewContextLine[];
+  nextLines: MediaTimingReviewContextLine[];
+  text: string;
+  originalStartTime: number;
+  originalEndTime: number;
+  previousCount: number;
+  nextCount: number;
+}): {
+  lineTexts: string[];
+  currentLineIndex: number;
+  sentence: string;
+  rangeStart: number;
+  rangeEnd: number;
+} {
+  const previous =
+    options.previousCount > 0 ? options.previousLines.slice(-options.previousCount) : [];
+  const next = options.nextCount > 0 ? options.nextLines.slice(0, options.nextCount) : [];
+  const lineTexts = [
+    ...previous.map((line) => line.text),
+    options.text,
+    ...next.map((line) => line.text),
+  ];
+  return {
+    lineTexts,
+    currentLineIndex: previous.length,
+    sentence: lineTexts.join(' '),
+    rangeStart: previous[0]?.startTime ?? options.originalStartTime,
+    rangeEnd: next[next.length - 1]?.endTime ?? options.originalEndTime,
+  };
+}
+
+export function createMediaTimingPreviewRequestGuard() {
+  let sequence = 0;
+  let activeRequestId: number | null = null;
+
+  return {
+    begin(): number | null {
+      if (activeRequestId !== null) return null;
+      sequence += 1;
+      activeRequestId = sequence;
+      return activeRequestId;
+    },
+    invalidate(): void {
+      sequence += 1;
+      activeRequestId = null;
+    },
+    isCurrent(requestId: number): boolean {
+      return requestId === activeRequestId;
+    },
+    finish(requestId: number): void {
+      if (activeRequestId === requestId) activeRequestId = null;
+    },
+    isInFlight(): boolean {
+      return activeRequestId !== null;
+    },
+  };
+}
+
+export function buildMediaTimingWaveformPath(peaks: number[]): string {
+  if (peaks.length < 2) return '';
+  const points = peaks.map((peak, index) => ({
+    x: (index / (peaks.length - 1)) * 1_000,
+    amplitude: clamp(Number.isFinite(peak) ? peak : 0, 0, 1) * 44,
+  }));
+  const upper = points.map(({ x, amplitude }) => `${x.toFixed(2)} ${(50 - amplitude).toFixed(2)}`);
+  const lower = [...points]
+    .reverse()
+    .map(({ x, amplitude }) => `${x.toFixed(2)} ${(50 + amplitude).toFixed(2)}`);
+  return `M ${upper.join(' L ')} L ${lower.join(' L ')} Z`;
+}
+
+/**
+ * Where an untouched clip should end once the waveform is known: just after the line's
+ * last speech slice, plus the configured end padding. Null keeps the subtitle timing when
+ * no speech shows inside the line, when speech runs through the line end (the subtitle is
+ * cutting the audio off, not lingering), or when the saving is too small to matter.
+ */
+export function trimMediaTimingSelectionEnd(options: {
+  peaks: readonly number[];
+  timelineStart: number;
+  timelineEnd: number;
+  lineStart: number;
+  lineEnd: number;
+  selectionEnd: number;
+  endPadSeconds: number;
+}): number | null {
+  const pointCount = options.peaks.length;
+  const span = options.timelineEnd - options.timelineStart;
+  if (pointCount < 2 || span <= 0 || options.lineEnd <= options.lineStart) return null;
+  // Point i covers [i, i + 1) / pointCount of the timeline (see computeWaveformPeaks).
+  const sliceEnd = (index: number): number =>
+    options.timelineStart + ((index + 1) / pointCount) * span;
+  const firstIndex = Math.max(
+    0,
+    Math.floor(((options.lineStart - options.timelineStart) / span) * pointCount),
+  );
+  const lastIndex = Math.min(
+    pointCount - 1,
+    Math.ceil(((options.lineEnd - options.timelineStart) / span) * pointCount) - 1,
+  );
+  let lastSpeechIndex = -1;
+  for (let index = lastIndex; index >= firstIndex; index -= 1) {
+    if ((options.peaks[index] ?? 0) >= SPEECH_LEVEL_THRESHOLD) {
+      lastSpeechIndex = index;
+      break;
+    }
+  }
+  if (lastSpeechIndex === -1 || lastSpeechIndex >= lastIndex) return null;
+  const trimmedEnd = sliceEnd(lastSpeechIndex) + SPEECH_TAIL_SECONDS + options.endPadSeconds;
+  if (options.selectionEnd - trimmedEnd < MINIMUM_TRAILING_TRIM_SECONDS) return null;
+  return trimmedEnd;
+}
+
+export function constrainMediaTimingSelection(options: {
+  nextStart: number;
+  nextEnd: number;
+  currentStart: number;
+  timelineStart: number;
+  timelineEnd: number;
+  mediaEnd: number;
+  maxMediaDuration: number;
+}): { start: number; end: number } {
+  let start = clamp(options.nextStart, options.timelineStart, options.timelineEnd);
+  let end = clamp(options.nextEnd, options.timelineStart, options.timelineEnd);
+  const startMoved = options.nextStart !== options.currentStart;
+  if (end - start < MINIMUM_CLIP_SECONDS) {
+    if (startMoved) start = end - MINIMUM_CLIP_SECONDS;
+    else end = start + MINIMUM_CLIP_SECONDS;
+  }
+  if (options.maxMediaDuration > 0 && end - start > options.maxMediaDuration) {
+    if (startMoved) start = end - options.maxMediaDuration;
+    else end = start + options.maxMediaDuration;
+  }
+  return {
+    start: Math.max(0, start),
+    end: Math.min(options.mediaEnd, end),
+  };
+}
+
+/** Maps a pointer position over the timeline track back onto a media timestamp. */
+export function mediaTimingTimeFromPointer(options: {
+  clientX: number;
+  trackLeft: number;
+  trackWidth: number;
+  timelineStart: number;
+  timelineEnd: number;
+}): number {
+  if (options.trackWidth <= 0) return options.timelineStart;
+  const ratio = clamp((options.clientX - options.trackLeft) / options.trackWidth, 0, 1);
+  return options.timelineStart + ratio * (options.timelineEnd - options.timelineStart);
+}
+
+/** Slides the selection without resizing it, keeping the whole clip inside the visible timeline. */
+export function slideMediaTimingSelection(options: {
+  nextStart: number;
+  span: number;
+  timelineStart: number;
+  timelineEnd: number;
+  mediaEnd: number;
+}): { start: number; end: number } {
+  const latestEnd = Math.min(options.timelineEnd, options.mediaEnd);
+  const maxStart = Math.max(options.timelineStart, latestEnd - options.span);
+  const start = clamp(options.nextStart, options.timelineStart, maxStart);
+  return { start, end: start + options.span };
+}
+
+export function createMediaTimingReviewModal(
+  ctx: RendererContext,
+  options: {
+    modalStateReader: Pick<ModalStateReader, 'isAnyModalOpen'>;
+    syncSettingsModalSubtitleSuppression: () => void;
+  },
+) {
+  let payload: MediaTimingReviewOpenPayload | null = null;
+  let selectionStart = 0;
+  let selectionEnd = 0;
+  let timelineStart = 0;
+  let timelineEnd = 0;
+  let previousCount = 0;
+  let nextCount = 0;
+  let startPadSeconds = 0;
+  let endPadSeconds = 0;
+  /** True until the user moves the clip; the first waveform then trims trailing silence. */
+  let trailingTrimPending = false;
+  let resolveInFlight = false;
+  let previewPlaying = false;
+  let previewTimer: ReturnType<typeof setTimeout> | null = null;
+  let waveformTimer: ReturnType<typeof setTimeout> | null = null;
+  let waveformSequence = 0;
+  let drag: {
+    edge: 'start' | 'end' | 'both';
+    pointerId: number;
+    trackLeft: number;
+    trackWidth: number;
+    grabOffset: number;
+  } | null = null;
+
+  const focus = createModalFocusGuard({
+    isOpen: () => ctx.state.mediaTimingReviewModalOpen,
+    getModalRoot: () => ctx.dom.mediaTimingReviewModal,
+    getPreferredFocusTargets: () => [
+      ctx.dom.mediaTimingReviewStartHandle,
+      ctx.dom.mediaTimingReviewCancelBack,
+    ],
+    getFallbackFocusTarget: () => ctx.dom.mediaTimingReviewCancel,
+    isModalLayer: ctx.platform.isModalLayer,
+  });
+  const previewRequest = createMediaTimingPreviewRequestGuard();
+  const framePicker = createMediaTimingFramePicker({
+    load: (request) => window.electronAPI.getMediaTimingReviewFrame(request),
+    onChange: () => renderFramePicker(),
+    onStale: () => closeResolvedReview(),
+  });
+
+  function renderFramePicker(): void {
+    const state = framePicker.getState();
+    const dom = ctx.dom;
+    dom.mediaTimingReviewFramePicker.classList.toggle('hidden', !state.enabled);
+    dom.mediaTimingReviewFramePicker.setAttribute('aria-busy', String(state.loading));
+    dom.mediaTimingReviewFrameSlider.min = String(timelineStart);
+    dom.mediaTimingReviewFrameSlider.max = String(Math.max(timelineStart, timelineEnd - 0.001));
+    const shownTime = state.loading ? state.requestedTime : state.timestamp;
+    if (shownTime !== undefined) dom.mediaTimingReviewFrameSlider.value = String(shownTime);
+    dom.mediaTimingReviewFrameTime.textContent =
+      shownTime === undefined ? '—' : formatMediaTimingTimestamp(shownTime);
+    dom.mediaTimingReviewFrameSlider.setAttribute(
+      'aria-valuetext',
+      dom.mediaTimingReviewFrameTime.textContent,
+    );
+    dom.mediaTimingReviewFrameStatus.textContent = state.message;
+    dom.mediaTimingReviewFrameImage.classList.toggle('hidden', !state.dataUrl);
+    if (state.dataUrl) dom.mediaTimingReviewFrameImage.src = state.dataUrl;
+    else dom.mediaTimingReviewFrameImage.removeAttribute('src');
+    dom.mediaTimingReviewFramePrevious.disabled =
+      resolveInFlight ||
+      state.loading ||
+      state.timestamp === undefined ||
+      state.timestamp <= timelineStart;
+    dom.mediaTimingReviewFrameNext.disabled =
+      resolveInFlight ||
+      state.loading ||
+      state.timestamp === undefined ||
+      state.timestamp >= timelineEnd - 0.001;
+    dom.mediaTimingReviewFrameSlider.disabled = resolveInFlight;
+    dom.mediaTimingReviewFrameReset.disabled = resolveInFlight || !state.manual;
+    dom.mediaTimingReviewConfirm.disabled = resolveInFlight || state.blockConfirm;
+  }
+
+  function setStatus(message: string, isError = false): void {
+    ctx.dom.mediaTimingReviewStatus.textContent = message;
+    ctx.dom.mediaTimingReviewStatus.classList.toggle('is-error', isError);
+  }
+
+  function clearPreviewTimer(): void {
+    if (previewTimer !== null) clearTimeout(previewTimer);
+    previewTimer = null;
+  }
+
+  /**
+   * Drives the play button label plus the playhead sweep that mirrors the hidden audio player.
+   * mpv reports when the clip actually finishes (see handlePreviewEnded), which accounts for
+   * output latency such as Bluetooth headphones; the timer only covers a player that never does.
+   */
+  function setPreviewPlaying(playing: boolean): void {
+    previewPlaying = playing;
+    ctx.dom.mediaTimingReviewPlayLabel.textContent = playing ? 'Stop preview' : 'Play selection';
+    ctx.dom.mediaTimingReviewPlay.classList.toggle('is-playing', playing);
+    clearPreviewTimer();
+    const track = ctx.dom.mediaTimingReviewSelectionTrack;
+    track.classList.remove('is-previewing');
+    if (!playing) return;
+    const clipSeconds = Math.max(MINIMUM_CLIP_SECONDS, selectionEnd - selectionStart);
+    track.style.setProperty('--playhead-duration', `${clipSeconds}s`);
+    void track.offsetWidth;
+    track.classList.add('is-previewing');
+    previewTimer = setTimeout(() => stopPreview(), clipSeconds * 1000 + PREVIEW_END_GRACE_MS);
+  }
+
+  /** The hidden player reached the end of the clip and paused itself. */
+  function handlePreviewEnded(reviewId: string): void {
+    if (!payload || payload.reviewId !== reviewId || !previewPlaying) return;
+    setPreviewPlaying(false);
+    setStatus('');
+  }
+
+  /** Callers that need to report a failure set their own status after stopping the preview. */
+  function stopPreview(): void {
+    previewRequest.invalidate();
+    setPreviewPlaying(false);
+    setStatus('');
+    if (payload) {
+      void window.electronAPI.stopMediaTimingReviewPreview(payload.reviewId).catch(() => {});
+    }
+  }
+
+  function renderHandle(handle: HTMLDivElement, value: number): void {
+    handle.setAttribute('aria-valuemin', timelineStart.toFixed(3));
+    handle.setAttribute('aria-valuemax', timelineEnd.toFixed(3));
+    handle.setAttribute('aria-valuenow', value.toFixed(3));
+    handle.setAttribute('aria-valuetext', formatMediaTimingTimestamp(value));
+  }
+
+  function renderSelection(): void {
+    framePicker.updateMidpoint(selectionStart + (selectionEnd - selectionStart) / 2);
+    renderFramePicker();
+    const span = Math.max(MINIMUM_CLIP_SECONDS, timelineEnd - timelineStart);
+    const startPercent = ((selectionStart - timelineStart) / span) * 100;
+    const endPercent = ((selectionEnd - timelineStart) / span) * 100;
+    const lineRange = currentLineSelection();
+    const originalStartPercent = payload
+      ? ((lineRange.rangeStart - timelineStart) / span) * 100
+      : 0;
+    const originalEndPercent = payload ? ((lineRange.rangeEnd - timelineStart) / span) * 100 : 0;
+    ctx.dom.mediaTimingReviewSelectionTrack.style.setProperty(
+      '--selection-start',
+      `${clamp(startPercent, 0, 100)}%`,
+    );
+    ctx.dom.mediaTimingReviewSelectionTrack.style.setProperty(
+      '--selection-end',
+      `${clamp(endPercent, 0, 100)}%`,
+    );
+    ctx.dom.mediaTimingReviewSelectionTrack.style.setProperty(
+      '--original-start',
+      `${clamp(originalStartPercent, 0, 100)}%`,
+    );
+    ctx.dom.mediaTimingReviewSelectionTrack.style.setProperty(
+      '--original-end',
+      `${clamp(originalEndPercent, 0, 100)}%`,
+    );
+    renderHandle(ctx.dom.mediaTimingReviewStartHandle, selectionStart);
+    renderHandle(ctx.dom.mediaTimingReviewEndHandle, selectionEnd);
+    ctx.dom.mediaTimingReviewStartValue.textContent = formatMediaTimingTimestamp(selectionStart);
+    ctx.dom.mediaTimingReviewEndValue.textContent = formatMediaTimingTimestamp(selectionEnd);
+    ctx.dom.mediaTimingReviewDuration.textContent = `${(selectionEnd - selectionStart).toFixed(2)}s`;
+    ctx.dom.mediaTimingReviewTimelineStart.textContent = formatMediaTimingTimestamp(
+      timelineStart,
+      false,
+    );
+    ctx.dom.mediaTimingReviewTimelineEnd.textContent = formatMediaTimingTimestamp(
+      timelineEnd,
+      false,
+    );
+    ctx.dom.mediaTimingReviewShowEarlier.disabled = timelineStart <= 0;
+    ctx.dom.mediaTimingReviewShowLater.disabled =
+      payload?.mediaDuration !== undefined && timelineEnd >= payload.mediaDuration;
+  }
+
+  function setWaveformState(state: 'loading' | 'ready' | 'unavailable'): void {
+    ctx.dom.mediaTimingReviewSelectionTrack.classList.toggle('is-loading', state === 'loading');
+    ctx.dom.mediaTimingReviewSelectionTrack.classList.toggle(
+      'is-waveform-unavailable',
+      state === 'unavailable',
+    );
+    ctx.dom.mediaTimingReviewWaveformLabel.textContent =
+      state === 'loading'
+        ? 'isolating dialogue...'
+        : state === 'ready'
+          ? 'speech-weighted waveform'
+          : 'waveform unavailable';
+  }
+
+  async function loadWaveform(): Promise<void> {
+    if (!payload || !ctx.state.mediaTimingReviewModalOpen) return;
+    waveformSequence += 1;
+    const sequence = waveformSequence;
+    const reviewId = payload.reviewId;
+    const startTime = timelineStart;
+    const endTime = timelineEnd;
+    setWaveformState('loading');
+    ctx.dom.mediaTimingReviewWaveformPath.setAttribute('d', '');
+    try {
+      const result = await window.electronAPI.getMediaTimingReviewWaveform({
+        reviewId,
+        startTime,
+        endTime,
+      });
+      if (
+        sequence !== waveformSequence ||
+        payload?.reviewId !== reviewId ||
+        timelineStart !== startTime ||
+        timelineEnd !== endTime
+      ) {
+        return;
+      }
+      if (!result.ok && result.stale) {
+        closeResolvedReview();
+        return;
+      }
+      const path = result.ok ? buildMediaTimingWaveformPath(result.peaks ?? []) : '';
+      if (!path) {
+        setWaveformState('unavailable');
+        return;
+      }
+      ctx.dom.mediaTimingReviewWaveformPath.setAttribute('d', path);
+      setWaveformState('ready');
+      trimTrailingSilence(result.peaks ?? []);
+    } catch {
+      if (sequence === waveformSequence && payload?.reviewId === reviewId) {
+        setWaveformState('unavailable');
+      }
+    }
+  }
+
+  /**
+   * Moves an untouched clip end back to where the line's dialogue ends. The Line end
+   * rail keeps marking the subtitle timing, and Reset restores it.
+   */
+  function trimTrailingSilence(peaks: readonly number[]): void {
+    if (!payload || !trailingTrimPending || previewPlaying || previewRequest.isInFlight()) {
+      return;
+    }
+    const lineRange = currentLineSelection();
+    const trimmedEnd = trimMediaTimingSelectionEnd({
+      peaks,
+      timelineStart,
+      timelineEnd,
+      lineStart: lineRange.rangeStart,
+      lineEnd: lineRange.rangeEnd,
+      selectionEnd,
+      endPadSeconds,
+    });
+    if (trimmedEnd === null) return;
+    updateSelection(selectionStart, trimmedEnd);
+    setStatus('Clip end moved to where the dialogue ends. Reset restores the subtitle timing.');
+  }
+
+  function queueWaveformLoad(delayMs = 0): void {
+    if (waveformTimer !== null) clearTimeout(waveformTimer);
+    waveformSequence += 1;
+    if (payload && ctx.state.mediaTimingReviewModalOpen) {
+      ctx.dom.mediaTimingReviewWaveformPath.setAttribute('d', '');
+      setWaveformState('loading');
+    }
+    waveformTimer = setTimeout(() => {
+      waveformTimer = null;
+      void loadWaveform();
+    }, delayMs);
+  }
+
+  function currentLineSelection(): ReturnType<typeof buildMediaTimingLineSelection> {
+    return buildMediaTimingLineSelection({
+      previousLines: payload?.previousLines ?? [],
+      nextLines: payload?.nextLines ?? [],
+      text: payload?.text ?? '',
+      originalStartTime: payload?.originalStartTime ?? 0,
+      originalEndTime: payload?.originalEndTime ?? 0,
+      previousCount,
+      nextCount,
+    });
+  }
+
+  function renderSentence(): void {
+    if (!payload) return;
+    const selection = currentLineSelection();
+    ctx.dom.mediaTimingReviewText.replaceChildren(
+      ...selection.lineTexts.map((text, index) => {
+        const line = document.createElement('span');
+        line.className =
+          index === selection.currentLineIndex
+            ? 'media-timing-review-line is-current'
+            : 'media-timing-review-line';
+        line.textContent = text;
+        return line;
+      }),
+    );
+    const total = selection.lineTexts.length;
+    ctx.dom.mediaTimingReviewLineCount.textContent = total === 1 ? '1 line' : `${total} lines`;
+    const hasContext = payload.previousLines.length > 0 || payload.nextLines.length > 0;
+    ctx.dom.mediaTimingReviewLineControls.classList.toggle('hidden', !hasContext);
+    ctx.dom.mediaTimingReviewPrevAdd.disabled = previousCount >= payload.previousLines.length;
+    ctx.dom.mediaTimingReviewPrevRemove.disabled = previousCount <= 0;
+    ctx.dom.mediaTimingReviewNextAdd.disabled = nextCount >= payload.nextLines.length;
+    ctx.dom.mediaTimingReviewNextRemove.disabled = nextCount <= 0;
+  }
+
+  /**
+   * Adds or removes an adjacent subtitle line from the card sentence, then follows the
+   * affected clip edge to the new outermost line while keeping the user's other edge.
+   */
+  function adjustLines(direction: 'previous' | 'next', delta: number): void {
+    if (!payload || resolveInFlight) return;
+    const available =
+      direction === 'previous' ? payload.previousLines.length : payload.nextLines.length;
+    const current = direction === 'previous' ? previousCount : nextCount;
+    const updated = clamp(current + delta, 0, available);
+    if (updated === current) return;
+    if (direction === 'previous') previousCount = updated;
+    else nextCount = updated;
+
+    const selection = currentLineSelection();
+    const mediaEnd = payload.mediaDuration ?? Number.POSITIVE_INFINITY;
+    let timelineChanged = false;
+    let capped = false;
+    if (direction === 'previous') {
+      const target = Math.max(0, selection.rangeStart - startPadSeconds);
+      if (target < timelineStart) {
+        timelineStart = Math.max(0, target - LINE_REVEAL_MARGIN_SECONDS);
+        timelineChanged = true;
+      }
+      updateSelection(target, selectionEnd);
+      capped = selectionStart > target + 0.001;
+    } else {
+      const target = Math.min(mediaEnd, selection.rangeEnd + endPadSeconds);
+      if (target > timelineEnd) {
+        timelineEnd = Math.min(mediaEnd, target + LINE_REVEAL_MARGIN_SECONDS);
+        timelineChanged = true;
+      }
+      updateSelection(selectionStart, target);
+      capped = selectionEnd < target - 0.001;
+    }
+    renderSentence();
+    if (capped && payload.maxMediaDuration > 0) {
+      setStatus(
+        `Clip length is capped at ${payload.maxMediaDuration}s, so the audio cannot cover every added line.`,
+      );
+    }
+    if (timelineChanged) queueWaveformLoad(120);
+  }
+
+  function updateSelection(nextStart: number, nextEnd: number): void {
+    if (!payload) return;
+    const mediaEnd = payload.mediaDuration ?? Number.POSITIVE_INFINITY;
+    const nextSelection = constrainMediaTimingSelection({
+      nextStart,
+      nextEnd,
+      currentStart: selectionStart,
+      timelineStart,
+      timelineEnd,
+      mediaEnd,
+      maxMediaDuration: payload.maxMediaDuration,
+    });
+    selectionStart = nextSelection.start;
+    selectionEnd = nextSelection.end;
+    trailingTrimPending = false;
+    if (previewPlaying || previewRequest.isInFlight()) stopPreview();
+    setStatus('');
+    renderSelection();
+  }
+
+  /** Shifts the whole clip without changing its length. */
+  function moveSelection(nextStart: number): void {
+    if (!payload) return;
+    const slid = slideMediaTimingSelection({
+      nextStart,
+      span: selectionEnd - selectionStart,
+      timelineStart,
+      timelineEnd,
+      mediaEnd: payload.mediaDuration ?? Number.POSITIVE_INFINITY,
+    });
+    updateSelection(slid.start, slid.end);
+  }
+
+  function setEdge(edge: 'start' | 'end', value: number): void {
+    if (edge === 'start') updateSelection(value, selectionEnd);
+    else updateSelection(selectionStart, value);
+  }
+
+  function applyDrag(clientX: number): void {
+    if (!drag) return;
+    const pointerTime = mediaTimingTimeFromPointer({
+      clientX,
+      trackLeft: drag.trackLeft,
+      trackWidth: drag.trackWidth,
+      timelineStart,
+      timelineEnd,
+    });
+    const time = pointerTime - drag.grabOffset;
+    if (drag.edge === 'both') moveSelection(time);
+    else setEdge(drag.edge, time);
+  }
+
+  /**
+   * Grabbing a handle drags that edge, grabbing the highlighted clip slides the whole selection,
+   * and pressing anywhere else snaps the nearest edge to that point and keeps dragging it.
+   */
+  function beginDrag(event: PointerEvent): void {
+    if (!payload || resolveInFlight || drag !== null || event.button !== 0) return;
+    const track = ctx.dom.mediaTimingReviewSelectionTrack;
+    const rect = track.getBoundingClientRect();
+    const pointerTime = mediaTimingTimeFromPointer({
+      clientX: event.clientX,
+      trackLeft: rect.left,
+      trackWidth: rect.width,
+      timelineStart,
+      timelineEnd,
+    });
+    const target = event.target;
+    let edge: 'start' | 'end' | 'both';
+    let grabOffset: number;
+    if (target === ctx.dom.mediaTimingReviewStartHandle) {
+      edge = 'start';
+      grabOffset = pointerTime - selectionStart;
+    } else if (target === ctx.dom.mediaTimingReviewEndHandle) {
+      edge = 'end';
+      grabOffset = pointerTime - selectionEnd;
+    } else if (target === ctx.dom.mediaTimingReviewSelectedRange) {
+      edge = 'both';
+      grabOffset = pointerTime - selectionStart;
+    } else {
+      edge =
+        Math.abs(pointerTime - selectionStart) <= Math.abs(pointerTime - selectionEnd)
+          ? 'start'
+          : 'end';
+      grabOffset = 0;
+    }
+    event.preventDefault();
+    drag = {
+      edge,
+      pointerId: event.pointerId,
+      trackLeft: rect.left,
+      trackWidth: rect.width,
+      grabOffset,
+    };
+    track.setPointerCapture(event.pointerId);
+    ctx.dom.mediaTimingReviewModal.classList.add(edge === 'both' ? 'is-sliding' : 'is-scrubbing');
+    if (edge !== 'both') {
+      const handle =
+        edge === 'start'
+          ? ctx.dom.mediaTimingReviewStartHandle
+          : ctx.dom.mediaTimingReviewEndHandle;
+      handle.focus();
+      if (grabOffset === 0) applyDrag(event.clientX);
+    }
+  }
+
+  function endDrag(event: PointerEvent): void {
+    if (!drag || drag.pointerId !== event.pointerId) return;
+    const track = ctx.dom.mediaTimingReviewSelectionTrack;
+    if (track.hasPointerCapture(event.pointerId)) track.releasePointerCapture(event.pointerId);
+    drag = null;
+    ctx.dom.mediaTimingReviewModal.classList.remove('is-scrubbing', 'is-sliding');
+  }
+
+  function cancelDrag(): void {
+    drag = null;
+    ctx.dom.mediaTimingReviewModal.classList.remove('is-scrubbing', 'is-sliding');
+  }
+
+  function handleEdgeKeydown(event: KeyboardEvent, edge: 'start' | 'end'): void {
+    const step = event.shiftKey ? COARSE_ADJUST_SECONDS : FINE_ADJUST_SECONDS;
+    const current = edge === 'start' ? selectionStart : selectionEnd;
+    if (event.key === 'ArrowLeft' || event.key === 'ArrowDown') setEdge(edge, current - step);
+    else if (event.key === 'ArrowRight' || event.key === 'ArrowUp') setEdge(edge, current + step);
+    else if (event.key === 'Home') setEdge(edge, timelineStart);
+    else if (event.key === 'End') setEdge(edge, timelineEnd);
+    else return;
+    event.preventDefault();
+  }
+
+  function showEditor(): void {
+    ctx.dom.mediaTimingReviewCancelStep.classList.add('hidden');
+    ctx.dom.mediaTimingReviewEditor.classList.remove('hidden');
+    ctx.dom.mediaTimingReviewCancel.classList.remove('hidden');
+  }
+
+  function requestCancel(): void {
+    if (!ctx.state.mediaTimingReviewModalOpen || !payload || resolveInFlight) return;
+    stopPreview();
+    ctx.dom.mediaTimingReviewEditor.classList.add('hidden');
+    ctx.dom.mediaTimingReviewCancel.classList.add('hidden');
+    ctx.dom.mediaTimingReviewCancelStep.classList.remove('hidden');
+    ctx.dom.mediaTimingReviewCancelMessage.textContent =
+      payload.noteId !== undefined
+        ? 'Keep editing, keep this card without media, use its original timing, or delete it.'
+        : 'Keep editing, create this card without media, use its original timing, or do not create it.';
+    ctx.dom.mediaTimingReviewSkipMedia.textContent =
+      payload.noteId !== undefined ? 'Keep without media' : 'Create without media';
+    ctx.dom.mediaTimingReviewDiscard.textContent =
+      payload.noteId !== undefined ? 'Delete card' : "Don't create card";
+    ctx.dom.mediaTimingReviewCancelBack.focus();
+  }
+
+  function closeResolvedReview(): void {
+    if (!ctx.state.mediaTimingReviewModalOpen) return;
+    cancelDrag();
+    clearPreviewTimer();
+    if (waveformTimer !== null) clearTimeout(waveformTimer);
+    waveformTimer = null;
+    waveformSequence += 1;
+    previewPlaying = false;
+    ctx.state.mediaTimingReviewModalOpen = false;
+    ctx.dom.mediaTimingReviewModal.classList.add('hidden');
+    ctx.dom.mediaTimingReviewModal.setAttribute('aria-hidden', 'true');
+    focus.detach();
+    window.electronAPI.notifyOverlayModalClosed('media-timing-review');
+    options.syncSettingsModalSubtitleSuppression();
+    payload = null;
+    framePicker.close();
+    if (!options.modalStateReader.isAnyModalOpen()) {
+      ctx.dom.overlay.classList.remove('interactive');
+      if (ctx.platform.shouldToggleMouseIgnore) {
+        window.electronAPI.setIgnoreMouseEvents(true, { forward: true });
+      }
+    }
+  }
+
+  async function resolveReview(decision: MediaTimingReviewDecision): Promise<void> {
+    if (!payload || resolveInFlight) return;
+    resolveInFlight = true;
+    renderFramePicker();
+    stopPreview();
+    const controls = ctx.dom.mediaTimingReviewModal.querySelectorAll<HTMLButtonElement>('button');
+    controls.forEach((button) => {
+      button.disabled = true;
+    });
+    try {
+      const result = await window.electronAPI.resolveMediaTimingReview({
+        reviewId: payload.reviewId,
+        decision,
+      });
+      if (!result.ok && !result.stale) {
+        setStatus(result.message ?? 'The timing review could not be resolved.', true);
+        showEditor();
+        return;
+      }
+      // A stale review was already settled by main; keeping the modal up would leave
+      // controls that can never succeed over a live mpv window.
+      closeResolvedReview();
+    } catch (error) {
+      setStatus(error instanceof Error ? error.message : String(error), true);
+      showEditor();
+    } finally {
+      resolveInFlight = false;
+      controls.forEach((button) => {
+        button.disabled = false;
+      });
+      renderSelection();
+      renderSentence();
+    }
+  }
+
+  function confirmSelection(): void {
+    if (!payload || framePicker.getState().blockConfirm) return;
+    const screenshotTime = framePicker.getScreenshotTime();
+    const includesAdjacentLines = previousCount > 0 || nextCount > 0;
+    void resolveReview({
+      action: 'confirm',
+      startTime: selectionStart,
+      endTime: selectionEnd,
+      ...(screenshotTime !== undefined ? { screenshotTime } : {}),
+      ...(includesAdjacentLines ? { text: currentLineSelection().sentence } : {}),
+    });
+  }
+
+  async function togglePreview(): Promise<void> {
+    if (!payload || resolveInFlight) return;
+    if (previewPlaying) {
+      stopPreview();
+      return;
+    }
+    const requestId = previewRequest.begin();
+    if (requestId === null) return;
+    const requestedReviewId = payload.reviewId;
+    setStatus('Starting audio preview...');
+    try {
+      const result = await window.electronAPI.previewMediaTimingReview({
+        reviewId: requestedReviewId,
+        startTime: selectionStart,
+        endTime: selectionEnd,
+      });
+      if (!previewRequest.isCurrent(requestId) || payload?.reviewId !== requestedReviewId) {
+        if (result.ok && !previewRequest.isInFlight() && !previewPlaying) {
+          void window.electronAPI.stopMediaTimingReviewPreview(requestedReviewId).catch(() => {});
+        }
+        return;
+      }
+      if (!result.ok && result.stale) {
+        closeResolvedReview();
+        return;
+      }
+      if (!result.ok) {
+        setStatus(result.message ?? 'Audio preview is unavailable.', true);
+        setPreviewPlaying(false);
+        return;
+      }
+      setStatus('Previewing in the hidden audio player.');
+      setPreviewPlaying(true);
+    } catch (error) {
+      if (!previewRequest.isCurrent(requestId) || payload?.reviewId !== requestedReviewId) return;
+      setStatus(
+        `Audio preview unavailable: ${error instanceof Error ? error.message : String(error)}`,
+        true,
+      );
+      setPreviewPlaying(false);
+    } finally {
+      previewRequest.finish(requestId);
+    }
+  }
+
+  function openMediaTimingReviewModal(nextPayload: MediaTimingReviewOpenPayload): void {
+    previewRequest.invalidate();
+    cancelDrag();
+    payload = {
+      ...nextPayload,
+      previousLines: nextPayload.previousLines ?? [],
+      nextLines: nextPayload.nextLines ?? [],
+    };
+    selectionStart = nextPayload.selectionStartTime;
+    selectionEnd = nextPayload.selectionEndTime;
+    timelineStart = nextPayload.timelineStartTime;
+    timelineEnd = nextPayload.timelineEndTime;
+    previousCount = 0;
+    nextCount = 0;
+    startPadSeconds = Math.max(0, nextPayload.originalStartTime - nextPayload.selectionStartTime);
+    endPadSeconds = Math.max(0, nextPayload.selectionEndTime - nextPayload.originalEndTime);
+    trailingTrimPending = true;
+    resolveInFlight = false;
+    setPreviewPlaying(false);
+    ctx.dom.mediaTimingReviewKind.textContent =
+      nextPayload.kind === 'word'
+        ? 'Word card'
+        : nextPayload.kind === 'audio'
+          ? 'Audio card'
+          : 'Sentence card';
+    ctx.dom.mediaTimingReviewKind.dataset.kind = nextPayload.kind;
+    ctx.dom.mediaTimingReviewDiscard.textContent =
+      nextPayload.noteId !== undefined ? 'Delete card' : "Don't create card";
+    setStatus('');
+    showEditor();
+    framePicker.open(
+      nextPayload.reviewId,
+      nextPayload.screenshotEnabled === true,
+      selectionStart + (selectionEnd - selectionStart) / 2,
+    );
+    renderSelection();
+    renderSentence();
+    ctx.state.mediaTimingReviewModalOpen = true;
+    options.syncSettingsModalSubtitleSuppression();
+    ctx.dom.overlay.classList.add('interactive');
+    if (ctx.platform.shouldToggleMouseIgnore) window.electronAPI.setIgnoreMouseEvents(false);
+    ctx.dom.mediaTimingReviewModal.classList.remove('hidden');
+    ctx.dom.mediaTimingReviewModal.setAttribute('aria-hidden', 'false');
+    window.electronAPI.notifyOverlayModalOpened('media-timing-review');
+    focus.attach();
+    focus.requestOverlayFocus();
+    window.focus();
+    focus.enforceModalFocus();
+    queueWaveformLoad();
+  }
+
+  function expandTimeline(direction: 'earlier' | 'later'): void {
+    if (!payload) return;
+    if (direction === 'earlier') {
+      timelineStart = Math.max(0, timelineStart - TIMELINE_EXPANSION_SECONDS);
+    } else {
+      timelineEnd = Math.min(
+        payload.mediaDuration ?? Number.POSITIVE_INFINITY,
+        timelineEnd + TIMELINE_EXPANSION_SECONDS,
+      );
+    }
+    renderSelection();
+    queueWaveformLoad(120);
+  }
+
+  function handleMediaTimingReviewKeydown(event: KeyboardEvent): boolean {
+    if (!ctx.state.mediaTimingReviewModalOpen) return false;
+    if (event.key === 'Escape') {
+      event.preventDefault();
+      if (!ctx.dom.mediaTimingReviewCancelStep.classList.contains('hidden')) showEditor();
+      else requestCancel();
+      return true;
+    }
+    if (
+      event.code === 'Space' &&
+      event.target instanceof Element &&
+      !event.target.closest('button')
+    ) {
+      event.preventDefault();
+      void togglePreview();
+      return true;
+    }
+    if (
+      event.key === 'Enter' &&
+      ctx.dom.mediaTimingReviewCancelStep.classList.contains('hidden') &&
+      !(event.target instanceof Element && event.target.closest('button'))
+    ) {
+      event.preventDefault();
+      confirmSelection();
+      return true;
+    }
+    if (
+      (event.key === 'p' || event.key === 'P' || event.key === 'n' || event.key === 'N') &&
+      ctx.dom.mediaTimingReviewCancelStep.classList.contains('hidden') &&
+      !event.ctrlKey &&
+      !event.metaKey &&
+      !event.altKey
+    ) {
+      event.preventDefault();
+      adjustLines(
+        event.key === 'p' || event.key === 'P' ? 'previous' : 'next',
+        event.shiftKey ? -1 : 1,
+      );
+      return true;
+    }
+    return false;
+  }
+
+  function wireDomEvents(): void {
+    ctx.dom.mediaTimingReviewFrameSlider.addEventListener('input', () => {
+      if (!resolveInFlight) framePicker.choose(Number(ctx.dom.mediaTimingReviewFrameSlider.value));
+    });
+    const stepFrame = (direction: -1 | 1) => {
+      const state = framePicker.getState();
+      if (!resolveInFlight && !state.loading && state.timestamp !== undefined)
+        framePicker.choose(state.timestamp, direction);
+    };
+    ctx.dom.mediaTimingReviewFrameSlider.addEventListener('keydown', (event) => {
+      if (event.key === 'ArrowLeft' || event.key === 'ArrowDown') {
+        event.preventDefault();
+        stepFrame(-1);
+      } else if (event.key === 'ArrowRight' || event.key === 'ArrowUp') {
+        event.preventDefault();
+        stepFrame(1);
+      }
+    });
+    ctx.dom.mediaTimingReviewFramePrevious.addEventListener('click', () => stepFrame(-1));
+    ctx.dom.mediaTimingReviewFrameNext.addEventListener('click', () => stepFrame(1));
+    ctx.dom.mediaTimingReviewFrameReset.addEventListener('click', () => {
+      if (!resolveInFlight) framePicker.reset();
+    });
+    const track = ctx.dom.mediaTimingReviewSelectionTrack;
+    track.addEventListener('pointerdown', beginDrag);
+    track.addEventListener('pointermove', (event) => {
+      if (drag?.pointerId === event.pointerId) applyDrag(event.clientX);
+    });
+    track.addEventListener('pointerup', endDrag);
+    track.addEventListener('pointercancel', endDrag);
+    ctx.dom.mediaTimingReviewStartHandle.addEventListener('keydown', (event) =>
+      handleEdgeKeydown(event, 'start'),
+    );
+    ctx.dom.mediaTimingReviewEndHandle.addEventListener('keydown', (event) =>
+      handleEdgeKeydown(event, 'end'),
+    );
+    ctx.dom.mediaTimingReviewShowEarlier.addEventListener('click', () => expandTimeline('earlier'));
+    ctx.dom.mediaTimingReviewShowLater.addEventListener('click', () => expandTimeline('later'));
+    ctx.dom.mediaTimingReviewStartBack.addEventListener('click', () =>
+      updateSelection(selectionStart - FINE_ADJUST_SECONDS, selectionEnd),
+    );
+    ctx.dom.mediaTimingReviewStartForward.addEventListener('click', () =>
+      updateSelection(selectionStart + FINE_ADJUST_SECONDS, selectionEnd),
+    );
+    ctx.dom.mediaTimingReviewEndBack.addEventListener('click', () =>
+      updateSelection(selectionStart, selectionEnd - FINE_ADJUST_SECONDS),
+    );
+    ctx.dom.mediaTimingReviewEndForward.addEventListener('click', () =>
+      updateSelection(selectionStart, selectionEnd + FINE_ADJUST_SECONDS),
+    );
+    ctx.dom.mediaTimingReviewPlay.addEventListener('click', () => void togglePreview());
+    ctx.dom.mediaTimingReviewReset.addEventListener('click', () => {
+      if (!payload) return;
+      previousCount = 0;
+      nextCount = 0;
+      updateSelection(payload.selectionStartTime, payload.selectionEndTime);
+      renderSentence();
+    });
+    ctx.dom.mediaTimingReviewPrevAdd.addEventListener('click', () => adjustLines('previous', 1));
+    ctx.dom.mediaTimingReviewPrevRemove.addEventListener('click', () =>
+      adjustLines('previous', -1),
+    );
+    ctx.dom.mediaTimingReviewNextAdd.addEventListener('click', () => adjustLines('next', 1));
+    ctx.dom.mediaTimingReviewNextRemove.addEventListener('click', () => adjustLines('next', -1));
+    ctx.dom.mediaTimingReviewCancel.addEventListener('click', requestCancel);
+    ctx.dom.mediaTimingReviewCancelBack.addEventListener('click', showEditor);
+    ctx.dom.mediaTimingReviewUseOriginal.addEventListener(
+      'click',
+      () => void resolveReview({ action: 'use-original' }),
+    );
+    ctx.dom.mediaTimingReviewSkipMedia.addEventListener(
+      'click',
+      () => void resolveReview({ action: 'skip-media' }),
+    );
+    ctx.dom.mediaTimingReviewDiscard.addEventListener(
+      'click',
+      () => void resolveReview({ action: 'discard' }),
+    );
+    ctx.dom.mediaTimingReviewConfirm.addEventListener('click', () => confirmSelection());
+  }
+
+  return {
+    openMediaTimingReviewModal,
+    handlePreviewEnded,
+    requestCancel,
+    handleMediaTimingReviewKeydown,
+    wireDomEvents,
+  };
+}
diff --git a/src/renderer/modals/session-help-sections.ts b/src/renderer/modals/session-help-sections.ts
index 513eafb6..3d740146 100644
--- a/src/renderer/modals/session-help-sections.ts
+++ b/src/renderer/modals/session-help-sections.ts
@@ -225,6 +225,10 @@ function describeSessionAction(
       return 'Open jimaku';
     case 'openTsukihime':
       return 'Open TsukiHime';
+    case 'openSubtitleSelection':
+      return 'Select subtitle tracks';
+    case 'openSubtitleGeneration':
+      return 'Generate Japanese subtitles';
     case 'openYoutubePicker':
       return 'Open YouTube subtitle picker';
     case 'openPlaylistBrowser':
@@ -266,6 +270,8 @@ function sectionForSessionBinding(binding: CompiledSessionBinding): string {
     case 'openJimaku':
     case 'openTsukihime':
     case 'openCharacterDictionaryManager':
+    case 'openSubtitleSelection':
+    case 'openSubtitleGeneration':
     case 'openControllerSelect':
     case 'openControllerDebug':
     case 'openYoutubePicker':
diff --git a/src/renderer/modals/subtitle-generation-view.test.ts b/src/renderer/modals/subtitle-generation-view.test.ts
new file mode 100644
index 00000000..87908449
--- /dev/null
+++ b/src/renderer/modals/subtitle-generation-view.test.ts
@@ -0,0 +1,114 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import {
+  describeGenerationModel,
+  describeGenerationProgress,
+  describeGenerationRecommendation,
+  describeGenerationTools,
+  describeGenerationVad,
+} from './subtitle-generation-view';
+
+test('only confirmed NVIDIA CUDA support recommends turbo', () => {
+  assert.deepEqual(describeGenerationRecommendation({ kind: 'unavailable' }), {
+    model: 'small',
+    text: 'NVIDIA CUDA acceleration was not confirmed. small is recommended.',
+  });
+  assert.deepEqual(
+    describeGenerationRecommendation({ kind: 'nvidia-cuda', gpuName: 'NVIDIA RTX 5070 Ti' }),
+    {
+      model: 'large-v3-turbo',
+      text: 'NVIDIA CUDA is available with NVIDIA RTX 5070 Ti. large-v3-turbo is recommended.',
+    },
+  );
+});
+
+test('missing tools block generation and list every install instruction', () => {
+  const found = { kind: 'found', path: '/usr/bin/tool' } as const;
+  assert.deepEqual(
+    describeGenerationTools({ ffmpeg: found, ffprobe: found, whisper: found, vad: null }),
+    {
+      ready: true,
+      text: 'whisper.cpp and FFmpeg are installed.',
+    },
+  );
+  assert.deepEqual(
+    describeGenerationTools({
+      ffmpeg: { kind: 'missing', message: 'ffmpeg was not found on PATH.' },
+      ffprobe: found,
+      whisper: found,
+      vad: { kind: 'missing', message: 'whisper-vad-speech-segments was not found on PATH.' },
+    }),
+    {
+      ready: false,
+      text: 'ffmpeg was not found on PATH. whisper-vad-speech-segments was not found on PATH.',
+    },
+  );
+});
+
+test('only a missing managed model offers a download', () => {
+  assert.deepEqual(describeGenerationModel({ kind: 'missing', path: '/models/small.bin' }), {
+    ready: false,
+    download: true,
+    text: 'Download a speech model to get started.',
+  });
+  for (const kind of ['managed', 'external'] as const) {
+    const model = describeGenerationModel({ kind, path: '/models/ggml-small.bin' });
+    assert.equal(model.ready, true);
+    assert.equal(model.download, false);
+  }
+  assert.deepEqual(
+    describeGenerationModel({
+      kind: 'invalid',
+      path: '/missing/model.bin',
+      message: 'Configured model does not exist.',
+    }),
+    {
+      ready: false,
+      download: false,
+      text: 'Configured model does not exist.',
+    },
+  );
+});
+
+test('generation progress distinguishes measured work from indeterminate stages', () => {
+  assert.deepEqual(
+    describeGenerationProgress({ stage: 'transcribe', percent: 42.8, message: 'Transcribing' }),
+    {
+      stage: 'Recognizing Japanese speech',
+      percent: 42.8,
+      label: '42%',
+    },
+  );
+  assert.deepEqual(describeGenerationProgress({ stage: 'extract', message: 'Extracting audio' }), {
+    stage: 'Preparing audio',
+    percent: null,
+    label: 'Working...',
+  });
+  assert.equal(
+    describeGenerationProgress({ stage: 'download', percent: 0, message: '' }).label,
+    '0%',
+  );
+  assert.equal(
+    describeGenerationProgress({ stage: 'download', percent: Number.NaN, message: '' }).percent,
+    null,
+  );
+  assert.equal(
+    describeGenerationProgress({ stage: 'write', percent: 120, message: '' }).percent,
+    100,
+  );
+});
+
+test('optional speech detection only gates generation when selected', () => {
+  const missing = { kind: 'missing', path: '/vad.bin' } as const;
+  assert.equal(describeGenerationVad({ enabled: false, model: missing }).ready, true);
+  assert.equal(describeGenerationVad({ enabled: false, model: missing }).download, false);
+  assert.equal(describeGenerationVad({ enabled: true, model: missing }).ready, false);
+  assert.equal(describeGenerationVad({ enabled: true, model: missing }).download, true);
+  assert.equal(
+    describeGenerationVad({ enabled: true, model: { kind: 'managed', path: '/vad.bin' } }).ready,
+    true,
+  );
+  const invalid = { kind: 'invalid', path: '/vad.bin', message: 'Cannot read model' } as const;
+  assert.equal(describeGenerationVad({ enabled: true, model: invalid }).download, false);
+  assert.equal(describeGenerationVad({ enabled: false, model: invalid }).ready, true);
+});
diff --git a/src/renderer/modals/subtitle-generation-view.ts b/src/renderer/modals/subtitle-generation-view.ts
new file mode 100644
index 00000000..b03fd0f5
--- /dev/null
+++ b/src/renderer/modals/subtitle-generation-view.ts
@@ -0,0 +1,82 @@
+import {
+  missingSubtitleGenerationTools,
+  recommendedSubtitleGenerationModel,
+  type SubtitleGenerationAcceleration,
+  type SubtitleGenerationModelStatus,
+  type SubtitleGenerationProgress,
+  type SubtitleGenerationTools,
+} from '../../shared/subtitle-generation';
+import type { SubtitleGenerationStatus } from '../../shared/subtitle-generation-ipc';
+
+export function describeGenerationRecommendation(acceleration: SubtitleGenerationAcceleration) {
+  return {
+    model: recommendedSubtitleGenerationModel(acceleration),
+    text:
+      acceleration.kind === 'nvidia-cuda'
+        ? `NVIDIA CUDA is available with ${acceleration.gpuName}. large-v3-turbo is recommended.`
+        : 'NVIDIA CUDA acceleration was not confirmed. small is recommended.',
+  };
+}
+
+export function describeGenerationTools(tools: SubtitleGenerationTools) {
+  const missing = missingSubtitleGenerationTools(tools);
+  if (missing.length > 0) return { ready: false, text: missing.join(' ') };
+  return {
+    ready: true,
+    text: tools.vad
+      ? 'whisper.cpp, its speech detector, and FFmpeg are installed.'
+      : 'whisper.cpp and FFmpeg are installed.',
+  };
+}
+
+export function describeGenerationVad(vad: SubtitleGenerationStatus['vad']) {
+  const model = describeGenerationModel(vad.model);
+  return {
+    ready: !vad.enabled || model.ready,
+    download: vad.enabled && model.download,
+    text: !vad.enabled
+      ? 'Optional. Generate from the full audio when unchecked.'
+      : vad.model.kind === 'missing'
+        ? 'Download the speech detection model to focus on spoken dialogue.'
+        : vad.model.kind === 'invalid'
+          ? vad.model.message
+          : vad.model.kind === 'external'
+            ? `Your speech detection model: ${vad.model.path}`
+            : 'Silero speech detection model installed.',
+  };
+}
+
+export function describeGenerationModel(model: SubtitleGenerationModelStatus) {
+  switch (model.kind) {
+    case 'external':
+      return { ready: true, download: false, text: `Your model: ${model.path}` };
+    case 'managed':
+      return { ready: true, download: false, text: `SubMiner model: ${model.path}` };
+    case 'missing':
+      return { ready: false, download: true, text: 'Download a speech model to get started.' };
+    case 'invalid':
+      return { ready: false, download: false, text: model.message };
+    default: {
+      const exhaustive: never = model;
+      return exhaustive;
+    }
+  }
+}
+
+const STAGE_LABELS = {
+  download: 'Downloading speech model',
+  extract: 'Preparing audio',
+  transcribe: 'Recognizing Japanese speech',
+  write: 'Saving subtitles',
+} satisfies Record<SubtitleGenerationProgress['stage'], string>;
+
+export function describeGenerationProgress(progress: SubtitleGenerationProgress | null) {
+  const raw = progress?.percent;
+  const percent =
+    raw !== undefined && Number.isFinite(raw) ? Math.max(0, Math.min(100, raw)) : null;
+  return {
+    stage: progress ? STAGE_LABELS[progress.stage] : 'Preparing',
+    percent,
+    label: percent === null ? 'Working...' : `${Math.floor(percent)}%`,
+  };
+}
diff --git a/src/renderer/modals/subtitle-generation.ts b/src/renderer/modals/subtitle-generation.ts
new file mode 100644
index 00000000..fb4fcffa
--- /dev/null
+++ b/src/renderer/modals/subtitle-generation.ts
@@ -0,0 +1,336 @@
+import type { SubtitleGenerationProgress } from '../../shared/subtitle-generation';
+import {
+  SUBTITLE_GENERATION_MODELS,
+  formatSubtitleGenerationModelSize,
+  getSubtitleGenerationModel,
+  isSubtitleGenerationModelId,
+} from '../../shared/subtitle-generation-model-catalog';
+import type {
+  SubtitleGenerationResult,
+  SubtitleGenerationStatus,
+} from '../../shared/subtitle-generation-ipc';
+import type { ModalStateReader, RendererContext } from '../context';
+import { syncOverlayMouseIgnoreState } from '../overlay-mouse-ignore';
+import { createModalFocusGuard } from './modal-focus-guard';
+import {
+  describeGenerationModel,
+  describeGenerationProgress,
+  describeGenerationRecommendation,
+  describeGenerationTools,
+  describeGenerationVad,
+} from './subtitle-generation-view';
+import { SUBTITLE_GENERATION_VAD_MODEL } from '../../shared/subtitle-generation-vad-model';
+
+function element<T extends HTMLElement>(id: string, constructor: new () => T): T {
+  const node = document.getElementById(id);
+  if (!(node instanceof constructor)) throw new Error(`Missing subtitle generation element: ${id}`);
+  return node;
+}
+
+export function createSubtitleGenerationModal(
+  ctx: RendererContext,
+  options: {
+    modalStateReader: Pick<ModalStateReader, 'isAnyModalOpen'>;
+    syncSettingsModalSubtitleSuppression: () => void;
+  },
+) {
+  const dom = {
+    modal: element('subtitleGenerationModal', HTMLDivElement),
+    close: element('subtitleGenerationClose', HTMLButtonElement),
+    open: element('subtitleGenerationOpen', HTMLButtonElement),
+    media: element('subtitleGenerationMedia', HTMLDivElement),
+    tools: element('subtitleGenerationTools', HTMLDivElement),
+    model: element('subtitleGenerationModel', HTMLDivElement),
+    modelPicker: element('subtitleGenerationModelPicker', HTMLDivElement),
+    modelSelect: element('subtitleGenerationModelSelect', HTMLSelectElement),
+    modelDescription: element('subtitleGenerationModelDescription', HTMLParagraphElement),
+    download: element('subtitleGenerationDownload', HTMLButtonElement),
+    vadEnabled: element('subtitleGenerationVadEnabled', HTMLInputElement),
+    vadModel: element('subtitleGenerationVadModel', HTMLDivElement),
+    vadDownload: element('subtitleGenerationVadDownload', HTMLButtonElement),
+    activity: element('subtitleGenerationActivity', HTMLDivElement),
+    stage: element('subtitleGenerationStage', HTMLSpanElement),
+    percent: element('subtitleGenerationPercent', HTMLSpanElement),
+    progress: element('subtitleGenerationProgress', HTMLProgressElement),
+    status: element('subtitleGenerationStatus', HTMLDivElement),
+    refresh: element('subtitleGenerationRefresh', HTMLButtonElement),
+    cancel: element('subtitleGenerationCancel', HTMLButtonElement),
+    start: element('subtitleGenerationStart', HTMLButtonElement),
+  };
+  let snapshot: SubtitleGenerationStatus | null = null;
+  let progress: SubtitleGenerationProgress | null = null;
+  let result: SubtitleGenerationResult | null = null;
+  let pending = false;
+  let cancelling = false;
+  let checking = false;
+  let error: string | null = null;
+  let priorFocus: Element | null = null;
+  let poll: ReturnType<typeof setTimeout> | null = null;
+  let unsubscribe: (() => void) | null = null;
+  for (const model of SUBTITLE_GENERATION_MODELS) {
+    const option = document.createElement('option');
+    option.value = model.id;
+    option.textContent = `${model.id} · ${formatSubtitleGenerationModelSize(model.size)}`;
+    dom.modelSelect.append(option);
+  }
+
+  const focus = createModalFocusGuard({
+    isOpen: () => ctx.state.subtitleGenerationModalOpen,
+    getModalRoot: () => dom.modal,
+    getPreferredFocusTargets: () => [dom.modelSelect, dom.download, dom.start],
+    getFallbackFocusTarget: () => dom.close,
+    isModalLayer: ctx.platform.isModalLayer,
+  });
+
+  function render(): void {
+    const busy = pending || Boolean(snapshot?.running);
+    const model = snapshot ? describeGenerationModel(snapshot.model) : null;
+    const vad = snapshot ? describeGenerationVad(snapshot.vad) : null;
+    const tools = snapshot ? describeGenerationTools(snapshot.tools) : null;
+    const readyMessage = !snapshot?.mediaPath
+      ? 'Open local media to generate subtitles.'
+      : !tools?.ready
+        ? 'Install the missing tools or set their paths in Settings, then click Check again.'
+        : !model?.ready
+          ? 'Set up a speech model to continue.'
+          : !vad?.ready
+            ? 'Download the speech detection model or uncheck Focus on spoken dialogue.'
+            : 'Ready when you are.';
+    dom.media.textContent = snapshot?.mediaPath ?? 'Open a local media file in the player first.';
+    dom.tools.textContent = tools?.text ?? 'Checking local tools...';
+    dom.model.textContent = model?.text ?? 'Checking local models...';
+    dom.modelPicker.classList.toggle('hidden', !snapshot || Boolean(snapshot.externalModelPath));
+    dom.modelSelect.disabled = busy || checking || !snapshot || Boolean(snapshot.externalModelPath);
+    if (snapshot) {
+      const recommendation = describeGenerationRecommendation(snapshot.acceleration);
+      for (const option of dom.modelSelect.options) {
+        if (!isSubtitleGenerationModelId(option.value)) continue;
+        const model = getSubtitleGenerationModel(option.value);
+        const recommended = model.id === recommendation.model ? ' (recommended)' : '';
+        option.textContent = `${model.id}${recommended} · ${formatSubtitleGenerationModelSize(model.size)}`;
+      }
+      dom.modelSelect.value = snapshot.managedModel;
+      dom.modelDescription.textContent = `${getSubtitleGenerationModel(snapshot.managedModel).description} ${recommendation.text}`;
+    }
+    dom.download.classList.toggle('hidden', !model?.download);
+    dom.download.textContent = snapshot
+      ? `Download ${snapshot.managedModel} model`
+      : 'Download model';
+    dom.download.disabled = busy || checking;
+    if (!checking) dom.vadEnabled.checked = snapshot?.vad.enabled ?? false;
+    dom.vadEnabled.disabled = busy || checking || !snapshot;
+    dom.vadModel.textContent = vad?.text ?? 'Checking speech detection...';
+    dom.vadDownload.classList.toggle('hidden', !vad?.download);
+    dom.vadDownload.textContent = `Download speech detection model · ${formatSubtitleGenerationModelSize(SUBTITLE_GENERATION_VAD_MODEL.size)}`;
+    dom.vadDownload.disabled = busy || checking;
+    dom.start.disabled =
+      busy || checking || !tools?.ready || !model?.ready || !vad?.ready || !snapshot?.mediaPath;
+    dom.refresh.disabled = busy || checking;
+    dom.cancel.classList.toggle('hidden', !busy);
+    dom.cancel.disabled = cancelling;
+    dom.cancel.textContent = cancelling ? 'Cancelling...' : 'Cancel';
+    dom.activity.classList.toggle('hidden', !busy);
+    const activity = describeGenerationProgress(progress);
+    dom.stage.textContent = activity.stage;
+    dom.percent.textContent = activity.label;
+    if (activity.percent === null) dom.progress.removeAttribute('value');
+    else dom.progress.value = activity.percent;
+    dom.status.classList.toggle('error', Boolean(error || (!busy && result && !result.ok)));
+    dom.status.textContent =
+      error ??
+      (busy
+        ? cancelling
+          ? 'Stopping the current operation...'
+          : (progress?.message ?? 'Starting...')
+        : (result?.message ?? (checking ? 'Checking local setup...' : readyMessage)));
+  }
+
+  function stopPolling(): void {
+    if (poll !== null) clearTimeout(poll);
+    poll = null;
+  }
+
+  async function refresh(): Promise<void> {
+    if (checking) return;
+    checking = true;
+    error = null;
+    render();
+    try {
+      snapshot = await window.electronAPI.getSubtitleGenerationStatus();
+      if (!pending) {
+        progress = snapshot.progress;
+        result = snapshot.lastResult ?? result;
+      }
+    } catch (cause) {
+      error = cause instanceof Error ? cause.message : 'Could not check subtitle generation setup.';
+    } finally {
+      checking = false;
+      render();
+      stopPolling();
+      if (ctx.state.subtitleGenerationModalOpen && snapshot?.running && !pending) {
+        poll = setTimeout(() => void refresh(), 1500);
+      }
+    }
+  }
+
+  async function run(action: 'download' | 'download-vad' | 'generate'): Promise<void> {
+    if (pending || snapshot?.running || checking || !snapshot) return;
+    const model = describeGenerationModel(snapshot.model);
+    const vad = describeGenerationVad(snapshot.vad);
+    const tools = describeGenerationTools(snapshot.tools);
+    if (
+      action === 'download'
+        ? !model.download
+        : action === 'download-vad'
+          ? !vad.download
+          : !tools.ready || !model.ready || !vad.ready || !snapshot.mediaPath
+    )
+      return;
+    pending = true;
+    result = null;
+    error = null;
+    progress = { stage: action === 'generate' ? 'extract' : 'download', message: 'Starting...' };
+    render();
+    try {
+      result = await (action === 'download'
+        ? window.electronAPI.downloadSubtitleGenerationModel()
+        : action === 'download-vad'
+          ? window.electronAPI.downloadSubtitleGenerationVadModel()
+          : window.electronAPI.startSubtitleGeneration());
+    } catch (cause) {
+      result = {
+        ok: false,
+        message: cause instanceof Error ? cause.message : 'Subtitle generation failed.',
+      };
+    } finally {
+      pending = false;
+      cancelling = false;
+      // Recheck model availability after downloads and recover controls after errors.
+      await refresh();
+    }
+  }
+
+  async function selectModel(): Promise<void> {
+    const model = dom.modelSelect.value;
+    if (pending || snapshot?.running || checking || !isSubtitleGenerationModelId(model)) return;
+    checking = true;
+    error = null;
+    render();
+    try {
+      snapshot = await window.electronAPI.selectSubtitleGenerationModel(model);
+      result = snapshot.lastResult;
+      progress = snapshot.progress;
+    } catch (cause) {
+      error = cause instanceof Error ? cause.message : 'Could not select the model.';
+    } finally {
+      checking = false;
+      render();
+    }
+  }
+
+  async function selectVad(): Promise<void> {
+    if (pending || snapshot?.running || checking || !snapshot) return;
+    const enabled = dom.vadEnabled.checked;
+    checking = true;
+    error = null;
+    render();
+    try {
+      snapshot = await window.electronAPI.setSubtitleGenerationVadEnabled(enabled);
+      result = snapshot.lastResult;
+      progress = snapshot.progress;
+    } catch (cause) {
+      error = cause instanceof Error ? cause.message : 'Could not change speech detection.';
+    } finally {
+      checking = false;
+      render();
+    }
+  }
+
+  async function cancel(): Promise<void> {
+    if (cancelling) return;
+    cancelling = true;
+    render();
+    try {
+      await window.electronAPI.cancelSubtitleGeneration();
+      await refresh();
+    } catch (cause) {
+      error = cause instanceof Error ? cause.message : 'Could not cancel the operation.';
+    } finally {
+      cancelling = false;
+      render();
+    }
+  }
+
+  function open(): void {
+    if (ctx.state.subtitleGenerationModalOpen) return;
+    priorFocus = document.activeElement;
+    ctx.state.subtitleGenerationModalOpen = true;
+    options.syncSettingsModalSubtitleSuppression();
+    dom.modal.classList.remove('hidden');
+    dom.modal.setAttribute('aria-hidden', 'false');
+    syncOverlayMouseIgnoreState(ctx);
+    focus.attach();
+    focus.focusFallbackTarget();
+    window.electronAPI.notifyOverlayModalOpened('subtitle-generation');
+    void refresh();
+  }
+
+  function close(): void {
+    if (!ctx.state.subtitleGenerationModalOpen) return;
+    ctx.state.subtitleGenerationModalOpen = false;
+    options.syncSettingsModalSubtitleSuppression();
+    dom.modal.classList.add('hidden');
+    dom.modal.setAttribute('aria-hidden', 'true');
+    focus.detach();
+    stopPolling();
+    window.electronAPI.notifyOverlayModalClosed('subtitle-generation');
+    if (priorFocus instanceof HTMLElement && priorFocus.isConnected)
+      priorFocus.focus({ preventScroll: true });
+    if (!options.modalStateReader.isAnyModalOpen()) syncOverlayMouseIgnoreState(ctx);
+  }
+
+  function handleKeydown(event: KeyboardEvent): boolean {
+    if (!ctx.state.subtitleGenerationModalOpen) return false;
+    if (event.key === 'Escape') {
+      event.preventDefault();
+      close();
+    }
+    return true;
+  }
+
+  function wireDomEvents(): void {
+    dom.close.addEventListener('click', close);
+    dom.open.addEventListener('click', () => {
+      void window.electronAPI
+        .requestSubtitleGenerationOpen()
+        .then((opened) => {
+          if (!opened)
+            ctx.dom.subtitleSidebarStatus.textContent = 'Could not open subtitle generation.';
+        })
+        .catch((cause: unknown) => {
+          ctx.dom.subtitleSidebarStatus.textContent =
+            cause instanceof Error ? cause.message : 'Could not open subtitle generation.';
+        });
+    });
+    dom.download.addEventListener('click', () => void run('download'));
+    dom.vadDownload.addEventListener('click', () => void run('download-vad'));
+    dom.vadEnabled.addEventListener('change', () => void selectVad());
+    dom.modelSelect.addEventListener('change', () => void selectModel());
+    dom.start.addEventListener('click', () => void run('generate'));
+    dom.cancel.addEventListener('click', () => void cancel());
+    dom.refresh.addEventListener('click', () => void refresh());
+    unsubscribe = window.electronAPI.onSubtitleGenerationProgress((update) => {
+      progress = update;
+      render();
+    });
+  }
+
+  function dispose(): void {
+    stopPolling();
+    focus.detach();
+    unsubscribe?.();
+    unsubscribe = null;
+  }
+
+  return { open, close, handleKeydown, wireDomEvents, dispose };
+}
diff --git a/src/renderer/modals/subtitle-selection.ts b/src/renderer/modals/subtitle-selection.ts
new file mode 100644
index 00000000..f9361840
--- /dev/null
+++ b/src/renderer/modals/subtitle-selection.ts
@@ -0,0 +1,172 @@
+import type { SubtitleSelectionState } from '../../shared/subtitle-selection';
+import type { RendererContext } from '../context';
+import { syncOverlayMouseIgnoreState } from '../overlay-mouse-ignore';
+import { createModalFocusGuard } from './modal-focus-guard';
+
+function element<T extends HTMLElement>(id: string, constructor: new () => T): T {
+  const node = document.getElementById(id);
+  if (!(node instanceof constructor)) throw new Error(`Missing subtitle selection element: ${id}`);
+  return node;
+}
+
+export function createSubtitleSelectionModal(
+  ctx: RendererContext,
+  options: { syncSettingsModalSubtitleSuppression: () => void },
+) {
+  const dom = {
+    modal: element('subtitleSelectionModal', HTMLDivElement),
+    primary: element('subtitleSelectionPrimary', HTMLSelectElement),
+    secondary: element('subtitleSelectionSecondary', HTMLSelectElement),
+    status: element('subtitleSelectionStatus', HTMLDivElement),
+    apply: element('subtitleSelectionApply', HTMLButtonElement),
+    close: element('subtitleSelectionClose', HTMLButtonElement),
+  };
+  let snapshot: SubtitleSelectionState | null = null;
+  let generation = 0;
+  let pending = false;
+  let priorFocus: Element | null = null;
+  const focus = createModalFocusGuard({
+    isOpen: () => ctx.state.subtitleSelectionModalOpen,
+    getModalRoot: () => dom.modal,
+    getPreferredFocusTargets: () => [dom.primary, dom.secondary, dom.apply],
+    getFallbackFocusTarget: () => dom.close,
+    isModalLayer: ctx.platform.isModalLayer,
+  });
+
+  function status(message: string, error = false): void {
+    dom.status.textContent = message;
+    dom.status.classList.toggle('error', error);
+  }
+
+  function updateControls(): void {
+    const disabled = pending || !snapshot;
+    dom.primary.disabled = disabled;
+    dom.secondary.disabled = disabled;
+    const duplicate = dom.primary.value !== 'no' && dom.primary.value === dom.secondary.value;
+    dom.apply.disabled = disabled || duplicate;
+    for (const option of dom.secondary.options)
+      option.disabled = option.value !== 'no' && option.value === dom.primary.value;
+  }
+
+  function populate(select: HTMLSelectElement, selected: number | null): void {
+    select.replaceChildren();
+    for (const track of [{ id: null, label: 'None' }, ...(snapshot?.tracks ?? [])]) {
+      const option = document.createElement('option');
+      option.value = track.id === null ? 'no' : String(track.id);
+      option.textContent = track.label;
+      select.append(option);
+    }
+    select.value = selected === null ? 'no' : String(selected);
+  }
+
+  async function refresh(openGeneration: number): Promise<void> {
+    try {
+      const next = await window.electronAPI.getSubtitleSelection();
+      if (generation !== openGeneration || !ctx.state.subtitleSelectionModalOpen) return;
+      snapshot = next;
+      populate(dom.primary, next.primary);
+      populate(dom.secondary, next.secondary);
+      status(
+        next.tracks.length
+          ? 'Choose subtitle tracks, then apply.'
+          : 'No subtitle tracks loaded in this video.',
+      );
+    } catch (cause) {
+      if (generation !== openGeneration || !ctx.state.subtitleSelectionModalOpen) return;
+      status(cause instanceof Error ? cause.message : 'Could not read subtitle tracks.', true);
+    } finally {
+      if (generation === openGeneration && ctx.state.subtitleSelectionModalOpen) {
+        pending = false;
+        updateControls();
+        focus.focusFallbackTarget();
+      }
+    }
+  }
+
+  function open(): void {
+    if (ctx.state.subtitleSelectionModalOpen) return;
+    priorFocus = document.activeElement;
+    snapshot = null;
+    pending = true;
+    generation += 1;
+    populate(dom.primary, null);
+    populate(dom.secondary, null);
+    status('Loading subtitle tracks...');
+    updateControls();
+    ctx.state.subtitleSelectionModalOpen = true;
+    options.syncSettingsModalSubtitleSuppression();
+    dom.modal.classList.remove('hidden');
+    dom.modal.setAttribute('aria-hidden', 'false');
+    syncOverlayMouseIgnoreState(ctx);
+    focus.attach();
+    focus.focusFallbackTarget();
+    window.electronAPI.notifyOverlayModalOpened('subtitle-selection');
+    void refresh(generation);
+  }
+
+  function close(): void {
+    if (!ctx.state.subtitleSelectionModalOpen) return;
+    generation += 1;
+    ctx.state.subtitleSelectionModalOpen = false;
+    options.syncSettingsModalSubtitleSuppression();
+    dom.modal.classList.add('hidden');
+    dom.modal.setAttribute('aria-hidden', 'true');
+    focus.detach();
+    window.electronAPI.notifyOverlayModalClosed('subtitle-selection');
+    syncOverlayMouseIgnoreState(ctx);
+    if (priorFocus instanceof HTMLElement) priorFocus.focus({ preventScroll: true });
+    priorFocus = null;
+  }
+
+  async function apply(): Promise<void> {
+    if (dom.apply.disabled || pending || !snapshot) return;
+    const openGeneration = generation;
+    pending = true;
+    updateControls();
+    status('Applying subtitle tracks...');
+    try {
+      await window.electronAPI.applySubtitleSelection({
+        mediaPath: snapshot.mediaPath,
+        primary: dom.primary.value === 'no' ? null : Number(dom.primary.value),
+        secondary: dom.secondary.value === 'no' ? null : Number(dom.secondary.value),
+      });
+      if (generation === openGeneration) close();
+    } catch (cause) {
+      if (generation === openGeneration)
+        status(cause instanceof Error ? cause.message : 'Could not select subtitle tracks.', true);
+    } finally {
+      if (generation === openGeneration) {
+        pending = false;
+        updateControls();
+      }
+    }
+  }
+
+  function handleKeydown(event: KeyboardEvent): boolean {
+    if (event.key === 'Escape') {
+      event.preventDefault();
+      close();
+    } else if (
+      event.key === 'Enter' &&
+      !(event.target instanceof HTMLSelectElement) &&
+      event.target !== dom.close
+    ) {
+      event.preventDefault();
+      void apply();
+    }
+    return true;
+  }
+
+  function wireDomEvents(): void {
+    dom.close.addEventListener('click', close);
+    dom.apply.addEventListener('click', () => void apply());
+    dom.primary.addEventListener('change', () => {
+      if (dom.primary.value !== 'no' && dom.primary.value === dom.secondary.value)
+        dom.secondary.value = 'no';
+      updateControls();
+    });
+    dom.secondary.addEventListener('change', updateControls);
+  }
+
+  return { open, close, handleKeydown, wireDomEvents, dispose: () => focus.detach() };
+}
diff --git a/src/renderer/modals/subtitle-sidebar-selection.electron-fixture.ts b/src/renderer/modals/subtitle-sidebar-selection.electron-fixture.ts
new file mode 100644
index 00000000..e9d141ad
--- /dev/null
+++ b/src/renderer/modals/subtitle-sidebar-selection.electron-fixture.ts
@@ -0,0 +1,165 @@
+import type { ElectronAPI, SubtitleSidebarSnapshot } from '../../types';
+import { SUBTITLE_DEFAULT_CONFIG } from '../../config/definitions/defaults-subtitle';
+import { CORE_DEFAULT_CONFIG } from '../../config/definitions/defaults-core';
+import { createKeyboardHandlers } from '../handlers/keyboard';
+import { createRendererState } from '../state';
+import { resolveRendererDom } from '../utils/dom';
+import { resolvePlatformInfo } from '../utils/platform';
+import { createSubtitleSidebarModal } from './subtitle-sidebar';
+import {
+  getSubtitleSidebarSelection,
+  wireSubtitleSidebarSelection,
+} from './subtitle-sidebar-selection';
+
+export async function setup() {
+  const commands: unknown[] = [];
+  const snapshot: SubtitleSidebarSnapshot = {
+    sourceKey: 'episode-1:track-1',
+    cues: [
+      { text: '最初の台詞', startTime: 0, endTime: 1 },
+      { text: '同じ台詞\n二行目', startTime: 1, endTime: 2 },
+      { text: '同じ台詞', startTime: 2, endTime: 3 },
+      ...Array.from({ length: 30 }, (_, i) => ({
+        text: `後の台詞${i}`,
+        startTime: i + 3,
+        endTime: i + 4,
+      })),
+    ],
+    currentSubtitle: { text: '最初の台詞', startTime: 0, endTime: 1 },
+    currentTimeSec: 0,
+    config: {
+      ...SUBTITLE_DEFAULT_CONFIG.subtitleSidebar,
+      enabled: true,
+      layout: 'overlay',
+      pauseVideoOnHover: false,
+      autoScroll: true,
+      css: {},
+    },
+  };
+  Object.defineProperty(window, 'electronAPI', {
+    value: {
+      getSubtitleSidebarSnapshot: async () => snapshot,
+      getSessionBindings: async () => [
+        {
+          sourcePath: 'keybindings[0].key',
+          originalKey: 'Space',
+          key: { code: 'Space', modifiers: [] },
+          actionType: 'mpv-command',
+          command: ['cycle', 'pause'],
+        },
+      ],
+      getConfiguredShortcuts: async () => CORE_DEFAULT_CONFIG.shortcuts,
+      getStatsToggleKey: async () => 'Backquote',
+      getMarkWatchedKey: async () => '',
+      copySubtitleSidebarSelection: async (text) => {
+        if (!('copyTestSelection' in window) || typeof window.copyTestSelection !== 'function')
+          throw new Error('Missing test clipboard bridge');
+        window.copyTestSelection(text);
+      },
+      getOverlayLayer: () => 'visible',
+      sendMpvCommand: (command) => {
+        commands.push(command);
+      },
+      setIgnoreMouseEvents: () => {},
+    } satisfies Pick<
+      ElectronAPI,
+      | 'getSubtitleSidebarSnapshot'
+      | 'getSessionBindings'
+      | 'getConfiguredShortcuts'
+      | 'getStatsToggleKey'
+      | 'getMarkWatchedKey'
+      | 'copySubtitleSidebarSelection'
+      | 'getOverlayLayer'
+      | 'sendMpvCommand'
+      | 'setIgnoreMouseEvents'
+    >,
+  });
+  const ctx = {
+    dom: resolveRendererDom(),
+    state: createRendererState(),
+    platform: resolvePlatformInfo(),
+  };
+  const modal = createSubtitleSidebarModal(ctx, {
+    modalStateReader: { isAnyModalOpen: () => false },
+  });
+  modal.wireDomEvents();
+  wireSubtitleSidebarSelection(ctx);
+  const keyboard = createKeyboardHandlers(ctx, {
+    handleRuntimeOptionsKeydown: () => false,
+    handleCharacterDictionaryKeydown: () => false,
+    handleSubsyncKeydown: () => false,
+    handleKikuKeydown: () => false,
+    handleJimakuKeydown: () => false,
+    handleTsukihimeKeydown: () => false,
+    handleYoutubePickerKeydown: () => false,
+    handleMediaTimingReviewKeydown: () => false,
+    handlePlaylistBrowserKeydown: () => false,
+    handleControllerSelectKeydown: () => false,
+    handleControllerDebugKeydown: () => false,
+    handleSessionHelpKeydown: () => false,
+    handleChangelogKeydown: () => false,
+    openSessionHelpModal: () => {},
+    getPlaybackPaused: async () => false,
+  });
+  await keyboard.setupMpvInputForwarding();
+  await modal.openSubtitleSidebarModal();
+  const list = ctx.dom.subtitleSidebarList;
+  list.style.height = '180px';
+  list.style.overflowY = 'auto';
+  const selection = window.getSelection();
+  if (!selection) throw new Error('Native selection unavailable');
+  const textNode = (index: number) => {
+    const node = list.children[index]?.querySelector('.subtitle-sidebar-text')?.firstChild;
+    if (!node) throw new Error(`Missing cue ${index}`);
+    return node;
+  };
+  const select = (backward = false) => {
+    const start = textNode(0);
+    const end = textNode(2);
+    selection.setBaseAndExtent(backward ? end : start, 2, backward ? start : end, 2);
+    document.dispatchEvent(new Event('selectionchange'));
+    return getSubtitleSidebarSelection(list);
+  };
+  // This is the same competing action as the renderer's current-subtitle shortcut.
+  let fallbackCopies = 0;
+  document.addEventListener('keydown', (event) => {
+    if ((event.ctrlKey || event.metaKey) && event.key.toLowerCase() === 'c') fallbackCopies += 1;
+  });
+  return {
+    takeCommands: () => commands.splice(0),
+    cueFocused: () => document.activeElement?.matches('.subtitle-sidebar-item') ?? false,
+    focusCue: () => list.querySelector<HTMLElement>('.subtitle-sidebar-item')?.focus(),
+    select,
+    selected: () => getSubtitleSidebarSelection(list),
+    buttonVisible: () => !ctx.dom.subtitleSidebarCopy.hidden,
+    fallbackCopies: () => fallbackCopies,
+    dragPoints: () =>
+      [0, 2].map((index) => {
+        const range = document.createRange();
+        range.setStart(textNode(index), 2);
+        range.collapse(true);
+        const rect = range.getBoundingClientRect();
+        return { x: Math.round(rect.x), y: Math.round(rect.y + rect.height / 2) };
+      }),
+    clickCopy: () => ctx.dom.subtitleSidebarCopy.click(),
+    clickCue: () => {
+      const before = commands.length;
+      list.children[0]?.dispatchEvent(new MouseEvent('click', { bubbles: true }));
+      return commands.length - before;
+    },
+    updatePlayback: async () => {
+      list.scrollTop = 0;
+      snapshot.currentTimeSec = 25;
+      snapshot.currentSubtitle = { text: '後の台詞22', startTime: 25, endTime: 26 };
+      await modal.refreshSubtitleSidebarSnapshot();
+      return list.scrollTop;
+    },
+    changeSource: async () => {
+      snapshot.sourceKey = 'episode-2:track-1';
+      await modal.refreshSubtitleSidebarSnapshot();
+      return getSubtitleSidebarSelection(list);
+    },
+    clear: () => selection.removeAllRanges(),
+    close: () => modal.closeSubtitleSidebarModal(),
+  };
+}
diff --git a/src/renderer/modals/subtitle-sidebar-selection.test.ts b/src/renderer/modals/subtitle-sidebar-selection.test.ts
new file mode 100644
index 00000000..c8f88059
--- /dev/null
+++ b/src/renderer/modals/subtitle-sidebar-selection.test.ts
@@ -0,0 +1,149 @@
+import assert from 'node:assert/strict';
+import { execFile } from 'node:child_process';
+import { mkdtemp, readFile, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { promisify } from 'node:util';
+import test from 'node:test';
+import { build } from 'esbuild';
+
+// This check opens Electron and uses the clipboard. Keep it out of normal code-only lanes.
+const electronTest =
+  process.env.SUBMINER_ELECTRON_TESTS === '1' &&
+  (process.platform !== 'linux' || process.env.DISPLAY)
+    ? test
+    : test.skip;
+
+electronTest(
+  'sidebar selection copies clean chronological text without seeking or losing context',
+  {
+    timeout: 30_000,
+  },
+  async () => {
+    const dir = await mkdtemp(join(tmpdir(), 'subminer-sidebar-selection-'));
+    await build({
+      entryPoints: [resolve('src/renderer/modals/subtitle-sidebar-selection.electron-fixture.ts')],
+      bundle: true,
+      platform: 'browser',
+      format: 'iife',
+      globalName: 'sidebarTest',
+      outfile: join(dir, 'fixture.js'),
+    });
+    const html = (await readFile('src/renderer/index.html', 'utf8'))
+      .replace(
+        '<script type="module" src="renderer.js"></script>',
+        '<script src="fixture.js"></script>',
+      )
+      .replace(
+        'href="style.css"',
+        `href="${new URL(`file://${resolve('src/renderer/style.css')}`).href}"`,
+      );
+    await writeFile(join(dir, 'index.html'), html);
+    await writeFile(
+      join(dir, 'clipboard.cjs'),
+      'const { clipboard, contextBridge } = require("electron"); contextBridge.exposeInMainWorld("copyTestSelection", text => clipboard.writeText(text));',
+    );
+    await build({
+      entryPoints: [resolve('src/core/services/overlay-window-input.ts')],
+      bundle: true,
+      platform: 'node',
+      format: 'cjs',
+      outfile: join(dir, 'input.cjs'),
+    });
+    await writeFile(
+      join(dir, 'run.cjs'),
+      `
+const { app, BrowserWindow, clipboard } = require('electron');
+const assert = require('node:assert/strict');
+const { handleOverlayWindowBeforeInputEvent } = require('./input.cjs');
+app.setPath('userData', ${JSON.stringify(join(dir, 'user-data'))});
+app.whenReady().then(async () => {
+  const window = new BrowserWindow({ width: 900, height: 700, show: false, webPreferences: { preload: ${JSON.stringify(join(dir, 'clipboard.cjs'))}, sandbox: false } });
+  window.webContents.on('console-message', (_event, details) => {
+    if (details.level === 'error') console.error(details.message);
+  });
+  let intercepted = 0;
+  window.webContents.on('before-input-event', (event, input) => handleOverlayWindowBeforeInputEvent({
+    kind: 'visible', windowVisible: true, input,
+    preventDefault: () => event.preventDefault(),
+    sendKeyboardModeToggleRequested() {}, sendLookupWindowToggleRequested() {}, forwardTabToMpv() {},
+    tryHandleOverlayShortcutLocalFallback(input) {
+      if (input.key.toLowerCase() !== 'c') return false;
+      intercepted++; return true;
+    },
+  }));
+  await window.loadFile(${JSON.stringify(join(dir, 'index.html'))});
+  const run = (code) => window.webContents.executeJavaScript(code, true);
+  await run('sidebarTest.setup().then(checks => { window.checks = checks; })');
+  const expected = { text: 'の台詞\\n\\n同じ台詞\\n二行目\\n\\n同じ', cueCount: 3 };
+  assert.deepEqual(await run('checks.select()'), expected);
+  assert.deepEqual(await run('checks.select(true)'), expected);
+  assert.equal(await run('checks.buttonVisible()'), true);
+  assert.equal(await run('checks.clickCue()'), 0);
+  assert.equal(await run('checks.updatePlayback()'), 0);
+  assert.deepEqual(await run('checks.selected()'), expected);
+  const previousClipboard = clipboard.readText();
+  try {
+    clipboard.writeText('sentinel');
+    window.show(); app.focus({ steal: true }); window.focus(); window.webContents.focus();
+    await new Promise(resolve => setTimeout(resolve, 100));
+    await run('checks.clear()');
+    const [start, end] = await run('checks.dragPoints()');
+    await run('checks.takeCommands()');
+    window.webContents.sendInputEvent({ type: 'mouseDown', ...start, button: 'left', clickCount: 1 });
+    window.webContents.sendInputEvent({ type: 'mouseUp', ...start, button: 'left', clickCount: 1 });
+    assert.deepEqual(await run('checks.takeCommands()'), [['seek', 0.08, 'absolute+exact']]);
+    assert.equal(await run('checks.cueFocused()'), false, 'Click-to-seek releases row focus');
+    assert.equal(await run('checks.selected()'), null);
+    const pressKey = async (keyCode) => {
+      window.webContents.sendInputEvent({ type: 'keyDown', keyCode });
+      window.webContents.sendInputEvent({ type: 'keyUp', keyCode });
+      return run('checks.takeCommands()');
+    };
+    assert.deepEqual(await pressKey('Space'), [['cycle', 'pause']]);
+    await run('checks.focusCue()');
+    assert.deepEqual(await pressKey('Space'), [['cycle', 'pause']]);
+    assert.deepEqual(await pressKey('Enter'), [['seek', 0.08, 'absolute+exact']]);
+    assert.equal(await run('checks.cueFocused()'), true, 'Keyboard activation keeps row focus');
+    window.webContents.sendInputEvent({ type: 'mouseDown', ...start, button: 'left', clickCount: 1 });
+    window.webContents.sendInputEvent({ type: 'mouseMove', ...end, button: 'left' });
+    window.webContents.sendInputEvent({ type: 'mouseUp', ...end, button: 'left', clickCount: 1 });
+    await new Promise(resolve => setTimeout(resolve, 100));
+    assert.deepEqual(await run('checks.selected()'), expected);
+    window.webContents.sendInputEvent({ type: 'keyDown', keyCode: 'C', modifiers: [process.platform === 'darwin' ? 'meta' : 'control'] });
+    window.webContents.sendInputEvent({ type: 'keyUp', keyCode: 'C', modifiers: [process.platform === 'darwin' ? 'meta' : 'control'] });
+    await new Promise(resolve => setTimeout(resolve, 100));
+    assert.equal(intercepted, 0);
+    assert.equal(await run('checks.fallbackCopies()'), 0);
+    assert.equal(clipboard.readText() === expected.text, true, 'Keyboard copies the selected excerpt');
+    clipboard.writeText('sentinel');
+    await run('checks.clickCopy()');
+    await new Promise(resolve => setTimeout(resolve, 100));
+    assert.equal(clipboard.readText() === expected.text, true, 'Button copies the selected excerpt');
+  } finally { clipboard.writeText(previousClipboard); }
+  await run('document.dispatchEvent(new KeyboardEvent("keydown", {key:"Escape", bubbles:true}))');
+  assert.equal(await run('checks.selected()'), null);
+  assert.equal(await run('checks.buttonVisible()'), false);
+  assert.equal(await run('checks.clickCue()'), 1);
+  await run('document.dispatchEvent(new KeyboardEvent("keydown", {key:"c", ctrlKey:true, bubbles:true}))');
+  assert.equal(await run('checks.fallbackCopies()'), 1);
+  await run('checks.select()');
+  assert.equal(await run('checks.changeSource()'), null);
+  await run('checks.select(); checks.close()');
+  assert.equal(await run('checks.selected()'), null);
+  window.destroy();
+  console.log('SIDEBAR_SELECTION_OK');
+  app.quit();
+}).catch(error => { console.error(error); app.exit(1); });
+`,
+    );
+    const env = { ...process.env };
+    delete env.ELECTRON_RUN_AS_NODE;
+    const { stdout } = await promisify(execFile)(
+      resolve('node_modules/.bin/electron'),
+      [join(dir, 'run.cjs')],
+      { env, timeout: 25_000 },
+    );
+    assert.match(stdout, /SIDEBAR_SELECTION_OK/);
+  },
+);
diff --git a/src/renderer/modals/subtitle-sidebar-selection.ts b/src/renderer/modals/subtitle-sidebar-selection.ts
new file mode 100644
index 00000000..07fbabee
--- /dev/null
+++ b/src/renderer/modals/subtitle-sidebar-selection.ts
@@ -0,0 +1,150 @@
+import type { RendererContext } from '../context';
+import { syncOverlayMouseIgnoreState } from '../overlay-mouse-ignore';
+
+function isEditingText(target: EventTarget | null): boolean {
+  return (
+    target instanceof HTMLElement &&
+    (target.isContentEditable ||
+      target instanceof HTMLInputElement ||
+      target instanceof HTMLTextAreaElement)
+  );
+}
+
+function getSelectionRange(list: HTMLElement): Range | null {
+  const selection = list.ownerDocument?.defaultView?.getSelection();
+  if (!selection || selection.isCollapsed || selection.rangeCount === 0) return null;
+  const range = selection.getRangeAt(0);
+  return list.contains(range.startContainer) && list.contains(range.endContainer) ? range : null;
+}
+
+export function hasSubtitleSidebarSelection(list: HTMLElement): boolean {
+  return getSelectionRange(list) !== null;
+}
+
+// Read only dialogue nodes, preserving partial first/last lines and DOM cue order.
+export function getSubtitleSidebarSelection(list: HTMLElement): {
+  text: string;
+  cueCount: number;
+} | null {
+  const range = getSelectionRange(list);
+  if (!range) return null;
+
+  const parts: string[] = [];
+  for (const text of list.querySelectorAll<HTMLElement>('.subtitle-sidebar-text')) {
+    if (!range.intersectsNode(text)) continue;
+    const part = list.ownerDocument.createRange();
+    part.selectNodeContents(text);
+    if (range.compareBoundaryPoints(Range.START_TO_START, part) > 0) {
+      part.setStart(range.startContainer, range.startOffset);
+    }
+    if (range.compareBoundaryPoints(Range.END_TO_END, part) < 0) {
+      part.setEnd(range.endContainer, range.endOffset);
+    }
+    const selectedText = part.toString();
+    if (selectedText.trim()) parts.push(selectedText);
+  }
+  return parts.length > 0 ? { text: parts.join('\n\n'), cueCount: parts.length } : null;
+}
+
+export function clearSubtitleSidebarSelection(list: HTMLElement): void {
+  const selection = list.ownerDocument?.defaultView?.getSelection();
+  if (selection?.anchorNode && list.contains(selection.anchorNode)) {
+    selection.removeAllRanges();
+  }
+}
+
+export function wireSubtitleSidebarSelection(ctx: RendererContext): () => void {
+  const list = ctx.dom.subtitleSidebarList;
+  const button = ctx.dom.subtitleSidebarCopy;
+  const doc = list.ownerDocument;
+  const abort = new AbortController();
+  const { signal } = abort;
+
+  const updateButton = () => {
+    const selected = getSubtitleSidebarSelection(list);
+    button.hidden = !selected;
+    button.textContent = selected
+      ? `Copy ${selected.cueCount} ${selected.cueCount === 1 ? 'line' : 'lines'}`
+      : 'Copy';
+  };
+  const copied = () => {
+    ctx.dom.subtitleSidebarStatus.textContent = 'Selection copied.';
+  };
+  const copySelection = async () => {
+    const selected = getSubtitleSidebarSelection(list);
+    if (!selected) return;
+    try {
+      await window.electronAPI.copySubtitleSidebarSelection(selected.text);
+      copied();
+    } catch {
+      ctx.dom.subtitleSidebarStatus.textContent = 'Could not copy selection. Try again.';
+    }
+  };
+
+  doc.addEventListener('selectionchange', updateButton, { signal });
+  doc.addEventListener(
+    'copy',
+    (event) => {
+      if (!ctx.state.subtitleSidebarModalOpen || isEditingText(event.target)) return;
+      const selected = getSubtitleSidebarSelection(list);
+      if (!selected || !event.clipboardData) return;
+      event.preventDefault();
+      event.clipboardData.setData('text/plain', selected.text);
+      copied();
+    },
+    { signal },
+  );
+  // Capture before modal Escape handling and the current-subtitle copy shortcut.
+  doc.addEventListener(
+    'keydown',
+    (event) => {
+      if (
+        !ctx.state.subtitleSidebarModalOpen ||
+        isEditingText(event.target) ||
+        !getSubtitleSidebarSelection(list)
+      )
+        return;
+      if (event.key === 'Escape') {
+        event.preventDefault();
+        event.stopImmediatePropagation();
+        clearSubtitleSidebarSelection(list);
+        updateButton();
+      } else if (
+        (event.ctrlKey || event.metaKey) &&
+        !event.altKey &&
+        !event.shiftKey &&
+        event.key.toLowerCase() === 'c'
+      ) {
+        event.preventDefault();
+        event.stopImmediatePropagation();
+        void copySelection();
+      }
+    },
+    { capture: true, signal },
+  );
+  button.addEventListener('mousedown', (event) => event.preventDefault(), { signal });
+  button.addEventListener('click', copySelection, { signal });
+  list.addEventListener(
+    'pointerdown',
+    (event) => {
+      if (event.button === 0) {
+        list.dataset.selecting = 'true';
+        list.scrollTo({ top: list.scrollTop, behavior: 'instant' });
+        syncOverlayMouseIgnoreState(ctx);
+      }
+    },
+    { signal },
+  );
+  const stopDragging = () => {
+    delete list.dataset.selecting;
+    syncOverlayMouseIgnoreState(ctx);
+  };
+  doc.addEventListener('pointerup', stopDragging, { signal });
+  doc.addEventListener('pointercancel', stopDragging, { signal });
+  doc.defaultView?.addEventListener('blur', stopDragging, { signal });
+  updateButton();
+  return () => {
+    abort.abort();
+    stopDragging();
+  };
+}
diff --git a/src/renderer/modals/subtitle-sidebar.test.ts b/src/renderer/modals/subtitle-sidebar.test.ts
index f9a46b35..39b8e1ef 100644
--- a/src/renderer/modals/subtitle-sidebar.test.ts
+++ b/src/renderer/modals/subtitle-sidebar.test.ts
@@ -113,6 +113,20 @@ test('findActiveSubtitleCueIndex prefers current subtitle timing over near-futur
   assert.equal(findActiveSubtitleCueIndex(cues, { text: 'previous', startTime: 231 }, 233, 0), 0);
 });
 
+test('findActiveSubtitleCueIndex follows playback through empty subtitle gaps', () => {
+  const cues = [
+    { startTime: 0, endTime: 2, text: 'first' },
+    { startTime: 100, endTime: 102, text: 'later' },
+    { startTime: 105, endTime: 107, text: 'next' },
+  ];
+
+  assert.equal(findActiveSubtitleCueIndex(cues, { text: 'later', startTime: 100 }, 101, 1), 1);
+  assert.equal(findActiveSubtitleCueIndex(cues, { text: '', startTime: 0 }, 103, 1), 2);
+  assert.equal(findActiveSubtitleCueIndex(cues, { text: 'next', startTime: 105 }, 105, 2), 2);
+  assert.equal(findActiveSubtitleCueIndex(cues, { text: '', startTime: 0 }, 108, 2), -1);
+  assert.equal(findActiveSubtitleCueIndex(cues, { text: 'first', startTime: 0 }, 0, 2), 0);
+});
+
 test('subtitle sidebar mining context resolves selected row cue timing', () => {
   const globals = globalThis as typeof globalThis & {
     Element?: unknown;
@@ -239,15 +253,17 @@ test('subtitle sidebar modal opens from snapshot and clicking cue seeks playback
   const modalNotifications: string[] = [];
 
   const snapshot: SubtitleSidebarSnapshot = {
+    sourceKey: 'test-subtitles',
     cues: [
-      { startTime: 1, endTime: 2, text: 'first' },
+      { startTime: 1, endTime: 3.4, text: 'first' },
       { startTime: 3, endTime: 4, text: 'second' },
     ],
     currentSubtitle: {
       text: 'second',
-      startTime: 3,
+      startTime: 3.5,
       endTime: 4,
     },
+    currentTimeSec: 3.5,
     config: {
       enabled: true,
       autoOpen: false,
@@ -361,6 +377,9 @@ test('subtitle sidebar modal opens from snapshot and clicking cue seeks playback
     modal.seekToCue(snapshot.cues[0]!);
     assert.deepEqual(mpvCommands.at(-1), ['seek', 1.08, 'absolute+exact']);
 
+    modal.seekToCue(snapshot.cues[1]!);
+    assert.deepEqual(mpvCommands.at(-1), ['seek', 3.48, 'absolute+exact']);
+
     modal.closeSubtitleSidebarModal();
     assert.deepEqual(visibilityChanges, [true, false]);
     assert.deepEqual(modalNotifications, ['open:subtitle-sidebar', 'close:subtitle-sidebar']);
@@ -370,13 +389,14 @@ test('subtitle sidebar modal opens from snapshot and clicking cue seeks playback
   }
 });
 
-test('subtitle sidebar rows support keyboard activation', async () => {
+test('subtitle sidebar rows seek with Enter and leave Space to playback shortcuts', async () => {
   const globals = globalThis as typeof globalThis & { window?: unknown; document?: unknown };
   const previousWindow = globals.window;
   const previousDocument = globals.document;
   const mpvCommands: Array<Array<string | number>> = [];
 
   const snapshot: SubtitleSidebarSnapshot = {
+    sourceKey: 'test-subtitles',
     cues: [
       { startTime: 1, endTime: 2, text: 'first' },
       { startTime: 3, endTime: 4, text: 'second' },
@@ -465,6 +485,18 @@ test('subtitle sidebar rows support keyboard activation', async () => {
     const keydownListeners = firstRow.listeners.get('keydown') ?? [];
     assert.equal(keydownListeners.length > 0, true);
 
+    mpvCommands.length = 0;
+    let spacePrevented = false;
+    keydownListeners[0]!({
+      key: ' ',
+      preventDefault: () => {
+        spacePrevented = true;
+      },
+    });
+
+    assert.deepEqual(mpvCommands, []);
+    assert.equal(spacePrevented, false);
+
     keydownListeners[0]!({
       key: 'Enter',
       preventDefault: () => {},
@@ -483,6 +515,7 @@ test('subtitle sidebar renders hour-long cue timestamps as HH:MM:SS', async () =
   const previousDocument = globals.document;
 
   const snapshot: SubtitleSidebarSnapshot = {
+    sourceKey: 'test-subtitles',
     cues: [{ startTime: 3665, endTime: 3670, text: 'long cue' }],
     currentSubtitle: {
       text: 'long cue',
@@ -576,6 +609,7 @@ test('subtitle sidebar does not open when the feature is disabled', async () =>
   const previousWindow = globals.window;
   const previousDocument = globals.document;
   const snapshot: SubtitleSidebarSnapshot = {
+    sourceKey: 'test-subtitles',
     cues: [],
     currentSubtitle: {
       text: '',
@@ -672,6 +706,7 @@ test('subtitle sidebar auto-open on startup only opens when enabled and configur
   const previousDocument = globals.document;
 
   let snapshot: SubtitleSidebarSnapshot = {
+    sourceKey: 'test-subtitles',
     cues: [{ startTime: 1, endTime: 2, text: 'first' }],
     currentSubtitle: {
       text: 'first',
@@ -782,6 +817,7 @@ test('subtitle sidebar auto-open restores previously open sidebar after renderer
   const previousDocument = globals.document;
 
   const snapshot: SubtitleSidebarSnapshot = {
+    sourceKey: 'test-subtitles',
     cues: [{ startTime: 1, endTime: 2, text: 'first' }],
     currentSubtitle: {
       text: 'first',
@@ -880,6 +916,7 @@ test('subtitle sidebar refresh closes and clears state when config becomes disab
   const previousDocument = globals.document;
   const bodyClassList = createClassList();
   let snapshot: SubtitleSidebarSnapshot = {
+    sourceKey: 'test-subtitles',
     cues: [{ startTime: 1, endTime: 2, text: 'first' }],
     currentSubtitle: {
       text: 'first',
@@ -1004,6 +1041,7 @@ test('subtitle sidebar keeps nearby repeated cue when subtitle update lacks timi
   const previousDocument = globals.document;
 
   const snapshot: SubtitleSidebarSnapshot = {
+    sourceKey: 'test-subtitles',
     cues: [
       { startTime: 1, endTime: 2, text: 'same' },
       { startTime: 3, endTime: 4, text: 'other' },
@@ -1121,6 +1159,7 @@ test('subtitle sidebar does not regress to previous cue on text-only transition
   const previousDocument = globals.document;
 
   const snapshot: SubtitleSidebarSnapshot = {
+    sourceKey: 'test-subtitles',
     cues: [
       { startTime: 1, endTime: 2, text: 'first' },
       { startTime: 3, endTime: 4, text: 'second' },
@@ -1229,6 +1268,7 @@ test('subtitle sidebar jumps to first resolved active cue, then resumes smooth a
   const previousDocument = globals.document;
 
   let snapshot: SubtitleSidebarSnapshot = {
+    sourceKey: 'test-subtitles',
     cues: Array.from({ length: 12 }, (_, index) => ({
       startTime: index * 2,
       endTime: index * 2 + 1.5,
@@ -1399,6 +1439,7 @@ test('subtitle sidebar polling schedules serialized timeouts instead of interval
   });
 
   const snapshot: SubtitleSidebarSnapshot = {
+    sourceKey: 'test-subtitles',
     cues: [{ startTime: 1, endTime: 2, text: 'first' }],
     currentSubtitle: {
       text: 'first',
@@ -1511,6 +1552,7 @@ test('subtitle sidebar closes and resumes a hover pause', async () => {
   const contentListeners = new Map<string, Array<() => void>>();
 
   const snapshot: SubtitleSidebarSnapshot = {
+    sourceKey: 'test-subtitles',
     cues: [{ startTime: 1, endTime: 2, text: 'first' }],
     currentSubtitle: {
       text: 'first',
@@ -1629,6 +1671,7 @@ test('subtitle sidebar hover pause ignores playback-state IPC failures', async (
   const contentListeners = new Map<string, Array<() => Promise<void> | void>>();
 
   const snapshot: SubtitleSidebarSnapshot = {
+    sourceKey: 'test-subtitles',
     cues: [{ startTime: 1, endTime: 2, text: 'first' }],
     currentSubtitle: {
       text: 'first',
@@ -1748,6 +1791,7 @@ test('subtitle sidebar keeps hover pause while a Yomitan lookup popup remains op
   const windowListeners = new Map<string, Array<() => Promise<void> | void>>();
 
   const snapshot: SubtitleSidebarSnapshot = {
+    sourceKey: 'test-subtitles',
     cues: [{ startTime: 1, endTime: 2, text: 'first' }],
     currentSubtitle: {
       text: 'first',
@@ -1877,6 +1921,7 @@ test('subtitle sidebar embedded layout reserves and releases mpv right margin',
   const mpvCommands: Array<Array<string | number>> = [];
 
   const snapshot: SubtitleSidebarSnapshot = {
+    sourceKey: 'test-subtitles',
     cues: [{ startTime: 1, endTime: 2, text: 'first' }],
     currentSubtitle: {
       text: 'first',
@@ -2036,6 +2081,7 @@ test('subtitle sidebar embedded layout measures reserved width after embedded cl
   const contentClassList = createClassList();
 
   const snapshot: SubtitleSidebarSnapshot = {
+    sourceKey: 'test-subtitles',
     cues: [{ startTime: 1, endTime: 2, text: 'first' }],
     currentSubtitle: {
       text: 'first',
@@ -2157,6 +2203,7 @@ test('subtitle sidebar embedded layout restores macOS and Windows passthrough ou
   const contentListeners = new Map<string, Array<() => void>>();
 
   const snapshot: SubtitleSidebarSnapshot = {
+    sourceKey: 'test-subtitles',
     cues: [{ startTime: 1, endTime: 2, text: 'first' }],
     currentSubtitle: {
       text: 'first',
@@ -2286,6 +2333,7 @@ test('subtitle sidebar overlay layout restores macOS and Windows passthrough out
   const contentListeners = new Map<string, Array<() => void>>();
 
   const snapshot: SubtitleSidebarSnapshot = {
+    sourceKey: 'test-subtitles',
     cues: [{ startTime: 1, endTime: 2, text: 'first' }],
     currentSubtitle: {
       text: 'first',
@@ -2413,6 +2461,7 @@ test('subtitle sidebar overlay layout only stays interactive while focus remains
   const contentListeners = new Map<string, Array<(event?: FocusEvent) => void>>();
 
   const snapshot: SubtitleSidebarSnapshot = {
+    sourceKey: 'test-subtitles',
     cues: [{ startTime: 1, endTime: 2, text: 'first' }],
     currentSubtitle: {
       text: 'first',
@@ -2528,6 +2577,7 @@ test('closing embedded subtitle sidebar recomputes passthrough from remaining su
   const ignoreMouseCalls: Array<[boolean, { forward?: boolean } | undefined]> = [];
 
   const snapshot: SubtitleSidebarSnapshot = {
+    sourceKey: 'test-subtitles',
     cues: [{ startTime: 1, endTime: 2, text: 'first' }],
     currentSubtitle: {
       text: 'first',
@@ -2636,6 +2686,7 @@ test('subtitle sidebar resets embedded mpv margin on startup while closed', asyn
   const mpvCommands: Array<Array<string | number>> = [];
 
   const snapshot: SubtitleSidebarSnapshot = {
+    sourceKey: 'test-subtitles',
     cues: [{ startTime: 1, endTime: 2, text: 'first' }],
     currentSubtitle: {
       text: 'first',
diff --git a/src/renderer/modals/subtitle-sidebar.ts b/src/renderer/modals/subtitle-sidebar.ts
index 4b3364cb..9eab6efe 100644
--- a/src/renderer/modals/subtitle-sidebar.ts
+++ b/src/renderer/modals/subtitle-sidebar.ts
@@ -4,8 +4,13 @@ import type {
   SubtitleMiningContext,
   SubtitleSidebarSnapshot,
 } from '../../types';
+import { subtitleCueListSeekTime } from '../../core/services/subtitle-cue-navigation.js';
 import type { ModalStateReader, RendererContext } from '../context';
 import { syncOverlayMouseIgnoreState } from '../overlay-mouse-ignore.js';
+import {
+  clearSubtitleSidebarSelection,
+  hasSubtitleSidebarSelection,
+} from './subtitle-sidebar-selection.js';
 import {
   YOMITAN_POPUP_HIDDEN_EVENT,
   YOMITAN_POPUP_SHOWN_EVENT,
@@ -14,7 +19,6 @@ import {
 
 const MANUAL_SCROLL_HOLD_MS = 1500;
 const ACTIVE_CUE_LOOKAHEAD_SEC = 0.18;
-const CLICK_SEEK_OFFSET_SEC = 0.08;
 const SNAPSHOT_POLL_INTERVAL_MS = 80;
 const EMBEDDED_SIDEBAR_MIN_WIDTH_PX = 240;
 const EMBEDDED_SIDEBAR_MAX_RATIO = 0.45;
@@ -116,8 +120,12 @@ export function findActiveSubtitleCueIndex(
     return -1;
   }
 
+  // The mpv client maps cleared sub-start to zero. Empty text has no active cue timing.
   const hasCurrentTiming =
-    typeof current?.startTime === 'number' && Number.isFinite(current.startTime);
+    current !== null &&
+    normalizeCueText(current.text).length > 0 &&
+    typeof current.startTime === 'number' &&
+    Number.isFinite(current.startTime);
 
   if (hasCurrentTiming) {
     const timingMatch = cues.findIndex(
@@ -209,6 +217,7 @@ export function createSubtitleSidebarModal(
   let subtitleSidebarYomitanPopupVisible = false;
   let subtitleSidebarPauseHeldByYomitanPopup = false;
   let lastSubtitleSidebarLookupCueIndex = -1;
+  let subtitleSourceKey: string | null = null;
 
   function restoreEmbeddedSidebarPassthrough(): void {
     syncOverlayMouseIgnoreState(ctx);
@@ -392,10 +401,9 @@ export function createSubtitleSidebarModal(
   }
 
   function seekToCue(cue: SubtitleCue): void {
-    const targetTime = Math.min(cue.endTime - 0.01, cue.startTime + CLICK_SEEK_OFFSET_SEC);
     window.electronAPI.sendMpvCommand([
       'seek',
-      Math.max(cue.startTime, targetTime),
+      subtitleCueListSeekTime(ctx.state.subtitleSidebarCues, cue),
       'absolute+exact',
     ]);
   }
@@ -470,6 +478,8 @@ export function createSubtitleSidebarModal(
   ): void {
     if (
       !ctx.state.subtitleSidebarAutoScroll ||
+      ctx.dom.subtitleSidebarList.dataset?.selecting === 'true' ||
+      hasSubtitleSidebarSelection(ctx.dom.subtitleSidebarList) ||
       ctx.state.subtitleSidebarActiveCueIndex < 0 ||
       (!force && ctx.state.subtitleSidebarActiveCueIndex === previousActiveCueIndex) ||
       nowForUiTiming() < ctx.state.subtitleSidebarManualScrollUntilMs
@@ -509,7 +519,7 @@ export function createSubtitleSidebarModal(
       row.setAttribute('role', 'button');
       row.setAttribute('aria-label', getCueRowLabel(cue));
       row.addEventListener('keydown', (event: KeyboardEvent) => {
-        if (event.key !== 'Enter' && event.key !== ' ') {
+        if (event.key !== 'Enter') {
           return;
         }
         event.preventDefault();
@@ -566,8 +576,14 @@ export function createSubtitleSidebarModal(
 
   async function refreshSnapshot(): Promise<SubtitleSidebarSnapshot> {
     const snapshot = await window.electronAPI.getSubtitleSidebarSnapshot();
+    if (snapshot.sourceKey !== subtitleSourceKey) {
+      clearSubtitleSidebarSelection(ctx.dom.subtitleSidebarList);
+      lastSubtitleSidebarLookupCueIndex = -1;
+      subtitleSourceKey = snapshot.sourceKey;
+    }
     applyConfig(snapshot);
     if (!snapshot.config.enabled) {
+      clearSubtitleSidebarSelection(ctx.dom.subtitleSidebarList);
       resumeSubtitleSidebarHoverPause();
       clearSidebarInteractionState();
       ctx.state.subtitleSidebarCues = [];
@@ -587,6 +603,7 @@ export function createSubtitleSidebarModal(
 
     const cuesChanged = !subtitleCueListsEqual(ctx.state.subtitleSidebarCues, snapshot.cues);
     if (cuesChanged) {
+      clearSubtitleSidebarSelection(ctx.dom.subtitleSidebarList);
       ctx.state.subtitleSidebarCues = snapshot.cues;
       if (ctx.state.subtitleSidebarModalOpen) {
         renderCueList();
@@ -671,6 +688,7 @@ export function createSubtitleSidebarModal(
     if (!ctx.state.subtitleSidebarModalOpen) {
       return;
     }
+    clearSubtitleSidebarSelection(ctx.dom.subtitleSidebarList);
     resumeSubtitleSidebarHoverPause();
     clearSidebarInteractionState();
     ctx.state.subtitleSidebarModalOpen = false;
@@ -711,6 +729,7 @@ export function createSubtitleSidebarModal(
       closeSubtitleSidebarModal();
     });
     ctx.dom.subtitleSidebarList.addEventListener('click', (event) => {
+      if (hasSubtitleSidebarSelection(ctx.dom.subtitleSidebarList)) return;
       const target = event.target;
       if (!(target instanceof Element)) {
         return;
@@ -727,6 +746,7 @@ export function createSubtitleSidebarModal(
       if (!cue) {
         return;
       }
+      row.blur();
       seekToCue(cue);
     });
     ctx.dom.subtitleSidebarList.addEventListener('wheel', () => {
diff --git a/src/renderer/modals/tsukihime.test.ts b/src/renderer/modals/tsukihime.test.ts
index 905aca8c..75d7eb20 100644
--- a/src/renderer/modals/tsukihime.test.ts
+++ b/src/renderer/modals/tsukihime.test.ts
@@ -40,13 +40,19 @@ function createElementStub() {
 }
 
 function createListStub() {
-  return {
-    innerHTML: '',
+  const list = {
     children: [] as unknown[],
     appendChild(child: unknown) {
-      this.children.push(child);
+      list.children.push(child);
     },
   };
+  // The modal clears lists through innerHTML before re-rendering.
+  return Object.defineProperty(list, 'innerHTML', {
+    get: () => '',
+    set: () => {
+      list.children.length = 0;
+    },
+  }) as typeof list & { innerHTML: string };
 }
 
 function createTabStub(active: boolean) {
@@ -118,6 +124,7 @@ function createModalHarness(
   files: TsukihimeSubtitleFile[],
   options: {
     secondaryLanguages?: string[];
+    secondaryLanguagesGate?: Promise<void>;
     downloadFile?: (query: unknown) => Promise<unknown>;
     listFiles?: (entryId: number) => Promise<unknown>;
     searchEntries?: (query: unknown) => Promise<unknown>;
@@ -138,7 +145,10 @@ function createModalHarness(
       if (options.downloadFile) return options.downloadFile(query);
       return { ok: true, path: '/tmp/subtitles/episode01.en.ass' };
     },
-    tsukihimeGetSecondaryLanguages: async () => options.secondaryLanguages ?? ['en', 'eng'],
+    tsukihimeGetSecondaryLanguages: async () => {
+      await options.secondaryLanguagesGate;
+      return options.secondaryLanguages ?? ['en', 'eng'];
+    },
     tsukihimeListFiles: async ({ entryId }: { entryId: number }) =>
       options.listFiles ? options.listFiles(entryId) : { ok: true, data: [] },
     tsukihimeSearchEntries: async (query: unknown) =>
@@ -613,3 +623,202 @@ test('renderFiles omits the size detail when the API does not report one', () =>
     harness.restoreGlobals();
   }
 });
+
+const ENGLISH_ONLY_ENTRY = {
+  id: 606713,
+  title: 'english only release',
+  timestamp: null,
+  totalSize: null,
+  numFiles: 1,
+  sublangs: ['en'],
+};
+
+const MULTI_SUB_ENTRY = {
+  id: 12255,
+  title: 'multi-sub release',
+  timestamp: null,
+  totalSize: null,
+  numFiles: 1,
+  sublangs: ['en-US', 'ja'],
+};
+
+const UNLABELED_ENTRY = {
+  id: 12256,
+  title: 'release without langs',
+  timestamp: null,
+  totalSize: null,
+  numFiles: 1,
+  sublangs: [],
+};
+
+function visibleEntryTitles(harness: ModalHarness): string[] {
+  return (harness.entriesList.children as Array<{ textContent: string }>).map(
+    (li) => li.textContent,
+  );
+}
+
+test('Japanese tab lists only releases that carry Japanese subtitles', async () => {
+  const SECOND_JAPANESE_TRACK: TsukihimeSubtitleFile = {
+    ...JAPANESE_TRACK,
+    attachmentId: 1955401,
+    filename: 'episode01.jpn.sdh.ass',
+  };
+  const harness = createModalHarness([], {
+    // Two tracks so the modal does not auto-download a lone match.
+    listFiles: async () => ({ ok: true, data: [JAPANESE_TRACK, SECOND_JAPANESE_TRACK] }),
+  });
+  try {
+    harness.state.currentTsukihimeEntryId = null;
+    harness.state.tsukihimeEntries = [ENGLISH_ONLY_ENTRY, MULTI_SUB_ENTRY, UNLABELED_ENTRY];
+
+    pressKey(harness, 'ArrowRight');
+    assert.deepEqual(visibleEntryTitles(harness), ['multi-sub release']);
+
+    // Enter addresses the visible list, so it must pick the multi-sub release
+    // rather than the hidden first search result.
+    pressKey(harness, 'Enter');
+    await flushAsyncWork();
+    assert.equal(harness.state.currentTsukihimeEntryId, MULTI_SUB_ENTRY.id);
+    assert.equal(harness.status.textContent, 'Select a subtitle track.');
+
+    pressKey(harness, 'ArrowLeft');
+    assert.deepEqual(visibleEntryTitles(harness), [
+      'english only release',
+      'multi-sub release',
+      'release without langs',
+    ]);
+    assert.equal(harness.state.currentTsukihimeEntryId, MULTI_SUB_ENTRY.id);
+    assert.equal(harness.state.selectedTsukihimeEntryIndex, 1);
+  } finally {
+    harness.restoreGlobals();
+  }
+});
+
+test('Japanese tab reports when no release carries Japanese subtitles', () => {
+  const harness = createModalHarness([]);
+  try {
+    harness.state.currentTsukihimeEntryId = null;
+    harness.state.tsukihimeEntries = [ENGLISH_ONLY_ENTRY, UNLABELED_ENTRY];
+
+    pressKey(harness, 'ArrowRight');
+    assert.deepEqual(visibleEntryTitles(harness), []);
+    assert.equal(
+      harness.status.textContent,
+      'No releases with Japanese subtitles. Switch to the English tab.',
+    );
+
+    pressKey(harness, 'ArrowLeft');
+    assert.deepEqual(visibleEntryTitles(harness), [
+      'english only release',
+      'release without langs',
+    ]);
+    assert.equal(harness.status.textContent, 'Select a release.');
+  } finally {
+    harness.restoreGlobals();
+  }
+});
+
+test('search reports when no release carries the secondary language', async () => {
+  const harness = createModalHarness([], {
+    searchEntries: async () => ({
+      ok: true,
+      data: [{ ...MULTI_SUB_ENTRY, sublangs: ['ja'] }],
+    }),
+  });
+  try {
+    harness.state.currentTsukihimeEntryId = null;
+    harness.titleInput.value = 'Futsutsuka na Akujo';
+
+    pressKey(harness, 'Enter');
+    await flushAsyncWork();
+    assert.deepEqual(visibleEntryTitles(harness), []);
+    assert.equal(
+      harness.status.textContent,
+      'No releases with English subtitles. Switch to the Japanese tab.',
+    );
+
+    pressKey(harness, 'ArrowRight');
+    assert.deepEqual(visibleEntryTitles(harness), ['multi-sub release']);
+  } finally {
+    harness.restoreGlobals();
+  }
+});
+
+test('switching to a tab that hides the selected release clears its tracks', () => {
+  const harness = createModalHarness([ENGLISH_TRACK, JAPANESE_TRACK]);
+  try {
+    harness.state.tsukihimeEntries = [ENGLISH_ONLY_ENTRY, MULTI_SUB_ENTRY];
+
+    pressKey(harness, 'ArrowRight');
+    assert.equal(harness.state.currentTsukihimeEntryId, null);
+    assert.deepEqual(harness.state.tsukihimeFiles, []);
+    assert.deepEqual(visibleEntryTitles(harness), ['multi-sub release']);
+    assert.equal(harness.status.textContent, 'Select a release.');
+  } finally {
+    harness.restoreGlobals();
+  }
+});
+
+test('a search waits for the configured secondary languages before filtering', async () => {
+  let openGate!: () => void;
+  const harness = createModalHarness([], {
+    secondaryLanguages: ['de'],
+    secondaryLanguagesGate: new Promise<void>((resolve) => {
+      openGate = resolve;
+    }),
+    searchEntries: async () => ({
+      ok: true,
+      data: [{ ...MULTI_SUB_ENTRY, title: 'german release', sublangs: ['de'] }],
+    }),
+  });
+  try {
+    harness.state.tsukihimeModalOpen = false;
+    harness.modal.openTsukihimeModal();
+    harness.titleInput.value = 'Futsutsuka na Akujo';
+
+    // Searching before the config arrives must not filter against the English
+    // fallback, which would hide this German-only release.
+    pressKey(harness, 'Enter');
+    await flushAsyncWork();
+    assert.deepEqual(visibleEntryTitles(harness), []);
+
+    openGate();
+    await flushAsyncWork();
+
+    assert.deepEqual(visibleEntryTitles(harness), ['german release']);
+  } finally {
+    harness.restoreGlobals();
+  }
+});
+
+test('a search from a prior modal session cannot repopulate a reopened modal', async () => {
+  let openGate!: () => void;
+  const harness = createModalHarness([], {
+    secondaryLanguagesGate: new Promise<void>((resolve) => {
+      openGate = resolve;
+    }),
+    searchEntries: async () => ({ ok: true, data: [MULTI_SUB_ENTRY] }),
+  });
+  try {
+    harness.state.tsukihimeModalOpen = false;
+    harness.modal.openTsukihimeModal();
+    harness.titleInput.value = 'Futsutsuka na Akujo';
+
+    // The search parks on the language config, then the user closes and
+    // reopens the modal before it resolves.
+    pressKey(harness, 'Enter');
+    harness.modal.closeTsukihimeModal();
+    harness.modal.openTsukihimeModal();
+    await flushAsyncWork();
+    harness.status.textContent = 'Fresh modal session';
+
+    openGate();
+    await flushAsyncWork();
+
+    assert.deepEqual(harness.state.tsukihimeEntries, []);
+    assert.deepEqual(visibleEntryTitles(harness), []);
+    assert.equal(harness.status.textContent, 'Fresh modal session');
+  } finally {
+    harness.restoreGlobals();
+  }
+});
diff --git a/src/renderer/modals/tsukihime.ts b/src/renderer/modals/tsukihime.ts
index 1f30e182..8ba2fd4f 100644
--- a/src/renderer/modals/tsukihime.ts
+++ b/src/renderer/modals/tsukihime.ts
@@ -41,7 +41,13 @@ export function createTsukihimeModal(
 
   // Defaults to English until the configured secondary languages arrive.
   let secondaryLanguages: string[] = ['en'];
+  // Both tab filters read the configured languages, so a search must wait for
+  // them rather than filtering against the English fallback.
+  let secondaryLanguagesReady: Promise<void> = Promise.resolve();
   let activeDownloadToken = 0;
+  // Bumped by every new search and by closing the modal, so results that
+  // arrive late cannot repopulate a reopened modal or a newer search.
+  let activeSearchToken = 0;
 
   function secondaryTabLabel(): string {
     return describeTsukihimeTabLanguages(secondaryLanguages);
@@ -61,6 +67,47 @@ export function createTsukihimeModal(
     );
   }
 
+  // Releases are filtered by the languages the search index reports for
+  // them. Most releases carry no Japanese track, so the primary tab hides
+  // them outright. A release with no language data cannot be classified and
+  // stays on the secondary tab, mirroring how unlabeled tracks are handled.
+  function entryMatchesTab(entry: TsukihimeEntry, tab: 'secondary' | 'primary'): boolean {
+    if (tab === 'primary') {
+      return entry.sublangs.some((lang) => normalizeTsukihimeLangCode(lang) === 'ja');
+    }
+    if (entry.sublangs.length === 0) return true;
+    return entry.sublangs.some(
+      (lang) =>
+        normalizeTsukihimeLangCode(lang) !== 'ja' &&
+        tsukihimeTrackMatchesLanguages(lang, secondaryLanguages),
+    );
+  }
+
+  function getVisibleEntries(): TsukihimeEntry[] {
+    return ctx.state.tsukihimeEntries.filter((entry) =>
+      entryMatchesTab(entry, ctx.state.tsukihimeActiveTab),
+    );
+  }
+
+  function describeEmptyReleases(): string {
+    const otherTab = ctx.state.tsukihimeActiveTab === 'primary' ? 'secondary' : 'primary';
+    const otherTabHasReleases = ctx.state.tsukihimeEntries.some((entry) =>
+      entryMatchesTab(entry, otherTab),
+    );
+    const language = ctx.state.tsukihimeActiveTab === 'primary' ? 'Japanese' : secondaryTabLabel();
+    const otherLabel = otherTab === 'primary' ? 'Japanese' : secondaryTabLabel();
+    return otherTabHasReleases
+      ? `No releases with ${language} subtitles. Switch to the ${otherLabel} tab.`
+      : `No releases with ${language} subtitles.`;
+  }
+
+  function clearFiles(): void {
+    ctx.state.tsukihimeFiles = [];
+    ctx.state.selectedTsukihimeFileIndex = 0;
+    ctx.dom.tsukihimeFilesList.innerHTML = '';
+    ctx.dom.tsukihimeFilesSection.classList.add('hidden');
+  }
+
   function renderTabs(): void {
     const primaryActive = ctx.state.tsukihimeActiveTab === 'primary';
     ctx.dom.tsukihimeTabSecondaryButton.setAttribute(
@@ -98,12 +145,37 @@ export function createTsukihimeModal(
     ctx.state.selectedTsukihimeFileIndex = 0;
     renderTabs();
 
-    if (ctx.state.tsukihimeFiles.length === 0) return;
-    renderFiles();
-    if (getVisibleFiles().length === 0) {
-      setTsukihimeStatus(describeEmptyTab());
-    } else {
-      setTsukihimeStatus('Select a subtitle track.');
+    const currentEntry = ctx.state.tsukihimeEntries.find(
+      (entry) => entry.id === ctx.state.currentTsukihimeEntryId,
+    );
+    if (currentEntry && !entryMatchesTab(currentEntry, tab)) {
+      // The selected release is hidden on this tab; drop its tracks so the
+      // list matches what the tab claims to show.
+      ctx.state.currentTsukihimeEntryId = null;
+      ctx.state.selectedTsukihimeEntryIndex = 0;
+      clearFiles();
+      renderEntries();
+      setTsukihimeStatus(
+        getVisibleEntries().length === 0 ? describeEmptyReleases() : 'Select a release.',
+      );
+      return;
+    }
+
+    const visibleEntries = getVisibleEntries();
+    ctx.state.selectedTsukihimeEntryIndex = currentEntry ? visibleEntries.indexOf(currentEntry) : 0;
+    renderEntries();
+
+    if (ctx.state.tsukihimeFiles.length > 0) {
+      renderFiles();
+      setTsukihimeStatus(
+        getVisibleFiles().length === 0 ? describeEmptyTab() : 'Select a subtitle track.',
+      );
+      return;
+    }
+    if (!currentEntry && ctx.state.tsukihimeEntries.length > 0) {
+      setTsukihimeStatus(
+        visibleEntries.length === 0 ? describeEmptyReleases() : 'Select a release.',
+      );
     }
   }
 
@@ -121,13 +193,14 @@ export function createTsukihimeModal(
 
   function renderEntries(): void {
     ctx.dom.tsukihimeEntriesList.innerHTML = '';
-    if (ctx.state.tsukihimeEntries.length === 0) {
+    const visibleEntries = getVisibleEntries();
+    if (visibleEntries.length === 0) {
       ctx.dom.tsukihimeEntriesSection.classList.add('hidden');
       return;
     }
 
     ctx.dom.tsukihimeEntriesSection.classList.remove('hidden');
-    ctx.state.tsukihimeEntries.forEach((entry, index) => {
+    visibleEntries.forEach((entry, index) => {
       const li = document.createElement('li');
       li.textContent = entry.title;
 
@@ -210,11 +283,15 @@ export function createTsukihimeModal(
       return;
     }
 
+    const searchToken = ++activeSearchToken;
     resetTsukihimeLists();
     setTsukihimeStatus('Searching TsukiHime...');
+    await secondaryLanguagesReady;
+    if (searchToken !== activeSearchToken) return;
 
     const response: TsukihimeApiResponse<TsukihimeEntry[]> =
       await window.electronAPI.tsukihimeSearchEntries({ query });
+    if (searchToken !== activeSearchToken) return;
     if (!response.ok) {
       setTsukihimeStatus(response.error.error, true);
       return;
@@ -228,20 +305,22 @@ export function createTsukihimeModal(
       return;
     }
 
+    const visibleEntries = getVisibleEntries();
+    if (visibleEntries.length === 0) {
+      setTsukihimeStatus(describeEmptyReleases());
+      return;
+    }
+
     setTsukihimeStatus('Select a release.');
     renderEntries();
-    if (ctx.state.tsukihimeEntries.length === 1) {
+    if (visibleEntries.length === 1) {
       selectEntry(0);
     }
   }
 
   async function loadFiles(entryId: number): Promise<void> {
     setTsukihimeStatus('Loading subtitle tracks...');
-    ctx.state.tsukihimeFiles = [];
-    ctx.state.selectedTsukihimeFileIndex = 0;
-
-    ctx.dom.tsukihimeFilesList.innerHTML = '';
-    ctx.dom.tsukihimeFilesSection.classList.add('hidden');
+    clearFiles();
 
     const response: TsukihimeApiResponse<TsukihimeSubtitleFile[]> =
       await window.electronAPI.tsukihimeListFiles({ entryId });
@@ -279,11 +358,14 @@ export function createTsukihimeModal(
     }
   }
 
+  // `index` addresses the entries visible on the active tab, not the full
+  // search result list.
   function selectEntry(index: number): void {
-    if (index < 0 || index >= ctx.state.tsukihimeEntries.length) return;
+    const visibleEntries = getVisibleEntries();
+    if (index < 0 || index >= visibleEntries.length) return;
 
     ctx.state.selectedTsukihimeEntryIndex = index;
-    ctx.state.currentTsukihimeEntryId = ctx.state.tsukihimeEntries[index]!.id;
+    ctx.state.currentTsukihimeEntryId = visibleEntries[index]!.id;
     renderEntries();
 
     if (ctx.state.currentTsukihimeEntryId !== null) {
@@ -363,16 +445,15 @@ export function createTsukihimeModal(
     resetTsukihimeLists();
     renderTabs();
 
-    const secondaryLanguagesReady = loadSecondaryLanguages();
+    secondaryLanguagesReady = loadSecondaryLanguages();
 
     window.electronAPI
       .getJimakuMediaInfo()
-      .then(async (info: JimakuMediaInfo) => {
+      .then((info: JimakuMediaInfo) => {
         ctx.dom.tsukihimeTitleInput.value = info.title || '';
         ctx.dom.tsukihimeEpisodeInput.value = info.episode ? String(info.episode) : '';
 
         if (info.confidence === 'high' && info.title && info.episode) {
-          await secondaryLanguagesReady;
           void performTsukihimeSearch();
         } else if (info.title) {
           setTsukihimeStatus('Check title/episode and press Search.');
@@ -389,6 +470,7 @@ export function createTsukihimeModal(
     if (!ctx.state.tsukihimeModalOpen) return;
 
     activeDownloadToken += 1;
+    activeSearchToken += 1;
     ctx.state.tsukihimeModalOpen = false;
     options.syncSettingsModalSubtitleSuppression();
     ctx.dom.tsukihimeModal.classList.add('hidden');
@@ -438,9 +520,9 @@ export function createTsukihimeModal(
           ctx.state.selectedTsukihimeFileIndex + 1,
         );
         renderFiles();
-      } else if (ctx.state.tsukihimeEntries.length > 0) {
+      } else if (getVisibleEntries().length > 0) {
         ctx.state.selectedTsukihimeEntryIndex = Math.min(
-          ctx.state.tsukihimeEntries.length - 1,
+          getVisibleEntries().length - 1,
           ctx.state.selectedTsukihimeEntryIndex + 1,
         );
         renderEntries();
@@ -456,7 +538,7 @@ export function createTsukihimeModal(
           ctx.state.selectedTsukihimeFileIndex - 1,
         );
         renderFiles();
-      } else if (ctx.state.tsukihimeEntries.length > 0) {
+      } else if (getVisibleEntries().length > 0) {
         ctx.state.selectedTsukihimeEntryIndex = Math.max(
           0,
           ctx.state.selectedTsukihimeEntryIndex - 1,
@@ -470,7 +552,7 @@ export function createTsukihimeModal(
       e.preventDefault();
       if (getVisibleFiles().length > 0) {
         void selectFile(ctx.state.selectedTsukihimeFileIndex);
-      } else if (ctx.state.tsukihimeEntries.length > 0) {
+      } else if (getVisibleEntries().length > 0) {
         selectEntry(ctx.state.selectedTsukihimeEntryIndex);
       } else {
         void performTsukihimeSearch();
diff --git a/src/renderer/overlay-mouse-ignore.ts b/src/renderer/overlay-mouse-ignore.ts
index 5a5d3b4b..865b8267 100644
--- a/src/renderer/overlay-mouse-ignore.ts
+++ b/src/renderer/overlay-mouse-ignore.ts
@@ -10,7 +10,9 @@ function isBlockingOverlayModalOpen(state: RendererState): boolean {
     state.youtubePickerModalOpen ||
     state.kikuModalOpen ||
     state.runtimeOptionsModalOpen ||
+    state.subtitleSelectionModalOpen ||
     state.subsyncModalOpen ||
+    state.subtitleGenerationModalOpen ||
     state.sessionHelpModalOpen,
   );
 }
@@ -27,7 +29,9 @@ function isYomitanPopupInteractionActive(state: RendererState): boolean {
 
 export function syncOverlayMouseIgnoreState(ctx: RendererContext): void {
   const shouldKeepWindowInteractive =
-    isYomitanPopupInteractionActive(ctx.state) || isBlockingOverlayModalOpen(ctx.state);
+    ctx.dom.subtitleSidebarList?.dataset?.selecting === 'true' ||
+    isYomitanPopupInteractionActive(ctx.state) ||
+    isBlockingOverlayModalOpen(ctx.state);
   const shouldStayInteractive =
     ctx.state.isOverSubtitle ||
     ctx.state.isOverSubtitleSidebar ||
diff --git a/src/renderer/renderer.ts b/src/renderer/renderer.ts
index 5ffacdad..5932c686 100644
--- a/src/renderer/renderer.ts
+++ b/src/renderer/renderer.ts
@@ -40,11 +40,15 @@ import { createPlaylistBrowserModal } from './modals/playlist-browser.js';
 import { createSessionHelpModal } from './modals/session-help.js';
 import { createChangelogModal } from './modals/changelog.js';
 import { createSubtitleSidebarModal } from './modals/subtitle-sidebar.js';
+import { wireSubtitleSidebarSelection } from './modals/subtitle-sidebar-selection.js';
 import { isControllerInteractionBlocked } from './controller-interaction-blocking.js';
 import { createCharacterDictionaryModal } from './modals/character-dictionary.js';
 import { createRuntimeOptionsModal } from './modals/runtime-options.js';
+import { createSubtitleSelectionModal } from './modals/subtitle-selection';
 import { createSubsyncModal } from './modals/subsync.js';
+import { createSubtitleGenerationModal } from './modals/subtitle-generation.js';
 import { createYoutubeTrackPickerModal } from './modals/youtube-track-picker.js';
+import { createMediaTimingReviewModal } from './modals/media-timing-review.js';
 import { createPositioningController } from './positioning.js';
 import { createOverlayContentMeasurementReporter } from './overlay-content-measurement.js';
 import { syncOverlayMouseIgnoreState } from './overlay-mouse-ignore.js';
@@ -78,6 +82,12 @@ const ctx = {
 };
 
 const modalDescriptors = [
+  {
+    id: 'subtitle-generation',
+    isOpen: () => ctx.state.subtitleGenerationModalOpen,
+    close: () => subtitleGenerationModal.close(),
+    suppressesSubtitles: true,
+  },
   {
     id: 'controller-select',
     isOpen: () => ctx.state.controllerSelectModalOpen,
@@ -114,6 +124,12 @@ const modalDescriptors = [
     close: () => youtubePickerModal.closeYoutubePickerModal(),
     suppressesSubtitles: true,
   },
+  {
+    id: 'media-timing-review',
+    isOpen: () => ctx.state.mediaTimingReviewModalOpen,
+    close: () => mediaTimingReviewModal.requestCancel(),
+    suppressesSubtitles: true,
+  },
   {
     id: 'playlist-browser',
     isOpen: () => ctx.state.playlistBrowserModalOpen,
@@ -138,6 +154,12 @@ const modalDescriptors = [
     close: () => characterDictionaryModal.closeCharacterDictionaryModal(),
     suppressesSubtitles: true,
   },
+  {
+    id: 'subtitle-selection',
+    isOpen: () => ctx.state.subtitleSelectionModalOpen,
+    close: () => subtitleSelectionModal.close(),
+    suppressesSubtitles: true,
+  },
   {
     id: 'subsync',
     isOpen: () => ctx.state.subsyncModalOpen,
@@ -201,10 +223,17 @@ const characterDictionaryModal = createCharacterDictionaryModal(ctx, {
   modalStateReader: { isAnyModalOpen },
   syncSettingsModalSubtitleSuppression,
 });
+const subtitleSelectionModal = createSubtitleSelectionModal(ctx, {
+  syncSettingsModalSubtitleSuppression,
+});
 const subsyncModal = createSubsyncModal(ctx, {
   modalStateReader: { isAnyModalOpen },
   syncSettingsModalSubtitleSuppression,
 });
+const subtitleGenerationModal = createSubtitleGenerationModal(ctx, {
+  modalStateReader: { isAnyModalOpen },
+  syncSettingsModalSubtitleSuppression,
+});
 const controllerSelectModal = createControllerSelectModal(ctx, {
   modalStateReader: { isAnyModalOpen },
   syncSettingsModalSubtitleSuppression,
@@ -232,6 +261,8 @@ const subtitleSidebarModal = createSubtitleSidebarModal(ctx, {
     measurementReporter.emitNow();
   },
 });
+const disposeSubtitleSidebarSelection = wireSubtitleSidebarSelection(ctx);
+window.addEventListener('beforeunload', disposeSubtitleSidebarSelection, { once: true });
 const kikuModal = createKikuModal(ctx, {
   modalStateReader: { isAnyModalOpen },
   syncSettingsModalSubtitleSuppression,
@@ -265,14 +296,21 @@ const playlistBrowserModal = createPlaylistBrowserModal(ctx, {
   modalStateReader: { isAnyModalOpen },
   syncSettingsModalSubtitleSuppression,
 });
+const mediaTimingReviewModal = createMediaTimingReviewModal(ctx, {
+  modalStateReader: { isAnyModalOpen },
+  syncSettingsModalSubtitleSuppression,
+});
 const keyboardHandlers = createKeyboardHandlers(ctx, {
   handleRuntimeOptionsKeydown: runtimeOptionsModal.handleRuntimeOptionsKeydown,
   handleCharacterDictionaryKeydown: characterDictionaryModal.handleCharacterDictionaryKeydown,
+  handleSubtitleSelectionKeydown: subtitleSelectionModal.handleKeydown,
   handleSubsyncKeydown: subsyncModal.handleSubsyncKeydown,
+  handleSubtitleGenerationKeydown: subtitleGenerationModal.handleKeydown,
   handleKikuKeydown: kikuModal.handleKikuKeydown,
   handleJimakuKeydown: jimakuModal.handleJimakuKeydown,
   handleTsukihimeKeydown: tsukihimeModal.handleTsukihimeKeydown,
   handleYoutubePickerKeydown: youtubePickerModal.handleYoutubePickerKeydown,
+  handleMediaTimingReviewKeydown: mediaTimingReviewModal.handleMediaTimingReviewKeydown,
   handlePlaylistBrowserKeydown: playlistBrowserModal.handlePlaylistBrowserKeydown,
   handleControllerSelectKeydown: controllerSelectModal.handleControllerSelectKeydown,
   handleControllerDebugKeydown: controllerDebugModal.handleControllerDebugKeydown,
@@ -520,6 +558,9 @@ const recovery = createRendererRecoveryController({
 registerRendererGlobalErrorHandlers(window, recovery);
 
 function registerModalOpenHandlers(): void {
+  window.electronAPI.onSubtitleGenerationOpen(() => {
+    runGuarded('subtitle-generation:open', () => subtitleGenerationModal.open());
+  });
   window.electronAPI.onOpenRuntimeOptions(() => {
     runGuarded('runtime-options:open', () => {
       runtimeOptionsModal.openRuntimeOptionsModal();
@@ -574,6 +615,16 @@ function registerModalOpenHandlers(): void {
       youtubePickerModal.openYoutubePickerModal(payload);
     });
   });
+  window.electronAPI.onOpenMediaTimingReview((payload) => {
+    runGuarded('media-timing-review:open', () => {
+      mediaTimingReviewModal.openMediaTimingReviewModal(payload);
+    });
+  });
+  window.electronAPI.onMediaTimingReviewPreviewEnded((reviewId) => {
+    runGuarded('media-timing-review:preview-ended', () => {
+      mediaTimingReviewModal.handlePreviewEnded(reviewId);
+    });
+  });
   window.electronAPI.onOpenPlaylistBrowser(() => {
     runGuardedAsync('playlist-browser:open', async () => {
       await playlistBrowserModal.openPlaylistBrowserModal();
@@ -584,6 +635,9 @@ function registerModalOpenHandlers(): void {
       youtubePickerModal.closeYoutubePickerModal();
     });
   });
+  window.electronAPI.onSubtitleSelectionOpen(() => {
+    runGuarded('subtitle-selection:open', () => subtitleSelectionModal.open());
+  });
   window.electronAPI.onSubsyncManualOpen((payload: SubsyncManualPayload) => {
     runGuarded('subsync:manual-open', () => {
       subsyncModal.openSubsyncModal(payload);
@@ -805,10 +859,13 @@ async function init(): Promise<void> {
   jimakuModal.wireDomEvents();
   tsukihimeModal.wireDomEvents();
   youtubePickerModal.wireDomEvents();
+  mediaTimingReviewModal.wireDomEvents();
   playlistBrowserModal.wireDomEvents();
   kikuModal.wireDomEvents();
   runtimeOptionsModal.wireDomEvents();
+  subtitleSelectionModal.wireDomEvents();
   subsyncModal.wireDomEvents();
+  subtitleGenerationModal.wireDomEvents();
   controllerSelectModal.wireDomEvents();
   controllerDebugModal.wireDomEvents();
   sessionHelpModal.wireDomEvents();
@@ -816,6 +873,8 @@ async function init(): Promise<void> {
   subtitleSidebarModal.wireDomEvents();
   characterDictionaryModal.wireDomEvents();
   window.addEventListener('beforeunload', () => {
+    subtitleSelectionModal.dispose();
+    subtitleGenerationModal.dispose();
     subtitleSidebarModal.disposeDomEvents();
   });
 
@@ -824,9 +883,13 @@ async function init(): Promise<void> {
       runtimeOptionsModal.updateRuntimeOptions(options);
     });
   });
+  window.electronAPI.onSessionBindingsChanged(keyboardHandlers.updateSessionBindings);
   window.electronAPI.onConfigHotReload((payload: ConfigHotReloadPayload) => {
     runGuarded('config:hot-reload', () => {
-      keyboardHandlers.updateSessionBindings(payload.sessionBindings);
+      void window.electronAPI
+        .getSessionBindings()
+        .then(keyboardHandlers.updateSessionBindings)
+        .catch((error: unknown) => console.error('Could not refresh session bindings', error));
       void keyboardHandlers.refreshConfiguredShortcuts();
       subtitleRenderer.applySubtitleStyle(payload.subtitleStyle);
       subtitleRenderer.updatePrimarySubMode(payload.primarySubMode);
diff --git a/src/renderer/state.ts b/src/renderer/state.ts
index 97005902..d7feb5e0 100644
--- a/src/renderer/state.ts
+++ b/src/renderer/state.ts
@@ -7,6 +7,7 @@ import type {
   TsukihimeEntry,
   TsukihimeSubtitleFile,
   JimakuEntry,
+  JimakuSearchCategory,
   JimakuFileEntry,
   KikuDuplicateCardInfo,
   KikuFieldGroupingChoice,
@@ -43,6 +44,7 @@ export type RendererState = {
   persistedSubtitlePosition: SubtitlePosition;
 
   jimakuModalOpen: boolean;
+  jimakuActiveTab: JimakuSearchCategory;
   jimakuEntries: JimakuEntry[];
   jimakuFiles: JimakuFileEntry[];
   selectedEntryIndex: number;
@@ -64,6 +66,8 @@ export type RendererState = {
   youtubePickerSecondaryTrackId: string | null;
   youtubePickerStatus: string;
 
+  mediaTimingReviewModalOpen: boolean;
+
   kikuModalOpen: boolean;
   kikuSelectedCard: 1 | 2;
   kikuOriginalData: KikuDuplicateCardInfo | null;
@@ -85,6 +89,8 @@ export type RendererState = {
   characterDictionaryStatus: string;
 
   subsyncModalOpen: boolean;
+  subtitleSelectionModalOpen: boolean;
+  subtitleGenerationModalOpen: boolean;
   subsyncSubtitleTracks: SubsyncSubtitleTrack[];
   subsyncSubmitting: boolean;
 
@@ -173,6 +179,7 @@ export function createRendererState(): RendererState {
     persistedSubtitlePosition: { yPercent: 10 },
 
     jimakuModalOpen: false,
+    jimakuActiveTab: 'anime',
     jimakuEntries: [],
     jimakuFiles: [],
     selectedEntryIndex: 0,
@@ -194,6 +201,8 @@ export function createRendererState(): RendererState {
     youtubePickerSecondaryTrackId: null,
     youtubePickerStatus: '',
 
+    mediaTimingReviewModalOpen: false,
+
     kikuModalOpen: false,
     kikuSelectedCard: 1,
     kikuOriginalData: null,
@@ -215,6 +224,8 @@ export function createRendererState(): RendererState {
     characterDictionaryStatus: '',
 
     subsyncModalOpen: false,
+    subtitleSelectionModalOpen: false,
+    subtitleGenerationModalOpen: false,
     subsyncSubtitleTracks: [],
     subsyncSubmitting: false,
 
diff --git a/src/renderer/style.css b/src/renderer/style.css
index f1aa7704..5c0620d9 100644
--- a/src/renderer/style.css
+++ b/src/renderer/style.css
@@ -18,7 +18,7 @@
 
 @font-face {
   font-family: 'M PLUS 1';
-  src: url('./fonts/MPLUS1[wght].ttf') format('truetype');
+  src: url('../fonts/MPLUS1[wght].ttf') format('truetype');
   font-weight: 100 900;
   font-display: swap;
 }
@@ -819,12 +819,14 @@ body:focus-visible,
   grid-template-columns: 1fr 120px auto;
 }
 
+.jimaku-tabs,
 .tsukihime-tabs {
   display: grid;
   grid-template-columns: repeat(2, minmax(0, 1fr));
   gap: 6px;
 }
 
+.jimaku-tab,
 .tsukihime-tab {
   min-width: 0;
   min-height: 34px;
@@ -842,6 +844,8 @@ body:focus-visible,
   text-overflow: ellipsis;
 }
 
+.jimaku-tab:hover,
+.jimaku-tab:focus-visible,
 .tsukihime-tab:hover,
 .tsukihime-tab:focus-visible {
   border-color: rgba(138, 173, 244, 0.48);
@@ -849,6 +853,7 @@ body:focus-visible,
   outline: none;
 }
 
+.jimaku-tab.active,
 .tsukihime-tab.active {
   border-color: rgba(238, 212, 159, 0.62);
   background: rgba(238, 212, 159, 0.16);
@@ -1323,6 +1328,875 @@ body:focus-visible,
   }
 }
 
+/* Media timing review uses the Catppuccin Macchiato palette without opacity-shifted colors. */
+.media-timing-review-modal {
+  background: rgba(24, 25, 38, 0.76);
+  backdrop-filter: blur(10px);
+}
+
+/* Pointer capture keeps events on the track, so the cursor is forced from the modal root. */
+.media-timing-review-modal.is-scrubbing,
+.media-timing-review-modal.is-scrubbing * {
+  cursor: ew-resize;
+}
+
+.media-timing-review-modal.is-sliding,
+.media-timing-review-modal.is-sliding * {
+  cursor: grabbing;
+}
+
+.media-timing-review-content {
+  width: min(720px, calc(100vw - 32px));
+  max-height: min(900px, calc(100vh - 32px));
+  overflow: auto;
+  gap: 0;
+  padding: 0;
+  border: 1px solid var(--ctp-surface1);
+  border-radius: 16px;
+  background: var(--ctp-base);
+  color: var(--ctp-text);
+  box-shadow:
+    0 30px 90px rgba(24, 25, 38, 0.8),
+    0 0 0 1px rgba(183, 189, 248, 0.07) inset;
+  animation: media-timing-review-enter 180ms cubic-bezier(0.2, 0.9, 0.25, 1);
+}
+
+@keyframes media-timing-review-enter {
+  from {
+    opacity: 0;
+    transform: translateY(10px) scale(0.985);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0) scale(1);
+  }
+}
+
+.media-timing-review-header {
+  position: sticky;
+  z-index: 2;
+  top: 0;
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 24px;
+  padding: 16px 20px 13px;
+  border-bottom: 1px solid var(--ctp-surface0);
+  background: var(--ctp-mantle);
+}
+
+.media-timing-review-heading {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 10px;
+}
+
+.media-timing-review-title {
+  color: var(--ctp-text);
+  font-size: 19px;
+  font-weight: 750;
+  letter-spacing: -0.025em;
+}
+
+.media-timing-review-kind {
+  --kind-accent: var(--ctp-teal);
+
+  padding: 3px 9px;
+  border: 1px solid color-mix(in srgb, var(--kind-accent) 42%, transparent);
+  border-radius: 999px;
+  background: color-mix(in srgb, var(--kind-accent) 13%, transparent);
+  color: var(--kind-accent);
+  font-size: 10px;
+  font-weight: 800;
+  letter-spacing: 0.12em;
+  text-transform: uppercase;
+}
+
+.media-timing-review-kind[data-kind='word'] {
+  --kind-accent: var(--ctp-mauve);
+}
+
+.media-timing-review-kind[data-kind='audio'] {
+  --kind-accent: var(--ctp-sky);
+}
+
+.media-timing-review-editor {
+  padding: 14px 20px 18px;
+}
+
+.media-timing-frame-picker {
+  display: grid;
+  grid-template-columns: minmax(0, 1fr) minmax(0, 1fr);
+  gap: 16px;
+  align-items: center;
+  margin: 0 0 16px;
+  padding: 12px;
+  border: 1px solid var(--ctp-surface1);
+  border-radius: 10px;
+  background: var(--ctp-mantle);
+}
+
+.media-timing-frame-picker.hidden {
+  display: none;
+}
+.media-timing-frame-image-shell {
+  aspect-ratio: 16 / 9;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  overflow: hidden;
+  border-radius: 6px;
+  background: var(--ctp-crust);
+}
+.media-timing-frame-image-shell img {
+  width: 100%;
+  height: 100%;
+  object-fit: contain;
+}
+.media-timing-frame-picker[aria-busy='true'] img {
+  opacity: 0.55;
+}
+.media-timing-frame-heading {
+  display: flex;
+  justify-content: space-between;
+  gap: 8px;
+  font-size: 12px;
+}
+.media-timing-frame-heading output {
+  color: var(--ctp-teal);
+  font-variant-numeric: tabular-nums;
+}
+.media-timing-frame-controls input {
+  width: 100%;
+  margin: 12px 0;
+  accent-color: var(--ctp-teal);
+}
+.media-timing-frame-buttons {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 6px;
+}
+.media-timing-frame-buttons button {
+  padding: 5px 8px;
+  border: 1px solid var(--ctp-surface2);
+  border-radius: 6px;
+  background: var(--ctp-surface0);
+  color: var(--ctp-text);
+  font-size: 11px;
+  cursor: pointer;
+}
+.media-timing-frame-buttons button:disabled {
+  opacity: 0.45;
+  cursor: default;
+}
+.media-timing-frame-controls p {
+  margin: 8px 0 0;
+  min-height: 2.6em;
+  color: var(--ctp-subtext0);
+  font-size: 11px;
+}
+@media (max-width: 520px) {
+  .media-timing-frame-picker {
+    grid-template-columns: 1fr;
+  }
+  .media-timing-frame-image-shell {
+    max-height: 180px;
+  }
+}
+
+.media-timing-review-sentence-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 12px;
+  margin-bottom: 6px;
+}
+
+.media-timing-review-sentence-heading {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+
+.media-timing-review-sentence-label {
+  color: var(--ctp-overlay1);
+  font-size: 10px;
+  font-weight: 750;
+  letter-spacing: 0.1em;
+  text-transform: uppercase;
+}
+
+.media-timing-review-line-count {
+  padding: 2px 8px;
+  border: 1px solid var(--ctp-surface1);
+  border-radius: 999px;
+  background: var(--ctp-mantle);
+  color: var(--ctp-subtext0);
+  font-size: 10px;
+  font-weight: 700;
+  font-variant-numeric: tabular-nums;
+}
+
+.media-timing-review-line-controls {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+}
+
+.media-timing-review-line-stepper {
+  display: flex;
+  align-items: center;
+  gap: 4px;
+}
+
+.media-timing-review-line-stepper span {
+  margin-right: 2px;
+  color: var(--ctp-overlay1);
+  font-size: 10px;
+  font-weight: 750;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+}
+
+.media-timing-review-line-stepper button {
+  width: 24px;
+  height: 22px;
+  padding: 0;
+  border: 1px solid var(--ctp-surface2);
+  border-radius: 6px;
+  background: var(--ctp-surface0);
+  color: var(--ctp-text);
+  font-size: 13px;
+  font-weight: 750;
+  line-height: 1;
+  cursor: pointer;
+}
+
+.media-timing-review-text {
+  display: flex;
+  flex-direction: column;
+  gap: 3px;
+  max-height: 108px;
+  overflow: auto;
+  margin: 0 0 12px;
+  padding: 8px 14px;
+  border-left: 3px solid var(--ctp-mauve);
+  border-radius: 0 10px 10px 0;
+  background: var(--ctp-mantle);
+  color: var(--ctp-subtext1);
+  font-size: 15px;
+  font-weight: 560;
+  line-height: 1.45;
+  white-space: pre-wrap;
+}
+
+.media-timing-review-line {
+  color: var(--ctp-overlay1);
+}
+
+.media-timing-review-line.is-current {
+  color: var(--ctp-text);
+}
+
+/* Only dim context lines when some are actually added. */
+.media-timing-review-text .media-timing-review-line:only-child {
+  color: var(--ctp-subtext1);
+}
+
+.media-timing-review-readout {
+  display: grid;
+  grid-template-columns: 1fr auto 1fr;
+  overflow: hidden;
+  margin-bottom: 12px;
+  border: 1px solid var(--ctp-surface1);
+  border-radius: 12px;
+  background: var(--ctp-mantle);
+}
+
+.media-timing-review-readout > div {
+  display: flex;
+  min-width: 0;
+  flex-direction: column;
+  gap: 3px;
+  padding: 8px 12px;
+}
+
+.media-timing-review-readout > div + div {
+  border-left: 1px solid var(--ctp-surface0);
+}
+
+.media-timing-review-readout span {
+  color: var(--ctp-overlay1);
+  font-size: 10px;
+  font-weight: 750;
+  letter-spacing: 0.1em;
+  text-transform: uppercase;
+}
+
+.media-timing-review-readout strong {
+  color: var(--ctp-lavender);
+  font-variant-numeric: tabular-nums;
+  font-size: 16px;
+  font-weight: 720;
+}
+
+.media-timing-review-readout .media-timing-review-duration {
+  align-items: center;
+  min-width: 128px;
+  background: var(--ctp-surface0);
+  text-align: center;
+}
+
+.media-timing-review-readout > div:last-child {
+  align-items: flex-end;
+  text-align: right;
+}
+
+.media-timing-review-readout .media-timing-review-duration strong {
+  color: var(--ctp-teal);
+}
+
+.media-timing-review-timeline-shell {
+  padding: 10px 12px 8px;
+  border: 1px solid var(--ctp-surface1);
+  border-radius: 14px;
+  background: var(--ctp-mantle);
+}
+
+.media-timing-review-timeline-labels,
+.media-timing-review-expand-row {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 12px;
+  color: var(--ctp-overlay1);
+  font-size: 10px;
+  font-weight: 650;
+  letter-spacing: 0.05em;
+}
+
+.media-timing-review-timeline-labels span:first-child,
+.media-timing-review-timeline-labels span:last-child {
+  color: var(--ctp-subtext0);
+  font-variant-numeric: tabular-nums;
+}
+
+.media-timing-review-track {
+  --selection-start: 20%;
+  --selection-end: 80%;
+  --original-start: 25%;
+  --original-end: 75%;
+  --playhead-duration: 1s;
+
+  position: relative;
+  height: 52px;
+  margin: 8px 0 9px;
+  overflow: hidden;
+  border: 1px solid var(--ctp-surface2);
+  border-radius: 10px;
+  background:
+    linear-gradient(var(--ctp-surface1), var(--ctp-surface1)) center / 100% 1px no-repeat,
+    repeating-linear-gradient(
+      90deg,
+      transparent 0,
+      transparent calc(10% - 1px),
+      color-mix(in srgb, var(--ctp-surface1) 65%, transparent) calc(10% - 1px),
+      color-mix(in srgb, var(--ctp-surface1) 65%, transparent) 10%
+    ),
+    linear-gradient(180deg, var(--ctp-crust), var(--ctp-mantle));
+  cursor: ew-resize;
+  touch-action: none;
+  user-select: none;
+}
+
+.media-timing-review-waveform {
+  position: absolute;
+  z-index: 1;
+  inset: 4px 0;
+  width: 100%;
+  height: calc(100% - 8px);
+  pointer-events: none;
+  transition: opacity 160ms ease;
+}
+
+#mediaTimingReviewWaveformPath {
+  fill: url('#mediaTimingReviewWaveformFill');
+}
+
+.media-timing-review-waveform-edge-stop {
+  stop-color: var(--ctp-sky);
+}
+
+.media-timing-review-waveform-core-stop {
+  stop-color: var(--ctp-blue);
+}
+
+/* Sits above the selection scrim so adjacent dialogue reads as outside the mined subtitle. */
+.media-timing-review-original-range {
+  position: absolute;
+  z-index: 4;
+  top: 0;
+  bottom: 0;
+  left: var(--original-start);
+  right: calc(100% - var(--original-end));
+  min-width: 1px;
+  background: color-mix(in srgb, var(--ctp-peach) 11%, transparent);
+  box-shadow: inset 0 0 0 1px color-mix(in srgb, var(--ctp-peach) 28%, transparent);
+  pointer-events: none;
+}
+
+.media-timing-review-original-boundary {
+  position: absolute;
+  top: 0;
+  bottom: 0;
+  width: 2px;
+  background: var(--ctp-peach);
+  box-shadow: 0 0 8px color-mix(in srgb, var(--ctp-peach) 45%, transparent);
+}
+
+.media-timing-review-original-boundary.is-start {
+  left: 0;
+}
+
+.media-timing-review-original-boundary.is-end {
+  right: 0;
+}
+
+.media-timing-review-original-label {
+  position: absolute;
+  z-index: 7;
+  padding: 3px 5px;
+  border: 1px solid color-mix(in srgb, var(--ctp-crust) 35%, transparent);
+  border-radius: 4px;
+  background: var(--ctp-peach);
+  box-shadow: 0 2px 6px color-mix(in srgb, var(--ctp-crust) 55%, transparent);
+  color: var(--ctp-crust);
+  font-size: 8px;
+  font-weight: 800;
+  letter-spacing: 0.06em;
+  line-height: 1;
+  pointer-events: none;
+  white-space: nowrap;
+  text-transform: uppercase;
+}
+
+.media-timing-review-original-label.is-start {
+  top: 5px;
+  left: calc(var(--original-start) + 7px);
+}
+
+.media-timing-review-original-label.is-end {
+  right: calc(100% - var(--original-end) + 7px);
+  bottom: 5px;
+}
+
+.media-timing-review-track.is-loading::after {
+  position: absolute;
+  z-index: 2;
+  inset: 0;
+  content: '';
+  background: linear-gradient(
+    105deg,
+    transparent 20%,
+    rgba(138, 173, 244, 0.16) 44%,
+    rgba(183, 189, 248, 0.22) 50%,
+    transparent 76%
+  );
+  transform: translateX(-100%);
+  animation: media-timing-waveform-loading 1.1s ease-in-out infinite;
+  pointer-events: none;
+}
+
+.media-timing-review-track.is-waveform-unavailable .media-timing-review-waveform {
+  opacity: 0;
+}
+
+@keyframes media-timing-waveform-loading {
+  to {
+    transform: translateX(100%);
+  }
+}
+
+/* The oversized shadow spread dims everything outside the clip; the track clips it. */
+.media-timing-review-selected-range {
+  position: absolute;
+  z-index: 3;
+  inset: 0 calc(100% - var(--selection-end)) 0 var(--selection-start);
+  border-inline: 1px solid color-mix(in srgb, var(--ctp-teal) 65%, transparent);
+  background: color-mix(in srgb, var(--ctp-teal) 9%, transparent);
+  box-shadow: 0 0 0 2000px color-mix(in srgb, var(--ctp-crust) 62%, transparent);
+  cursor: grab;
+}
+
+.media-timing-review-playhead {
+  position: absolute;
+  z-index: 5;
+  top: 0;
+  bottom: 0;
+  left: var(--selection-start);
+  width: 2px;
+  background: var(--ctp-yellow);
+  box-shadow: 0 0 12px color-mix(in srgb, var(--ctp-yellow) 75%, transparent);
+  opacity: 0;
+  pointer-events: none;
+}
+
+.media-timing-review-track.is-previewing .media-timing-review-playhead {
+  opacity: 1;
+  animation: media-timing-review-playhead var(--playhead-duration) linear forwards;
+}
+
+@keyframes media-timing-review-playhead {
+  from {
+    left: var(--selection-start);
+  }
+  to {
+    left: var(--selection-end);
+  }
+}
+
+.media-timing-review-handle {
+  position: absolute;
+  z-index: 6;
+  top: 0;
+  bottom: 0;
+  width: 14px;
+  border: 1px solid var(--ctp-teal);
+  background: linear-gradient(
+    180deg,
+    var(--ctp-teal),
+    color-mix(in srgb, var(--ctp-teal) 74%, var(--ctp-crust))
+  );
+  cursor: ew-resize;
+  touch-action: none;
+  transition: box-shadow 130ms ease;
+}
+
+/* Widens the grab area past the visible bracket without moving the clip edge. */
+.media-timing-review-handle::before {
+  position: absolute;
+  inset: 0 -7px;
+  content: '';
+}
+
+.media-timing-review-handle::after {
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  width: 6px;
+  height: 18px;
+  content: '';
+  border-inline: 1px solid color-mix(in srgb, var(--ctp-crust) 55%, transparent);
+  transform: translate(-50%, -50%);
+}
+
+.media-timing-review-handle-start {
+  left: var(--selection-start);
+  border-radius: 5px 0 0 5px;
+}
+
+.media-timing-review-handle-end {
+  left: var(--selection-end);
+  border-radius: 0 5px 5px 0;
+  transform: translateX(-100%);
+}
+
+.media-timing-review-handle:hover {
+  box-shadow: 0 0 16px color-mix(in srgb, var(--ctp-teal) 60%, transparent);
+}
+
+.media-timing-review-handle:focus-visible {
+  outline: 2px solid transparent;
+  box-shadow:
+    inset 0 0 0 2px var(--ctp-yellow),
+    0 0 16px color-mix(in srgb, var(--ctp-yellow) 55%, transparent);
+}
+
+.media-timing-review-expand-row span {
+  text-align: center;
+}
+
+.media-timing-review-expand-button,
+.media-timing-review-quiet-button,
+.media-timing-review-original-button,
+.media-timing-review-skip-button,
+.media-timing-review-discard-button,
+.media-timing-review-play-button,
+.media-timing-review-confirm-button,
+.media-timing-review-fine-control button {
+  border: 1px solid var(--ctp-surface2);
+  border-radius: 9px;
+  background: var(--ctp-surface0);
+  color: var(--ctp-text);
+  font: inherit;
+  font-size: 12px;
+  font-weight: 720;
+  cursor: pointer;
+  transition:
+    background 130ms ease,
+    border-color 130ms ease,
+    transform 130ms ease;
+}
+
+.media-timing-review-expand-button {
+  min-width: 82px;
+  padding: 5px 9px;
+  color: var(--ctp-sky);
+  font-variant-numeric: tabular-nums;
+}
+
+.media-timing-review-expand-button:disabled,
+.media-timing-review-content button:disabled {
+  cursor: default;
+  opacity: 0.42;
+}
+
+.media-timing-review-content button:not(:disabled):hover {
+  border-color: var(--ctp-lavender);
+  background: var(--ctp-surface1);
+}
+
+.media-timing-review-content button:not(:disabled):active {
+  transform: translateY(1px);
+}
+
+.media-timing-review-content button:focus-visible {
+  outline: 2px solid var(--ctp-yellow);
+  outline-offset: 2px;
+}
+
+.media-timing-review-fine-grid {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 10px;
+  margin-top: 10px;
+}
+
+.media-timing-review-fine-control {
+  display: grid;
+  grid-template-columns: 1fr auto auto;
+  align-items: center;
+  gap: 6px;
+  padding: 8px 10px;
+  border: 1px solid var(--ctp-surface0);
+  border-radius: 10px;
+  background: var(--ctp-mantle);
+  color: var(--ctp-subtext1);
+}
+
+.media-timing-review-fine-control span {
+  font-size: 11px;
+  font-weight: 750;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+}
+
+.media-timing-review-fine-control button {
+  min-width: 58px;
+  padding: 5px 8px;
+  font-variant-numeric: tabular-nums;
+}
+
+.media-timing-review-status {
+  min-height: 21px;
+  padding-top: 8px;
+  color: var(--ctp-teal);
+  font-size: 11px;
+  font-weight: 620;
+}
+
+.media-timing-review-status.is-error {
+  color: var(--ctp-red);
+}
+
+.media-timing-review-footer,
+.media-timing-review-preview-actions {
+  display: flex;
+  align-items: center;
+  gap: 9px;
+}
+
+.media-timing-review-footer {
+  justify-content: space-between;
+  padding-top: 4px;
+}
+
+.media-timing-review-play-button,
+.media-timing-review-confirm-button,
+.media-timing-review-quiet-button,
+.media-timing-review-original-button,
+.media-timing-review-skip-button,
+.media-timing-review-discard-button {
+  padding: 9px 15px;
+}
+
+.media-timing-review-play-button {
+  display: inline-flex;
+  align-items: center;
+  gap: 9px;
+  border-color: var(--ctp-teal);
+  background: var(--ctp-teal);
+  color: var(--ctp-crust);
+}
+
+.media-timing-review-play-glyph {
+  width: 0;
+  height: 0;
+  border-block: 5px solid transparent;
+  border-left: 9px solid currentcolor;
+}
+
+.media-timing-review-play-button.is-playing {
+  border-color: var(--ctp-yellow);
+  background: var(--ctp-yellow);
+}
+
+.media-timing-review-play-button.is-playing .media-timing-review-play-glyph {
+  width: 9px;
+  height: 10px;
+  border: 0;
+  border-radius: 2px;
+  background: currentcolor;
+}
+
+.media-timing-review-confirm-button {
+  border-color: var(--ctp-blue);
+  background: var(--ctp-blue);
+  color: var(--ctp-crust);
+}
+
+.media-timing-review-original-button {
+  border-color: var(--ctp-yellow);
+  color: var(--ctp-yellow);
+}
+
+.media-timing-review-skip-button {
+  border-color: var(--ctp-sky);
+  color: var(--ctp-sky);
+}
+
+.media-timing-review-discard-button {
+  border-color: var(--ctp-red);
+  background: var(--ctp-red);
+  color: var(--ctp-crust);
+}
+
+.media-timing-review-hints {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 4px 16px;
+  padding-top: 14px;
+  color: var(--ctp-overlay1);
+  font-size: 10px;
+  font-weight: 650;
+  letter-spacing: 0.04em;
+}
+
+.media-timing-review-hints kbd {
+  display: inline-block;
+  min-width: 15px;
+  margin-right: 3px;
+  padding: 1px 5px;
+  border: 1px solid var(--ctp-surface1);
+  border-bottom-width: 2px;
+  border-radius: 5px;
+  background: var(--ctp-mantle);
+  color: var(--ctp-subtext0);
+  font-family: inherit;
+  font-size: 9px;
+  font-weight: 750;
+  text-align: center;
+}
+
+.media-timing-review-cancel-step {
+  min-height: 300px;
+  padding: 44px 38px 34px;
+  text-align: center;
+}
+
+.media-timing-review-cancel-mark {
+  display: grid;
+  width: 52px;
+  height: 52px;
+  margin: 0 auto 16px;
+  place-items: center;
+  border: 2px solid var(--ctp-yellow);
+  border-radius: 50%;
+  background: color-mix(in srgb, var(--ctp-yellow) 12%, transparent);
+  color: var(--ctp-yellow);
+  font-size: 26px;
+  font-weight: 760;
+}
+
+.media-timing-review-cancel-step h2 {
+  color: var(--ctp-text);
+  font-size: 21px;
+  font-weight: 760;
+}
+
+.media-timing-review-cancel-step p {
+  max-width: 520px;
+  margin: 8px auto 24px;
+  color: var(--ctp-subtext0);
+  font-size: 13px;
+  line-height: 1.5;
+}
+
+.media-timing-review-cancel-actions {
+  display: flex;
+  flex-wrap: wrap;
+  justify-content: center;
+  gap: 10px;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .media-timing-review-content {
+    animation: none;
+  }
+
+  .media-timing-review-track.is-loading::after,
+  .media-timing-review-track.is-previewing .media-timing-review-playhead {
+    animation: none;
+  }
+}
+
+@media (max-width: 640px) {
+  .media-timing-review-content {
+    width: calc(100vw - 18px);
+    max-height: calc(100vh - 18px);
+  }
+
+  .media-timing-review-header,
+  .media-timing-review-editor {
+    padding-right: 15px;
+    padding-left: 15px;
+  }
+
+  .media-timing-review-readout {
+    grid-template-columns: 1fr;
+  }
+
+  .media-timing-review-readout > div + div {
+    border-top: 1px solid var(--ctp-surface0);
+    border-left: 0;
+  }
+
+  .media-timing-review-fine-grid {
+    grid-template-columns: 1fr;
+  }
+
+  .media-timing-review-footer {
+    align-items: stretch;
+    flex-direction: column;
+  }
+
+  .media-timing-review-preview-actions > *,
+  .media-timing-review-confirm-button {
+    flex: 1;
+  }
+}
+
 body.subtitle-sidebar-embedded-open #subtitleContainer {
   max-width: min(80%, calc(100vw - var(--subtitle-sidebar-reserved-width) - 24px));
   transform: translateX(calc(var(--subtitle-sidebar-reserved-width) * -0.5));
@@ -1928,10 +2802,6 @@ body.layer-modal #overlay {
   text-align: center;
   font-size: 24px;
   line-height: 1.5;
-  /* Backstop: pathological tracks (karaoke typesetting, sign spam) must never grow
-     the hover-pause band beyond a top strip. ~4 lines at line-height 1.5. */
-  max-height: 6em;
-  overflow: hidden;
   color: #ffffff;
   -webkit-text-stroke: 0.45px rgba(0, 0, 0, 0.7);
   paint-order: stroke fill;
@@ -2191,6 +3061,142 @@ iframe[id^='yomitan-popup'],
   width: min(560px, 92%);
 }
 
+.subtitle-generation-content {
+  width: min(860px, 92%);
+  max-height: 92%;
+  border-top: 3px solid var(--ctp-green);
+}
+
+.subtitle-generation-body {
+  display: flex;
+  flex-direction: column;
+  gap: 18px;
+  overflow-y: auto;
+  scrollbar-width: thin;
+  scrollbar-color: var(--ctp-surface1) transparent;
+}
+
+.subtitle-generation-body > * {
+  flex-shrink: 0;
+}
+
+.subtitle-generation-intro {
+  margin: 0;
+  color: var(--ctp-subtext1);
+  font-size: 14px;
+  line-height: 1.65;
+}
+
+.subtitle-generation-detail {
+  padding: 12px 14px;
+  border-left: 2px solid var(--ctp-surface1);
+  background: rgba(24, 25, 38, 0.35);
+  overflow-wrap: anywhere;
+  font-size: 13px;
+}
+
+.subtitle-generation-label {
+  display: block;
+  margin-bottom: 6px;
+  color: var(--ctp-green);
+  font-size: 11px;
+  letter-spacing: 0.06em;
+  text-transform: uppercase;
+}
+
+.subtitle-generation-hint {
+  margin: 8px 0 0;
+  color: var(--ctp-subtext0);
+  font-size: 12px;
+  line-height: 1.6;
+}
+
+.subtitle-generation-model-picker {
+  margin-top: 14px;
+}
+
+.subtitle-generation-model-picker label {
+  display: block;
+  margin-bottom: 6px;
+  color: var(--ctp-subtext1);
+  font-size: 12px;
+}
+
+.subtitle-generation-model-picker select {
+  width: 100%;
+  padding: 8px 10px;
+  border: 1px solid var(--ctp-surface1);
+  border-radius: 6px;
+  background: var(--ctp-mantle);
+  color: var(--ctp-text);
+  font: inherit;
+}
+
+.subtitle-generation-model-picker select:focus-visible {
+  outline: 2px solid var(--ctp-green);
+  outline-offset: 2px;
+}
+
+.subtitle-generation-model-picker select:disabled {
+  opacity: 0.5;
+}
+
+.subtitle-generation-detail button {
+  margin-top: 12px;
+}
+
+.subtitle-generation-vad-toggle {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  cursor: pointer;
+}
+
+.subtitle-generation-vad-toggle input {
+  accent-color: var(--ctp-green);
+}
+
+.subtitle-generation-vad-toggle .subtitle-generation-hint {
+  margin: 0 0 0 auto;
+}
+
+.subtitle-generation-progress-heading {
+  display: flex;
+  justify-content: space-between;
+  margin-bottom: 9px;
+  font-size: 13px;
+}
+
+.subtitle-generation-activity progress {
+  display: block;
+  width: 100%;
+  height: 8px;
+  accent-color: var(--ctp-green);
+}
+
+.subtitle-generation-actions {
+  display: flex;
+  flex-wrap: wrap;
+  justify-content: flex-end;
+  gap: 8px;
+}
+
+.subtitle-generation-actions button:disabled,
+.subtitle-generation-detail button:disabled {
+  opacity: 0.5;
+  cursor: default;
+}
+
+.subtitle-generation-open {
+  align-self: flex-start;
+  margin: 0 16px 8px;
+  font-size: 12px;
+}
+
+.subtitle-sidebar-body:has(.subtitle-sidebar-item) .subtitle-generation-open {
+  display: none;
+}
+
 .subsync-form {
   display: flex;
   flex-direction: column;
@@ -2222,6 +3228,16 @@ iframe[id^='yomitan-popup'],
   padding: 8px 10px;
 }
 
+.subsync-field select:focus-visible {
+  outline: 2px solid var(--ctp-blue);
+  outline-offset: 2px;
+}
+
+#subtitleSelectionModal .kiku-confirm-button:disabled {
+  opacity: 0.5;
+  cursor: default;
+}
+
 .subsync-footer {
   display: flex;
   justify-content: flex-end;
@@ -2905,6 +3921,7 @@ body.subtitle-sidebar-embedded-open #subtitleSidebarContent {
 }
 
 .subtitle-sidebar-timestamp {
+  user-select: none;
   font-size: 0.72em;
   font-weight: 600;
   font-variant-numeric: tabular-nums;
@@ -2927,6 +3944,8 @@ body.subtitle-sidebar-embedded-open #subtitleSidebarContent {
 }
 
 .subtitle-sidebar-text {
+  user-select: text;
+  cursor: text;
   white-space: pre-wrap;
   line-height: 1.5;
   font-size: 1em;
diff --git a/src/renderer/subtitle-render.test.ts b/src/renderer/subtitle-render.test.ts
index 29c8e5ec..ca297908 100644
--- a/src/renderer/subtitle-render.test.ts
+++ b/src/renderer/subtitle-render.test.ts
@@ -11,6 +11,7 @@ import {
   getFrequencyRankLabelForToken,
   getJlptLevelLabelForToken,
   normalizeSubtitle,
+  normalizeSubtitleForDisplay,
   prepareSecondarySubtitleLines,
   sanitizeSubtitleHoverTokenColor,
   shouldRenderTokenizedSubtitle,
@@ -1004,6 +1005,34 @@ test('normalizeSubtitle collapses explicit line breaks when collapseLineBreaks i
   );
 });
 
+test('normalizeSubtitleForDisplay always breaks between simultaneous cues', () => {
+  // The blank line marks two distinct cues on screen at once. Flattening it would run a
+  // sign or a second speaker into the line beside it as one sentence.
+  const twoCues =
+    '\u6b21\u306f\u9b3c\u5b50\u6bcd\u795e\u524d\u3000\u9b3c\u5b50\u6bcd\u795e\u524d\n\n\u611b\u97f3\u3061\u3083\u3093\u3000\u3082\u3046\u5199\u771f\u4e0a\u3052\u3066\u308b';
+
+  assert.equal(
+    normalizeSubtitleForDisplay(twoCues, false),
+    '\u6b21\u306f\u9b3c\u5b50\u6bcd\u795e\u524d \u9b3c\u5b50\u6bcd\u795e\u524d\n\u611b\u97f3\u3061\u3083\u3093 \u3082\u3046\u5199\u771f\u4e0a\u3052\u3066\u308b',
+  );
+  assert.equal(normalizeSubtitleForDisplay(twoCues, true), twoCues.replace('\n\n', '\n'));
+});
+
+test('normalizeSubtitleForDisplay preserves CRLF boundaries between simultaneous cues', () => {
+  assert.equal(normalizeSubtitleForDisplay('a\r\n\r\nb', false), 'a\nb');
+});
+
+test('normalizeSubtitleForDisplay still flattens a wrap inside one cue', () => {
+  // A typesetter's \\N inside a single utterance is what preserveLineBreaks governs.
+  assert.equal(
+    normalizeSubtitleForDisplay(
+      '\u5e38\u4eba\u304c\u4f7f\u3048\u3070\\N\u305d\u306e\u5727\u5012\u7684\u306a\u529b\u306b',
+      false,
+    ),
+    '\u5e38\u4eba\u304c\u4f7f\u3048\u3070 \u305d\u306e\u5727\u5012\u7684\u306a\u529b\u306b',
+  );
+});
+
 test('normalizeSubtitle leaves already-decoded text alone', () => {
   // Primary subtitle text is decoded from ASS once, upstream: by mpv for live lines and
   // by the cue parser for prefetched ones. A brace that survives that is literal text.
@@ -1424,11 +1453,8 @@ test('subtitle annotation CSS underlines JLPT tokens without changing token colo
   );
 });
 
-test('prepareSecondarySubtitleLines preserves short stacks without layer metadata', () => {
+test('prepareSecondarySubtitleLines collapses exact short copies in stacks', () => {
   assert.deepEqual(prepareSecondarySubtitleLines('Your\\NYour\\NYour\\NYour\\Nmosaic'), [
-    'Your',
-    'Your',
-    'Your',
     'Your',
     'mosaic',
   ]);
@@ -1438,6 +1464,15 @@ test('prepareSecondarySubtitleLines preserves short stacks without layer metadat
   ]);
 });
 
+test('prepareSecondarySubtitleLines collapses exact short sign copies beside dialogue', () => {
+  const liveText = "And for today's sports festival...\nEntrance\nEntrance";
+
+  assert.deepEqual(prepareSecondarySubtitleLines(liveText), [
+    "And for today's sports festival...",
+    'Entrance',
+  ]);
+});
+
 test('prepareSecondarySubtitleLines collapses karaoke syllable spam into one deduped line', () => {
   // Karaoke-typeset OP/ED: one ASS event per syllable, duplicated across layers,
   // joined with \N by mpv's secondary-sub-text.
@@ -1448,10 +1483,19 @@ test('prepareSecondarySubtitleLines collapses karaoke syllable spam into one ded
   assert.deepEqual(prepareSecondarySubtitleLines(karaoke), ['ya This no ma ups']);
 });
 
-test('prepareSecondarySubtitleLines preserves repeated short dialogue without layer metadata', () => {
+test('prepareSecondarySubtitleLines collapses exact repeated short lines', () => {
   const dialogue = ['Wait', 'Wait', 'Wait'];
 
-  assert.deepEqual(prepareSecondarySubtitleLines(dialogue.join('\\N')), dialogue);
+  assert.deepEqual(prepareSecondarySubtitleLines(dialogue.join('\\N')), ['Wait']);
+});
+
+test('prepareSecondarySubtitleLines collapses punctuation variants of a full-sentence fallback', () => {
+  const dialogue = 'A question veiled as an insult!';
+  const positionedSign = 'A question veiled as an insult';
+
+  assert.deepEqual(prepareSecondarySubtitleLines([dialogue, positionedSign].join('\\N')), [
+    dialogue,
+  ]);
 });
 
 test('prepareSecondarySubtitleLines preserves short simultaneous dialogue without repeats', () => {
@@ -1460,6 +1504,10 @@ test('prepareSecondarySubtitleLines preserves short simultaneous dialogue withou
   assert.deepEqual(prepareSecondarySubtitleLines(dialogue.join('\\N')), dialogue);
 });
 
+test('prepareSecondarySubtitleLines preserves distinct short lines with internal whitespace', () => {
+  assert.deepEqual(prepareSecondarySubtitleLines('AB\\NA B'), ['AB', 'A B']);
+});
+
 test('prepareSecondarySubtitleLines keeps normal dialogue lines intact', () => {
   const dialogue = ' I never expected this. \\N\\N But here we are. ';
 
@@ -1481,13 +1529,13 @@ test('prepareSecondarySubtitleLines strips ASS override tags and handles empty i
   assert.deepEqual(prepareSecondarySubtitleLines('{\\an8}'), []);
 });
 
-test('secondary subtitle root CSS caps height so hover-pause band stays a top strip', () => {
+test('secondary subtitle root CSS does not clip long subtitle stacks', () => {
   const srcCssPath = path.join(process.cwd(), 'src', 'renderer', 'style.css');
   const cssText = fs.readFileSync(srcCssPath, 'utf-8');
 
   const secondaryRootBlock = extractClassBlock(cssText, '#secondarySubRoot');
-  assert.match(secondaryRootBlock, /max-height:\s*6em;/);
-  assert.match(secondaryRootBlock, /overflow:\s*hidden;/);
+  assert.doesNotMatch(secondaryRootBlock, /max-height\s*:/);
+  assert.doesNotMatch(secondaryRootBlock, /overflow\s*:\s*hidden/);
 });
 
 test('applySubtitleStyle sets known-word maturity color variables', () => {
diff --git a/src/renderer/subtitle-render.ts b/src/renderer/subtitle-render.ts
index 8b63c004..bccfc829 100644
--- a/src/renderer/subtitle-render.ts
+++ b/src/renderer/subtitle-render.ts
@@ -6,6 +6,7 @@ import type {
   SubtitleRendererStyleConfig,
 } from '../types';
 import { assToPlainText, normalizePlainSubtitleText } from '../core/services/ass-text.js';
+import { flattenedSecondarySubtitleLineIdentity } from '../core/services/secondary-subtitle-line-identity.js';
 import type { RendererContext } from './context';
 import { PRIMARY_SUB_VISIBLE_ON_YOMITAN_POPUP_CLASS } from './yomitan-popup.js';
 
@@ -49,6 +50,21 @@ export function normalizeSubtitle(text: string, trim = true, collapseLineBreaks
   return normalizePlainSubtitleText(text, { trim, collapseLineBreaks });
 }
 
+/**
+ * Display form of a resolved subtitle. `preserveLineBreaks` governs wrapping inside one
+ * utterance, which is what a typesetter's `\N` means. The blank line the resolver puts
+ * between two simultaneous cues is a different thing and always breaks, so a sign or a
+ * second speaker never runs into the line beside it.
+ */
+export function normalizeSubtitleForDisplay(text: string, preserveLineBreaks: boolean): string {
+  return text
+    .replace(/\r\n/g, '\n')
+    .split(/\n{2,}/)
+    .map((cueText) => normalizeSubtitle(cueText, true, !preserveLineBreaks))
+    .filter((cueText) => cueText.length > 0)
+    .join('\n');
+}
+
 const HEX_COLOR_PATTERN = /^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/;
 const SAFE_CSS_COLOR_PATTERN =
   /^(?:#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})|(?:rgba?|hsla?)\([^)]*\)|var\([^)]*\)|[a-zA-Z]+)$/;
@@ -413,16 +429,13 @@ function renderWithTokens(
   const fragment = document.createDocumentFragment();
 
   if (sourceText) {
-    const normalizedSource = normalizeSubtitle(sourceText, true, !preserveLineBreaks);
+    const normalizedSource = normalizeSubtitleForDisplay(sourceText, preserveLineBreaks);
     const segments = alignTokensToSourceText(tokens, normalizedSource);
 
     for (const segment of segments) {
       if (segment.kind === 'text') {
-        if (preserveLineBreaks) {
-          renderPlainTextPreserveLineBreaks(fragment, segment.text);
-        } else {
-          fragment.appendChild(document.createTextNode(segment.text));
-        }
+        // Normalization already resolved which breaks survive; every one left is real.
+        renderPlainTextPreserveLineBreaks(fragment, segment.text);
         continue;
       }
 
@@ -665,6 +678,22 @@ function isKaraokeLikeLineSet(lines: string[]): boolean {
   return median <= KARAOKE_MAX_MEDIAN_LINE_LENGTH;
 }
 
+function collapseFullLineFallbackCopies(lines: string[]): string[] {
+  const seenExact = new Set<string>();
+  const seenFlattened = new Set<string>();
+  return lines.filter((line) => {
+    const exactIdentity = line.normalize('NFKC');
+    if (seenExact.has(exactIdentity)) return false;
+    seenExact.add(exactIdentity);
+
+    const flattenedIdentity = flattenedSecondarySubtitleLineIdentity(line);
+    if (!flattenedIdentity) return true;
+    if (seenFlattened.has(flattenedIdentity)) return false;
+    seenFlattened.add(flattenedIdentity);
+    return true;
+  });
+}
+
 export function prepareSecondarySubtitleLines(text: string): string[] {
   // The one display-side ASS decode: secondary text also reaches the overlay from
   // websocket clients that forward their source line untouched, so unlike the primary
@@ -678,7 +707,7 @@ export function prepareSecondarySubtitleLines(text: string): string[] {
     .map((line) => line.trim())
     .filter((line) => line.length > 0);
   if (!isKaraokeLikeLineSet(lines)) {
-    return lines;
+    return collapseFullLineFallbackCopies(lines);
   }
 
   const seen = new Set<string>();
@@ -731,7 +760,7 @@ export function createSubtitleRenderer(ctx: RendererContext) {
       return;
     }
 
-    const normalized = normalizeSubtitle(text, true, !ctx.state.preserveSubtitleLineBreaks);
+    const normalized = normalizeSubtitleForDisplay(text, ctx.state.preserveSubtitleLineBreaks);
     const hasRenderableTokens =
       shouldRenderTokenizedSubtitle(tokens?.length ?? 0) && Boolean(tokens);
     if (
diff --git a/src/renderer/utils/dom.ts b/src/renderer/utils/dom.ts
index 5f6b46b2..fe9216d2 100644
--- a/src/renderer/utils/dom.ts
+++ b/src/renderer/utils/dom.ts
@@ -21,6 +21,8 @@ export type RendererDom = {
   jimakuFilesSection: HTMLDivElement;
   jimakuFilesList: HTMLUListElement;
   jimakuBroadenButton: HTMLButtonElement;
+  jimakuTabAnimeButton: HTMLButtonElement;
+  jimakuTabLiveActionButton: HTMLButtonElement;
 
   tsukihimeModal: HTMLDivElement;
   tsukihimeTitleInput: HTMLInputElement;
@@ -44,6 +46,54 @@ export type RendererDom = {
   youtubePickerStatus: HTMLDivElement;
   youtubePickerTracks: HTMLUListElement;
 
+  mediaTimingReviewFramePicker: HTMLDivElement;
+  mediaTimingReviewFrameImage: HTMLImageElement;
+  mediaTimingReviewFrameSlider: HTMLInputElement;
+  mediaTimingReviewFrameTime: HTMLElement;
+  mediaTimingReviewFrameStatus: HTMLElement;
+  mediaTimingReviewFramePrevious: HTMLButtonElement;
+  mediaTimingReviewFrameNext: HTMLButtonElement;
+  mediaTimingReviewFrameReset: HTMLButtonElement;
+  mediaTimingReviewModal: HTMLDivElement;
+  mediaTimingReviewKind: HTMLDivElement;
+  mediaTimingReviewText: HTMLElement;
+  mediaTimingReviewLineCount: HTMLElement;
+  mediaTimingReviewLineControls: HTMLDivElement;
+  mediaTimingReviewPrevAdd: HTMLButtonElement;
+  mediaTimingReviewPrevRemove: HTMLButtonElement;
+  mediaTimingReviewNextAdd: HTMLButtonElement;
+  mediaTimingReviewNextRemove: HTMLButtonElement;
+  mediaTimingReviewStartValue: HTMLElement;
+  mediaTimingReviewEndValue: HTMLElement;
+  mediaTimingReviewDuration: HTMLElement;
+  mediaTimingReviewTimelineStart: HTMLElement;
+  mediaTimingReviewTimelineEnd: HTMLElement;
+  mediaTimingReviewSelectionTrack: HTMLDivElement;
+  mediaTimingReviewWaveformLabel: HTMLElement;
+  mediaTimingReviewWaveformPath: SVGPathElement;
+  mediaTimingReviewSelectedRange: HTMLDivElement;
+  mediaTimingReviewStartHandle: HTMLDivElement;
+  mediaTimingReviewEndHandle: HTMLDivElement;
+  mediaTimingReviewShowEarlier: HTMLButtonElement;
+  mediaTimingReviewShowLater: HTMLButtonElement;
+  mediaTimingReviewStartBack: HTMLButtonElement;
+  mediaTimingReviewStartForward: HTMLButtonElement;
+  mediaTimingReviewEndBack: HTMLButtonElement;
+  mediaTimingReviewEndForward: HTMLButtonElement;
+  mediaTimingReviewPlay: HTMLButtonElement;
+  mediaTimingReviewPlayLabel: HTMLElement;
+  mediaTimingReviewReset: HTMLButtonElement;
+  mediaTimingReviewCancel: HTMLButtonElement;
+  mediaTimingReviewConfirm: HTMLButtonElement;
+  mediaTimingReviewStatus: HTMLDivElement;
+  mediaTimingReviewEditor: HTMLDivElement;
+  mediaTimingReviewCancelStep: HTMLDivElement;
+  mediaTimingReviewCancelMessage: HTMLParagraphElement;
+  mediaTimingReviewCancelBack: HTMLButtonElement;
+  mediaTimingReviewUseOriginal: HTMLButtonElement;
+  mediaTimingReviewSkipMedia: HTMLButtonElement;
+  mediaTimingReviewDiscard: HTMLButtonElement;
+
   kikuModal: HTMLDivElement;
   kikuCard1: HTMLDivElement;
   kikuCard2: HTMLDivElement;
@@ -117,6 +167,7 @@ export type RendererDom = {
   subtitleSidebarModal: HTMLDivElement;
   subtitleSidebarContent: HTMLDivElement;
   subtitleSidebarClose: HTMLButtonElement;
+  subtitleSidebarCopy: HTMLButtonElement;
   subtitleSidebarStatus: HTMLDivElement;
   subtitleSidebarList: HTMLUListElement;
 
@@ -145,8 +196,8 @@ export type RendererDom = {
   playlistBrowserClose: HTMLButtonElement;
 };
 
-function getRequiredElement<T extends HTMLElement>(id: string): T {
-  const element = document.getElementById(id);
+function getRequiredElement<T extends Element>(id: string): T {
+  const element = document.querySelector(`#${id}`);
   if (!element) {
     throw new Error(`Missing required DOM element #${id}`);
   }
@@ -177,6 +228,8 @@ export function resolveRendererDom(): RendererDom {
     jimakuFilesSection: getRequiredElement<HTMLDivElement>('jimakuFilesSection'),
     jimakuFilesList: getRequiredElement<HTMLUListElement>('jimakuFiles'),
     jimakuBroadenButton: getRequiredElement<HTMLButtonElement>('jimakuBroaden'),
+    jimakuTabAnimeButton: getRequiredElement<HTMLButtonElement>('jimakuTabAnime'),
+    jimakuTabLiveActionButton: getRequiredElement<HTMLButtonElement>('jimakuTabLiveAction'),
 
     tsukihimeModal: getRequiredElement<HTMLDivElement>('tsukihimeModal'),
     tsukihimeTitleInput: getRequiredElement<HTMLInputElement>('tsukihimeTitle'),
@@ -204,6 +257,94 @@ export function resolveRendererDom(): RendererDom {
     youtubePickerStatus: getRequiredElement<HTMLDivElement>('youtubePickerStatus'),
     youtubePickerTracks: getRequiredElement<HTMLUListElement>('youtubePickerTracks'),
 
+    mediaTimingReviewFramePicker: getRequiredElement<HTMLDivElement>(
+      'mediaTimingReviewFramePicker',
+    ),
+    mediaTimingReviewFrameImage: getRequiredElement<HTMLImageElement>(
+      'mediaTimingReviewFrameImage',
+    ),
+    mediaTimingReviewFrameSlider: getRequiredElement<HTMLInputElement>(
+      'mediaTimingReviewFrameSlider',
+    ),
+    mediaTimingReviewFrameTime: getRequiredElement<HTMLElement>('mediaTimingReviewFrameTime'),
+    mediaTimingReviewFrameStatus: getRequiredElement<HTMLElement>('mediaTimingReviewFrameStatus'),
+    mediaTimingReviewFramePrevious: getRequiredElement<HTMLButtonElement>(
+      'mediaTimingReviewFramePrevious',
+    ),
+    mediaTimingReviewFrameNext: getRequiredElement<HTMLButtonElement>('mediaTimingReviewFrameNext'),
+    mediaTimingReviewFrameReset: getRequiredElement<HTMLButtonElement>(
+      'mediaTimingReviewFrameReset',
+    ),
+    mediaTimingReviewModal: getRequiredElement<HTMLDivElement>('mediaTimingReviewModal'),
+    mediaTimingReviewKind: getRequiredElement<HTMLDivElement>('mediaTimingReviewKind'),
+    mediaTimingReviewText: getRequiredElement<HTMLElement>('mediaTimingReviewText'),
+    mediaTimingReviewLineCount: getRequiredElement<HTMLElement>('mediaTimingReviewLineCount'),
+    mediaTimingReviewLineControls: getRequiredElement<HTMLDivElement>(
+      'mediaTimingReviewLineControls',
+    ),
+    mediaTimingReviewPrevAdd: getRequiredElement<HTMLButtonElement>('mediaTimingReviewPrevAdd'),
+    mediaTimingReviewPrevRemove: getRequiredElement<HTMLButtonElement>(
+      'mediaTimingReviewPrevRemove',
+    ),
+    mediaTimingReviewNextAdd: getRequiredElement<HTMLButtonElement>('mediaTimingReviewNextAdd'),
+    mediaTimingReviewNextRemove: getRequiredElement<HTMLButtonElement>(
+      'mediaTimingReviewNextRemove',
+    ),
+    mediaTimingReviewStartValue: getRequiredElement<HTMLElement>('mediaTimingReviewStartValue'),
+    mediaTimingReviewEndValue: getRequiredElement<HTMLElement>('mediaTimingReviewEndValue'),
+    mediaTimingReviewDuration: getRequiredElement<HTMLElement>('mediaTimingReviewDuration'),
+    mediaTimingReviewTimelineStart: getRequiredElement<HTMLElement>(
+      'mediaTimingReviewTimelineStart',
+    ),
+    mediaTimingReviewTimelineEnd: getRequiredElement<HTMLElement>('mediaTimingReviewTimelineEnd'),
+    mediaTimingReviewSelectionTrack: getRequiredElement<HTMLDivElement>(
+      'mediaTimingReviewSelectionTrack',
+    ),
+    mediaTimingReviewWaveformLabel: getRequiredElement<HTMLElement>(
+      'mediaTimingReviewWaveformLabel',
+    ),
+    mediaTimingReviewWaveformPath: getRequiredElement<SVGPathElement>(
+      'mediaTimingReviewWaveformPath',
+    ),
+    mediaTimingReviewSelectedRange: getRequiredElement<HTMLDivElement>(
+      'mediaTimingReviewSelectedRange',
+    ),
+    mediaTimingReviewStartHandle: getRequiredElement<HTMLDivElement>(
+      'mediaTimingReviewStartHandle',
+    ),
+    mediaTimingReviewEndHandle: getRequiredElement<HTMLDivElement>('mediaTimingReviewEndHandle'),
+    mediaTimingReviewShowEarlier: getRequiredElement<HTMLButtonElement>(
+      'mediaTimingReviewShowEarlier',
+    ),
+    mediaTimingReviewShowLater: getRequiredElement<HTMLButtonElement>('mediaTimingReviewShowLater'),
+    mediaTimingReviewStartBack: getRequiredElement<HTMLButtonElement>('mediaTimingReviewStartBack'),
+    mediaTimingReviewStartForward: getRequiredElement<HTMLButtonElement>(
+      'mediaTimingReviewStartForward',
+    ),
+    mediaTimingReviewEndBack: getRequiredElement<HTMLButtonElement>('mediaTimingReviewEndBack'),
+    mediaTimingReviewEndForward: getRequiredElement<HTMLButtonElement>(
+      'mediaTimingReviewEndForward',
+    ),
+    mediaTimingReviewPlay: getRequiredElement<HTMLButtonElement>('mediaTimingReviewPlay'),
+    mediaTimingReviewPlayLabel: getRequiredElement<HTMLElement>('mediaTimingReviewPlayLabel'),
+    mediaTimingReviewReset: getRequiredElement<HTMLButtonElement>('mediaTimingReviewReset'),
+    mediaTimingReviewCancel: getRequiredElement<HTMLButtonElement>('mediaTimingReviewCancel'),
+    mediaTimingReviewConfirm: getRequiredElement<HTMLButtonElement>('mediaTimingReviewConfirm'),
+    mediaTimingReviewStatus: getRequiredElement<HTMLDivElement>('mediaTimingReviewStatus'),
+    mediaTimingReviewEditor: getRequiredElement<HTMLDivElement>('mediaTimingReviewEditor'),
+    mediaTimingReviewCancelStep: getRequiredElement<HTMLDivElement>('mediaTimingReviewCancelStep'),
+    mediaTimingReviewCancelMessage: getRequiredElement<HTMLParagraphElement>(
+      'mediaTimingReviewCancelMessage',
+    ),
+    mediaTimingReviewCancelBack: getRequiredElement<HTMLButtonElement>(
+      'mediaTimingReviewCancelBack',
+    ),
+    mediaTimingReviewUseOriginal: getRequiredElement<HTMLButtonElement>(
+      'mediaTimingReviewUseOriginal',
+    ),
+    mediaTimingReviewSkipMedia: getRequiredElement<HTMLButtonElement>('mediaTimingReviewSkipMedia'),
+    mediaTimingReviewDiscard: getRequiredElement<HTMLButtonElement>('mediaTimingReviewDiscard'),
+
     kikuModal: getRequiredElement<HTMLDivElement>('kikuFieldGroupingModal'),
     kikuCard1: getRequiredElement<HTMLDivElement>('kikuCard1'),
     kikuCard2: getRequiredElement<HTMLDivElement>('kikuCard2'),
@@ -295,6 +436,7 @@ export function resolveRendererDom(): RendererDom {
     subtitleSidebarModal: getRequiredElement<HTMLDivElement>('subtitleSidebarModal'),
     subtitleSidebarContent: getRequiredElement<HTMLDivElement>('subtitleSidebarContent'),
     subtitleSidebarClose: getRequiredElement<HTMLButtonElement>('subtitleSidebarClose'),
+    subtitleSidebarCopy: getRequiredElement<HTMLButtonElement>('subtitleSidebarCopy'),
     subtitleSidebarStatus: getRequiredElement<HTMLDivElement>('subtitleSidebarStatus'),
     subtitleSidebarList: getRequiredElement<HTMLUListElement>('subtitleSidebarList'),
 
diff --git a/src/runtime-options.test.ts b/src/runtime-options.test.ts
index 5c5d2e47..e07e5b9b 100644
--- a/src/runtime-options.test.ts
+++ b/src/runtime-options.test.ts
@@ -82,3 +82,19 @@ test('RuntimeOptionsManager keeps known-word and n+1 annotation toggles separate
   assert.equal(effective.nPlusOne?.enabled, true);
   assert.deepEqual(patches, []);
 });
+
+test('RuntimeOptionsManager applies media timing review to the live Anki config', () => {
+  const baseConfig = structuredClone(DEFAULT_CONFIG.ankiConnect);
+  const patches: unknown[] = [];
+  const manager = new RuntimeOptionsManager(() => structuredClone(baseConfig), {
+    applyAnkiPatch: (patch) => {
+      patches.push(patch);
+    },
+    onOptionsChanged: () => undefined,
+  });
+
+  assert.equal(manager.getOptionValue('anki.mediaReviewTiming'), false);
+  assert.equal(manager.setOptionValue('anki.mediaReviewTiming', true).ok, true);
+  assert.equal(manager.getEffectiveAnkiConnectConfig().media?.reviewTiming, true);
+  assert.deepEqual(patches, [{ media: { reviewTiming: true } }]);
+});
diff --git a/src/settings/style.css b/src/settings/style.css
index 5540b239..389fa676 100644
--- a/src/settings/style.css
+++ b/src/settings/style.css
@@ -1,6 +1,6 @@
 @font-face {
   font-family: 'M PLUS 1';
-  src: url('./fonts/MPLUS1[wght].ttf') format('truetype');
+  src: url('../fonts/MPLUS1[wght].ttf') format('truetype');
   font-weight: 100 900;
   font-display: swap;
 }
diff --git a/src/shared/ipc/contracts.ts b/src/shared/ipc/contracts.ts
index 50c3a9cc..bfc52d81 100644
--- a/src/shared/ipc/contracts.ts
+++ b/src/shared/ipc/contracts.ts
@@ -4,9 +4,12 @@ import type { RuntimeOptionId, RuntimeOptionValue } from '../../types/runtime-op
 export const OVERLAY_HOSTED_MODALS = [
   'runtime-options',
   'subsync',
+  'subtitle-selection',
+  'subtitle-generation',
   'jimaku',
   'tsukihime',
   'youtube-track-picker',
+  'media-timing-review',
   'playlist-browser',
   'kiku',
   'controller-select',
@@ -49,6 +52,16 @@ export const IPC_CHANNELS = {
     dispatchSessionAction: 'session-action:dispatch',
   },
   request: {
+    getSubtitleSelection: 'subtitle-selection:get',
+    applySubtitleSelection: 'subtitle-selection:apply',
+    requestSubtitleGenerationOpen: 'subtitle-generation:open',
+    getSubtitleGenerationStatus: 'subtitle-generation:status',
+    startSubtitleGeneration: 'subtitle-generation:start',
+    selectSubtitleGenerationModel: 'subtitle-generation:select-model',
+    downloadSubtitleGenerationModel: 'subtitle-generation:download',
+    downloadSubtitleGenerationVadModel: 'subtitle-generation:download-vad',
+    setSubtitleGenerationVadEnabled: 'subtitle-generation:set-vad-enabled',
+    cancelSubtitleGeneration: 'subtitle-generation:cancel',
     getVisibleOverlayVisibility: 'get-visible-overlay-visibility',
     getCurrentSubtitle: 'get-current-subtitle',
     getCurrentSubtitleRaw: 'get-current-subtitle-raw',
@@ -60,6 +73,7 @@ export const IPC_CHANNELS = {
     getSubtitleStyle: 'get-subtitle-style',
     getMecabStatus: 'get-mecab-status',
     getKeybindings: 'get-keybindings',
+    getMpvInputBindings: 'get-mpv-input-bindings',
     getSessionBindings: 'get-session-bindings',
     getConfigShortcuts: 'get-config-shortcuts',
     getStatsToggleKey: 'get-stats-toggle-key',
@@ -125,8 +139,16 @@ export const IPC_CHANNELS = {
     syncUiRevealSnapshot: 'sync-ui:reveal-snapshot',
     syncUiPickSnapshotFile: 'sync-ui:pick-snapshot-file',
     getChangelogSnapshot: 'changelog:get-snapshot',
+    mediaTimingReviewPreview: 'media-timing-review:preview',
+    mediaTimingReviewWaveform: 'media-timing-review:waveform',
+    mediaTimingReviewFrame: 'media-timing-review:frame',
+    mediaTimingReviewStopPreview: 'media-timing-review:stop-preview',
+    mediaTimingReviewResolve: 'media-timing-review:resolve',
   },
   event: {
+    subtitleSelectionOpen: 'subtitle-selection:opened',
+    subtitleGenerationOpen: 'subtitle-generation:opened',
+    subtitleGenerationProgress: 'subtitle-generation:progress',
     subtitleSet: 'subtitle:set',
     overlayPointerRecoveryRequest: 'overlay:pointer-recovery-request',
     subtitleVisibility: 'mpv:subVisibility',
@@ -142,6 +164,8 @@ export const IPC_CHANNELS = {
     jimakuOpen: 'jimaku:open',
     tsukihimeOpen: 'tsukihime:open',
     youtubePickerOpen: 'youtube:picker-open',
+    mediaTimingReviewOpen: 'media-timing-review:open',
+    mediaTimingReviewPreviewEnded: 'media-timing-review:preview-ended',
     youtubePickerCancel: 'youtube:picker-cancel',
     playlistBrowserOpen: 'playlist-browser:open',
     sessionNumericSelectionStart: 'session:numeric-selection-start',
@@ -154,6 +178,7 @@ export const IPC_CHANNELS = {
     controllerDebugOpen: 'controller-debug:open',
     subtitleSidebarToggle: 'subtitle-sidebar:toggle',
     primarySubtitleBarToggle: 'primary-subtitle-bar:toggle',
+    sessionBindingsChanged: 'session-bindings:changed',
     configHotReload: 'config:hot-reload',
     overlayNotification: 'overlay:notification',
     notificationHistoryToggle: 'notification-history:toggle',
diff --git a/src/shared/ipc/validators.ts b/src/shared/ipc/validators.ts
index 6487e3a3..26dca4fb 100644
--- a/src/shared/ipc/validators.ts
+++ b/src/shared/ipc/validators.ts
@@ -44,6 +44,8 @@ const SESSION_ACTION_IDS: SessionActionId[] = [
   'openControllerDebug',
   'openJimaku',
   'openTsukihime',
+  'openSubtitleSelection',
+  'openSubtitleGeneration',
   'openYoutubePicker',
   'openPlaylistBrowser',
   'replayCurrentSubtitle',
@@ -53,12 +55,14 @@ const SESSION_ACTION_IDS: SessionActionId[] = [
 
 const RUNTIME_OPTION_IDS: RuntimeOptionId[] = [
   'anki.autoUpdateNewCards',
+  'anki.mediaReviewTiming',
   'subtitle.annotation.knownWords.highlightEnabled',
   'subtitle.annotation.knownWords.maturityEnabled',
   'subtitle.annotation.nPlusOne',
   'subtitle.annotation.jlpt',
   'subtitle.annotation.frequency',
   'anki.kikuFieldGrouping',
+  'anki.senrenFieldGrouping',
   'anki.nPlusOneMatchMode',
 ];
 
@@ -390,7 +394,14 @@ export function parseKikuMergePreviewRequest(value: unknown): KikuMergePreviewRe
 
 export function parseJimakuSearchQuery(value: unknown): JimakuSearchQuery | null {
   if (!isObject(value) || typeof value.query !== 'string') return null;
-  return { query: value.query };
+  if (
+    value.category !== undefined &&
+    value.category !== 'anime' &&
+    value.category !== 'liveAction'
+  ) {
+    return null;
+  }
+  return { query: value.query, category: value.category };
 }
 
 export function parseJimakuFilesQuery(value: unknown): JimakuFilesQuery | null {
diff --git a/src/shared/media-identity.test.ts b/src/shared/media-identity.test.ts
new file mode 100644
index 00000000..85ebaa83
--- /dev/null
+++ b/src/shared/media-identity.test.ts
@@ -0,0 +1,37 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { sanitizeMediaTitle, toMediaIdentityPath } from './media-identity';
+
+test('media identity separates authenticated transport URLs from titles and stats keys', () => {
+  const url =
+    'https://user:password@jellyfin.example/Videos/item-1/stream?api_key=test-secret#token';
+  assert.equal(sanitizeMediaTitle(url), null);
+  assert.equal(sanitizeMediaTitle('stream?static=true&api_key=test-secret'), null);
+  assert.equal(sanitizeMediaTitle('stream static true api key test secret'), null);
+  assert.equal(sanitizeMediaTitle('stream%3Fapi_key%3Dtest-secret'), null);
+  assert.equal(sanitizeMediaTitle('  My Anime S01E02  '), 'My Anime S01E02');
+  assert.equal(toMediaIdentityPath(url), 'jellyfin://jellyfin.example/item/item-1');
+  assert.equal(
+    toMediaIdentityPath('https://example.com/base/Videos/item-1/master.m3u8?token=secret'),
+    'jellyfin://example.com/item/item-1',
+  );
+  assert.equal(toMediaIdentityPath('stream?api_key=test-secret'), '');
+  assert.equal(toMediaIdentityPath('/media/My Anime S01E02.mkv'), '/media/My Anime S01E02.mkv');
+});
+
+test('remote stats identities drop credentials while preserving YouTube video identity', () => {
+  assert.match(
+    toMediaIdentityPath('https://user:password@example.com/video.mkv?signature=secret#secret'),
+    /^https:\/\/example\.com\/video\.mkv#query-[a-f0-9]{64}$/,
+  );
+  assert.notEqual(
+    toMediaIdentityPath('https://example.com/video?id=1'),
+    toMediaIdentityPath('https://example.com/video?id=2'),
+  );
+  const identity = toMediaIdentityPath('https://example.com/video?id=1');
+  assert.equal(toMediaIdentityPath(identity), identity);
+  assert.equal(
+    toMediaIdentityPath('https://www.youtube.com/watch?v=video-id&token=secret'),
+    'https://www.youtube.com/watch?v=video-id',
+  );
+});
diff --git a/src/shared/media-identity.ts b/src/shared/media-identity.ts
new file mode 100644
index 00000000..68b84f56
--- /dev/null
+++ b/src/shared/media-identity.ts
@@ -0,0 +1,58 @@
+import { createHash } from 'node:crypto';
+
+const URL_SCHEME = /[a-z][a-z0-9+.-]*:\/\//i;
+const QUERY_PAIR = /[?&][^=\s&#]+=/;
+const CREDENTIAL_LABEL = /\b(?:api[_ -]?key|access[_ -]?token|x[_ -]?emby[_ -]?token)\b/i;
+
+/** mpv can report the URL or its query-bearing basename before metadata arrives. */
+export function sanitizeMediaTitle(value: string | null | undefined): string | null {
+  const title = value?.trim();
+  if (!title) return null;
+  let decoded = title;
+  try {
+    decoded = decodeURIComponent(title);
+  } catch {
+    // Ordinary titles can contain a literal percent sign.
+  }
+  if (URL_SCHEME.test(decoded) || QUERY_PAIR.test(decoded) || CREDENTIAL_LABEL.test(decoded)) {
+    return null;
+  }
+  return title;
+}
+
+export function resolveMediaLookupTarget(
+  mediaPath: string | null,
+  mediaTitle: string | null,
+): string | null {
+  return sanitizeMediaTitle(mediaPath) ?? sanitizeMediaTitle(mediaTitle);
+}
+
+/** Persistent identity, never a URL to use for authenticated media retrieval. */
+export function toMediaIdentityPath(mediaPath: string): string {
+  const value = mediaPath.trim();
+  if (!URL_SCHEME.test(value)) return sanitizeMediaTitle(value) ?? '';
+  try {
+    const url = new URL(value);
+    const jellyfinItem = url.pathname.match(
+      /\/Videos\/([^/]+)\/(?:stream(?:\.[^/]*)?|master\.m3u8)\/?$/i,
+    );
+    if (jellyfinItem) return `jellyfin://${url.host}/item/${jellyfinItem[1]}`;
+    url.username = '';
+    url.password = '';
+    const query = url.search;
+    const queryFingerprint = /^#query-[a-f0-9]{64}$/.test(url.hash) ? url.hash : '';
+    const youtubeId = /^(?:www\.|m\.)?youtube\.com$/i.test(url.hostname)
+      ? url.searchParams.get('v')
+      : null;
+    url.search = '';
+    url.hash = queryFingerprint;
+    if (youtubeId) url.searchParams.set('v', youtubeId);
+    else if (query) {
+      // Different query-selected videos must not collapse into one stats entry.
+      url.hash = `query-${createHash('sha256').update(query).digest('hex')}`;
+    }
+    return url.toString();
+  } catch {
+    return '';
+  }
+}
diff --git a/src/shared/media-kind.ts b/src/shared/media-kind.ts
new file mode 100644
index 00000000..a17f53c4
--- /dev/null
+++ b/src/shared/media-kind.ts
@@ -0,0 +1,37 @@
+/**
+ * Library entry classification shared by the tracker, the stats HTTP layer and
+ * the stats SPA. Anime entries link to AniList, live-action entries link to
+ * TMDB, and YouTube entries are channels grouping tracked videos.
+ */
+export const MEDIA_KINDS = ['anime', 'live_action', 'youtube'] as const;
+export type MediaKind = (typeof MEDIA_KINDS)[number];
+
+export const TMDB_MEDIA_TYPES = ['tv', 'movie'] as const;
+export type TmdbMediaType = (typeof TMDB_MEDIA_TYPES)[number];
+
+export function isMediaKind(value: unknown): value is MediaKind {
+  return typeof value === 'string' && (MEDIA_KINDS as readonly string[]).includes(value);
+}
+
+export function isTmdbMediaType(value: unknown): value is TmdbMediaType {
+  return typeof value === 'string' && (TMDB_MEDIA_TYPES as readonly string[]).includes(value);
+}
+
+/**
+ * Anime and live-action entries share one title namespace: both come from the
+ * filename/Jellyfin parser and an entry switches between them when it is
+ * relinked from AniList to TMDB or back. YouTube channels are a separate
+ * namespace, so a channel never combines with a series entry and a same-named
+ * anime and channel stay separate.
+ */
+export function shareTitleNamespace(a: MediaKind, b: MediaKind): boolean {
+  return (a === 'youtube') === (b === 'youtube');
+}
+
+/**
+ * SQL predicate matching rows in the same title namespace as the bound kind
+ * parameter (the SQL twin of `shareTitleNamespace`).
+ */
+export function sameTitleNamespaceSql(column = 'media_kind'): string {
+  return `(${column} = 'youtube') = (? = 'youtube')`;
+}
diff --git a/src/shared/mpv-input-bindings.test.ts b/src/shared/mpv-input-bindings.test.ts
new file mode 100644
index 00000000..c001fc73
--- /dev/null
+++ b/src/shared/mpv-input-bindings.test.ts
@@ -0,0 +1,115 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import {
+  keyboardEventToMpvKey,
+  normalizeMpvInputKey,
+  parseMpvInputBindingKeys,
+} from './mpv-input-bindings';
+
+test('mpv discovery validates entries and excludes inactive, mouse, sequence, and SubMiner keys', () => {
+  assert.deepEqual(
+    parseMpvInputBindingKeys([
+      { key: 'r', cmd: 'script-binding replay/run', priority: 1, owner: 'replay' },
+      { key: 'r', cmd: 'show-text duplicate', priority: 0 },
+      { key: 'Ctrl+A', cmd: 'show-text shifted', priority: 1 },
+      { key: 'g-g', cmd: 'seek 0', priority: 1 },
+      { key: 'MBTN_LEFT', cmd: 'cycle pause', priority: 1 },
+      { key: 'q', cmd: 'quit', priority: -1 },
+      { key: 's', cmd: 'screenshot', priority: 1 },
+      { key: 's', cmd: 'script-binding subminer/session', priority: 5, owner: 'subminer' },
+      { key: 't', cmd: 'script-message subminer-toggle', priority: 1 },
+      { key: 'x', cmd: 'ignore', priority: NaN },
+      { key: 'z', cmd: 5, priority: 1 },
+      null,
+    ]),
+    ['r', 'ctrl+A'],
+  );
+  assert.deepEqual(parseMpvInputBindingKeys({ key: 'r' }), []);
+});
+
+test('mpv keys retain printable characters and normalize modifiers', () => {
+  assert.equal(normalizeMpvInputKey('Alt+Ctrl+Shift+a'), 'ctrl+alt+A');
+  assert.equal(normalizeMpvInputKey('Ctrl++'), 'ctrl++');
+  assert.equal(normalizeMpvInputKey('Shift+LEFT'), 'shift+LEFT');
+  assert.equal(normalizeMpvInputKey('F12'), 'F12');
+  assert.equal(normalizeMpvInputKey('UNMAPPED'), null);
+});
+
+test('keyboard conversion respects layout characters and skips composition and AltGr', () => {
+  const event = {
+    key: 'A',
+    ctrlKey: true,
+    shiftKey: true,
+    altKey: false,
+    metaKey: false,
+    isComposing: false,
+    getModifierState: () => false,
+  };
+  assert.equal(keyboardEventToMpvKey(event), 'ctrl+A');
+  assert.equal(keyboardEventToMpvKey({ ...event, key: '#', ctrlKey: false }), 'SHARP');
+  assert.equal(keyboardEventToMpvKey({ ...event, key: 'ArrowLeft', ctrlKey: false }), 'shift+LEFT');
+  assert.equal(keyboardEventToMpvKey({ ...event, key: 'Dead' }), null);
+  assert.equal(keyboardEventToMpvKey({ ...event, isComposing: true }), null);
+  assert.equal(
+    keyboardEventToMpvKey({ ...event, getModifierState: (key) => key === 'AltGraph' }),
+    null,
+  );
+});
+
+test('only the highest-priority active binding determines SubMiner ownership', () => {
+  const user = { key: 'r', cmd: 'script-binding replay/run', is_weak: false, priority: 12 };
+  const plugin = {
+    key: 'r',
+    cmd: 'script-binding subminer/run',
+    owner: 'subminer',
+    is_weak: true,
+    priority: 2,
+  };
+  assert.deepEqual(parseMpvInputBindingKeys([plugin, user]), ['r']);
+  assert.deepEqual(parseMpvInputBindingKeys([user, plugin]), ['r']);
+  assert.deepEqual(parseMpvInputBindingKeys([user, { ...plugin, priority: -1 }]), ['r']);
+  assert.deepEqual(
+    parseMpvInputBindingKeys([user, { ...plugin, is_weak: false, priority: 15 }]),
+    [],
+  );
+});
+
+test('SubMiner ownership excludes only its script commands and respects explicit owners', () => {
+  assert.deepEqual(
+    parseMpvInputBindingKeys([
+      { key: 'a', cmd: 'show-text "subminer/readme"', priority: 1 },
+      { key: 'b', cmd: 'run subminer-helper', priority: 1 },
+      { key: 'c', cmd: 'script-message subminer-toggle', owner: 'other-script', priority: 1 },
+      { key: 'd', cmd: 'script-binding subminer/action', owner: 'other-script', priority: 1 },
+      { key: 'e', cmd: '  script-binding "subminer/action"', priority: 1 },
+      { key: 'f', cmd: 'script-message subminer-toggle', priority: 1 },
+      { key: 'g', cmd: 'ignore', owner: 'subminer', priority: 1 },
+    ]),
+    ['a', 'b', 'c', 'd'],
+  );
+});
+
+test('SubMiner ownership recognizes leading mpv prefixes without matching command arguments', () => {
+  assert.deepEqual(
+    parseMpvInputBindingKeys([
+      { key: 'a', cmd: 'no-osd script-binding subminer/action', priority: 1 },
+      { key: 'b', cmd: '  repeatable\tasync raw script-binding "subminer/action"', priority: 1 },
+      { key: 'c', cmd: 'osd-msg-bar sync script-message subminer-toggle', priority: 1 },
+      { key: 'd', cmd: 'no-osd show-text "script-binding subminer/action"', priority: 1 },
+      { key: 'e', cmd: 'show-text "no-osd script-binding subminer/action"', priority: 1 },
+      { key: 'f', cmd: 'no-osd script-binding other/action', priority: 1 },
+      { key: 'g', cmd: 'no-osd script-binding subminer/action', owner: 'other', priority: 1 },
+    ]),
+    ['d', 'e', 'f', 'g'],
+  );
+});
+
+test('sequence conflict discovery allows winning ignore bindings used by mpv sequence prefixes', () => {
+  const bindings = [
+    { key: 'g', cmd: 'show-text old', priority: 0 },
+    { key: 'g', cmd: 'no-osd ignore', priority: 1 },
+    { key: 'h', cmd: 'show-text action', priority: 0 },
+  ];
+  assert.deepEqual(parseMpvInputBindingKeys(bindings), ['g', 'h']);
+  assert.deepEqual(parseMpvInputBindingKeys(bindings, { includeIgnored: false }), ['h']);
+});
diff --git a/src/shared/mpv-input-bindings.ts b/src/shared/mpv-input-bindings.ts
new file mode 100644
index 00000000..4eb344db
--- /dev/null
+++ b/src/shared/mpv-input-bindings.ts
@@ -0,0 +1,110 @@
+const SPECIAL_KEYS: Record<string, string> = {
+  ' ': 'SPACE',
+  '#': 'SHARP',
+  Enter: 'ENTER',
+  Escape: 'ESC',
+  Backspace: 'BS',
+  Tab: 'TAB',
+  Delete: 'DEL',
+  Insert: 'INS',
+  Home: 'HOME',
+  End: 'END',
+  PageUp: 'PGUP',
+  PageDown: 'PGDWN',
+  ArrowLeft: 'LEFT',
+  ArrowRight: 'RIGHT',
+  ArrowUp: 'UP',
+  ArrowDown: 'DOWN',
+};
+const MPV_SPECIAL_KEYS = new Set(Object.values(SPECIAL_KEYS));
+// Leading command flags accepted by mpv's input/cmd.c, before the command name.
+const MPV_COMMAND_PREFIXES =
+  /^(?:(?:no-osd|osd-bar|osd-msg|osd-msg-bar|osd-auto|expand-properties|raw|repeatable|nonrepeatable|nonscalable|async|sync)\s+)+/;
+
+// Only single keyboard strokes are imported. Mouse input and sequences need
+// their own focus and conflict rules before they can be forwarded safely.
+export function normalizeMpvInputKey(value: string): string | null {
+  const modifiers = new Set<string>();
+  let key = value;
+  let modifier = /^(Shift|Ctrl|Alt|Meta)\+/i.exec(key);
+  while (modifier?.[1]) {
+    modifiers.add(modifier[1].toLowerCase());
+    key = key.slice(modifier[0].length);
+    modifier = /^(Shift|Ctrl|Alt|Meta)\+/i.exec(key);
+  }
+  if (key === 'SHARP') modifiers.delete('shift');
+  if (!MPV_SPECIAL_KEYS.has(key) && !/^F(?:[1-9]|1[0-9]|2[0-4])$/.test(key)) {
+    if ([...key].length !== 1) return null;
+    if (modifiers.has('shift') && /^[a-z]$/i.test(key)) key = key.toUpperCase();
+    modifiers.delete('shift');
+  }
+  return [...['ctrl', 'alt', 'shift', 'meta'].filter((item) => modifiers.has(item)), key].join('+');
+}
+
+export function keyboardEventToMpvKey(
+  event: Pick<
+    KeyboardEvent,
+    'key' | 'ctrlKey' | 'altKey' | 'shiftKey' | 'metaKey' | 'isComposing' | 'getModifierState'
+  >,
+): string | null {
+  if (event.isComposing || event.key === 'Dead' || event.getModifierState?.('AltGraph'))
+    return null;
+  const key = SPECIAL_KEYS[event.key] ?? event.key;
+  const modifiers = [
+    ...(event.ctrlKey ? ['ctrl'] : []),
+    ...(event.altKey ? ['alt'] : []),
+    ...(event.shiftKey ? ['shift'] : []),
+    ...(event.metaKey ? ['meta'] : []),
+  ];
+  return normalizeMpvInputKey([...modifiers, key].join('+'));
+}
+
+export function parseMpvInputBindingKeys(
+  value: unknown,
+  { includeIgnored = true }: { includeIgnored?: boolean } = {},
+): string[] {
+  if (!Array.isArray(value)) return [];
+  const bindings = new Map<string, { priority: number; owned: boolean; ignored: boolean }>();
+  for (const candidate of value) {
+    const entry: unknown = candidate;
+    if (
+      !entry ||
+      typeof entry !== 'object' ||
+      !('key' in entry) ||
+      typeof entry.key !== 'string' ||
+      !('cmd' in entry) ||
+      typeof entry.cmd !== 'string' ||
+      !('priority' in entry) ||
+      typeof entry.priority !== 'number' ||
+      !Number.isFinite(entry.priority) ||
+      entry.priority < 0
+    )
+      continue;
+    const key = normalizeMpvInputKey(entry.key);
+    if (!key) continue;
+    const owner = 'owner' in entry ? entry.owner : undefined;
+    const owned =
+      owner === 'subminer' ||
+      (owner === undefined &&
+        /^(?:script-binding\s+["']?subminer\/|script-message\s+["']?subminer-)/.test(
+          entry.cmd.trimStart().replace(MPV_COMMAND_PREFIXES, ''),
+        ));
+    const previous = bindings.get(key);
+    // mpv's reported priority already ranks active non-weak bindings above weak
+    // bindings. Only the winning binding determines whether the key is imported.
+    if (
+      !previous ||
+      entry.priority > previous.priority ||
+      (entry.priority === previous.priority && owned)
+    ) {
+      bindings.set(key, {
+        priority: entry.priority,
+        owned,
+        ignored: entry.cmd.trim().replace(MPV_COMMAND_PREFIXES, '') === 'ignore',
+      });
+    }
+  }
+  return [...bindings]
+    .filter(([, binding]) => !binding.owned && (includeIgnored || !binding.ignored))
+    .map(([key]) => key);
+}
diff --git a/src/shared/session-key-sequences.ts b/src/shared/session-key-sequences.ts
new file mode 100644
index 00000000..cc0757d8
--- /dev/null
+++ b/src/shared/session-key-sequences.ts
@@ -0,0 +1,71 @@
+import type {
+  CompiledSessionBinding,
+  SessionBindingWarning,
+  SessionKeySpec,
+} from '../types/session-bindings';
+
+export interface SessionKeyReservation {
+  key: SessionKeySpec;
+  path: string;
+}
+
+export function getSessionSequencePrefix(key: SessionKeySpec): SessionKeySpec | null {
+  const match = /^(Key[A-Z])-Key[A-Z]$/.exec(key.code);
+  return match?.[1] ? { code: match[1], modifiers: key.modifiers } : null;
+}
+
+function signature(key: SessionKeySpec): string {
+  return [...key.modifiers, key.code].join('+');
+}
+
+export function resolveSessionSequenceConflicts(
+  bindings: CompiledSessionBinding[],
+  reservations: SessionKeyReservation[] = [],
+): { bindings: CompiledSessionBinding[]; warnings: SessionBindingWarning[] } {
+  const singles = new Map<string, string[]>();
+  for (const { key, path } of [
+    ...bindings.map((binding) => ({ key: binding.key, path: binding.sourcePath })),
+    ...reservations,
+  ]) {
+    if (getSessionSequencePrefix(key)) continue;
+    const id = signature(key);
+    singles.set(id, [...(singles.get(id) ?? []), path]);
+  }
+  const warnings: SessionBindingWarning[] = [];
+  const effective = bindings.filter((binding) => {
+    const prefix = getSessionSequencePrefix(binding.key);
+    if (!prefix) return true;
+    const conflicts = singles.get(signature(prefix));
+    if (!conflicts?.length) return true;
+    const paths = [...new Set(conflicts)];
+    warnings.push({
+      kind: 'conflict',
+      path: binding.sourcePath,
+      value: binding.originalKey,
+      conflictingPaths: paths,
+      message: `Disabled sequence "${binding.originalKey}" (${binding.sourcePath}): its first key is reserved by ${paths.join(', ')}. Single-key bindings take priority; remap the sequence or its conflicting binding.`,
+    });
+    return false;
+  });
+  return { bindings: effective, warnings };
+}
+
+// Imported mpv keys preserve case: g and G are different strokes.
+export function reserveMpvSequencePrefixes(keys: string[]): SessionKeyReservation[] {
+  return keys.flatMap((value) => {
+    const parts = value.split('+');
+    const letter = parts.pop();
+    if (!letter || !/^[a-z]$/i.test(letter)) return [];
+    const modifiers: SessionKeySpec['modifiers'] = [];
+    if (parts.includes('ctrl')) modifiers.push('ctrl');
+    if (parts.includes('alt')) modifiers.push('alt');
+    if (parts.includes('shift') || /^[A-Z]$/.test(letter)) modifiers.push('shift');
+    if (parts.includes('meta')) modifiers.push('meta');
+    return [
+      {
+        key: { code: `Key${letter.toUpperCase()}`, modifiers },
+        path: `mpv input binding "${value}"`,
+      },
+    ];
+  });
+}
diff --git a/src/shared/subtitle-generation-ipc.ts b/src/shared/subtitle-generation-ipc.ts
new file mode 100644
index 00000000..c508bf85
--- /dev/null
+++ b/src/shared/subtitle-generation-ipc.ts
@@ -0,0 +1,24 @@
+import type {
+  SubtitleGenerationAcceleration,
+  SubtitleGenerationConfig,
+  SubtitleGenerationModelStatus,
+  SubtitleGenerationProgress,
+  SubtitleGenerationTools,
+} from './subtitle-generation';
+
+export type SubtitleGenerationResult =
+  | { ok: true; message: string; outputPath?: string }
+  | { ok: false; message: string };
+
+export interface SubtitleGenerationStatus {
+  model: SubtitleGenerationModelStatus;
+  vad: { enabled: boolean; model: SubtitleGenerationModelStatus };
+  tools: SubtitleGenerationTools;
+  acceleration: SubtitleGenerationAcceleration;
+  managedModel: SubtitleGenerationConfig['managedModel'];
+  externalModelPath: string | null;
+  mediaPath: string | null;
+  running: boolean;
+  progress: SubtitleGenerationProgress | null;
+  lastResult: SubtitleGenerationResult | null;
+}
diff --git a/src/shared/subtitle-generation-model-catalog.ts b/src/shared/subtitle-generation-model-catalog.ts
new file mode 100644
index 00000000..b889030a
--- /dev/null
+++ b/src/shared/subtitle-generation-model-catalog.ts
@@ -0,0 +1,164 @@
+// Official multilingual models from whisper.cpp/models/download-ggml-model.sh.
+// Byte sizes and SHA256: https://huggingface.co/api/models/ggerganov/whisper.cpp/tree/main.
+const MODEL_CATALOG = {
+  tiny: {
+    id: 'tiny',
+    size: 77691713,
+    sha256: 'be07e048e1e599ad46341c8d2a135645097a538221678b7acdd1b1919c6e1b21',
+    description: 'Fastest and lightest; more transcription errors.',
+  },
+  'tiny-q5_1': {
+    id: 'tiny-q5_1',
+    size: 32152673,
+    sha256: '818710568da3ca15689e31a743197b520007872ff9576237bda97bd1b469c3d7',
+    description:
+      'tiny with 5-bit quantization: lower memory use, with a possible accuracy tradeoff.',
+  },
+  'tiny-q8_0': {
+    id: 'tiny-q8_0',
+    size: 43537433,
+    sha256: 'c2085835d3f50733e2ff6e4b41ae8a2b8d8110461e18821b09a15c40c42d1cca',
+    description:
+      'tiny with 8-bit quantization: lower memory use, with a possible accuracy tradeoff.',
+  },
+  base: {
+    id: 'base',
+    size: 147951465,
+    sha256: '60ed5bc3dd14eea856493d334349b405782ddcaf0028d4b5df4088345fba2efe',
+    description: 'Fast and lightweight; less accurate than small.',
+  },
+  'base-q5_1': {
+    id: 'base-q5_1',
+    size: 59707625,
+    sha256: '422f1ae452ade6f30a004d7e5c6a43195e4433bc370bf23fac9cc591f01a8898',
+    description:
+      'base with 5-bit quantization: lower memory use, with a possible accuracy tradeoff.',
+  },
+  'base-q8_0': {
+    id: 'base-q8_0',
+    size: 81768585,
+    sha256: 'c577b9a86e7e048a0b7eada054f4dd79a56bbfa911fbdacf900ac5b567cbb7d9',
+    description:
+      'base with 8-bit quantization: lower memory use, with a possible accuracy tradeoff.',
+  },
+  small: {
+    id: 'small',
+    size: 487601967,
+    sha256: '1be3a9b2063867b937e64e2ec7483364a79917e157fa98c5d94b5c1fffea987b',
+    description: 'Balances accuracy and processing time with modest memory requirements.',
+  },
+  'small-q5_1': {
+    id: 'small-q5_1',
+    size: 190085487,
+    sha256: 'ae85e4a935d7a567bd102fe55afc16bb595bdb618e11b2fc7591bc08120411bb',
+    description:
+      'small with 5-bit quantization: lower memory use, with a possible accuracy tradeoff.',
+  },
+  'small-q8_0': {
+    id: 'small-q8_0',
+    size: 264464607,
+    sha256: '49c8fb02b65e6049d5fa6c04f81f53b867b5ec9540406812c643f177317f779f',
+    description:
+      'small with 8-bit quantization: lower memory use, with a possible accuracy tradeoff.',
+  },
+  medium: {
+    id: 'medium',
+    size: 1533763059,
+    sha256: '6c14d5adee5f86394037b4e4e8b59f1673b6cee10e3cf0b11bbdbee79c156208',
+    description: 'Prioritizes accuracy over small; takes longer to process.',
+  },
+  'medium-q5_0': {
+    id: 'medium-q5_0',
+    size: 539212467,
+    sha256: '19fea4b380c3a618ec4723c3eef2eb785ffba0d0538cf43f8f235e7b3b34220f',
+    description:
+      'medium with 5-bit quantization: lower memory use, with a possible accuracy tradeoff.',
+  },
+  'medium-q8_0': {
+    id: 'medium-q8_0',
+    size: 823369779,
+    sha256: '42a1ffcbe4167d224232443396968db4d02d4e8e87e213d3ee2e03095dea6502',
+    description:
+      'medium with 8-bit quantization: lower memory use, with a possible accuracy tradeoff.',
+  },
+  'large-v1': {
+    id: 'large-v1',
+    size: 3094623691,
+    sha256: '7d99f41a10525d0206bddadd86760181fa920438b6b33237e3118ff6c83bb53d',
+    description: 'Older large model; high memory use and longer processing.',
+  },
+  'large-v2': {
+    id: 'large-v2',
+    size: 3094623691,
+    sha256: '9a423fe4d40c82774b6af34115b8b935f34152246eb19e80e376071d3f999487',
+    description: 'Older large model; high memory use and longer processing.',
+  },
+  'large-v2-q5_0': {
+    id: 'large-v2-q5_0',
+    size: 1080732091,
+    sha256: '3a214837221e4530dbc1fe8d734f302af393eb30bd0ed046042ebf4baf70f6f2',
+    description:
+      'large-v2 with 5-bit quantization: lower memory use, with a possible accuracy tradeoff.',
+  },
+  'large-v2-q8_0': {
+    id: 'large-v2-q8_0',
+    size: 1656129691,
+    sha256: 'fef54e6d898246a65c8285bfa83bd1807e27fadf54d5d4e81754c47634737e8c',
+    description:
+      'large-v2 with 8-bit quantization: lower memory use, with a possible accuracy tradeoff.',
+  },
+  'large-v3': {
+    id: 'large-v3',
+    size: 3095033483,
+    sha256: '64d182b440b98d5203c4f9bd541544d84c605196c4f7b845dfa11fb23594d1e2',
+    description: 'Prioritizes accuracy; high memory use and longer processing.',
+  },
+  'large-v3-q5_0': {
+    id: 'large-v3-q5_0',
+    size: 1081140203,
+    sha256: 'd75795ecff3f83b5faa89d1900604ad8c780abd5739fae406de19f23ecd98ad1',
+    description:
+      'large-v3 with 5-bit quantization: lower memory use, with a possible accuracy tradeoff.',
+  },
+  'large-v3-turbo': {
+    id: 'large-v3-turbo',
+    size: 1624555275,
+    sha256: '1fc70f774d38eb169993ac391eea357ef47c88757ef72ee5943879b7e8e2bc69',
+    description: 'Faster large-v3 variant with an accuracy tradeoff; uses more memory than small.',
+  },
+  'large-v3-turbo-q5_0': {
+    id: 'large-v3-turbo-q5_0',
+    size: 574041195,
+    sha256: '394221709cd5ad1f40c46e6031ca61bce88931e6e088c188294c6d5a55ffa7e2',
+    description:
+      'large-v3-turbo with 5-bit quantization: lower memory use, with a possible accuracy tradeoff.',
+  },
+  'large-v3-turbo-q8_0': {
+    id: 'large-v3-turbo-q8_0',
+    size: 874188075,
+    sha256: '317eb69c11673c9de1e1f0d459b253999804ec71ac4c23c17ecf5fbe24e259a1',
+    description:
+      'large-v3-turbo with 8-bit quantization: lower memory use, with a possible accuracy tradeoff.',
+  },
+} as const;
+
+export type SubtitleGenerationModelId = keyof typeof MODEL_CATALOG;
+
+export const SUBTITLE_GENERATION_MODELS = Object.values(MODEL_CATALOG);
+
+export const RECOMMENDED_SUBTITLE_GENERATION_MODEL = 'small' satisfies SubtitleGenerationModelId;
+
+export function isSubtitleGenerationModelId(value: unknown): value is SubtitleGenerationModelId {
+  return typeof value === 'string' && Object.hasOwn(MODEL_CATALOG, value);
+}
+
+export function getSubtitleGenerationModel(id: SubtitleGenerationModelId) {
+  return MODEL_CATALOG[id];
+}
+
+export function formatSubtitleGenerationModelSize(size: number): string {
+  if (size < 1024 ** 2) return `${Math.ceil(size / 1024)} KiB`;
+  return size >= 1024 ** 3
+    ? `${(size / 1024 ** 3).toFixed(1)} GiB`
+    : `${Math.round(size / 1024 ** 2)} MiB`;
+}
diff --git a/src/shared/subtitle-generation-vad-model.ts b/src/shared/subtitle-generation-vad-model.ts
new file mode 100644
index 00000000..2615ea8b
--- /dev/null
+++ b/src/shared/subtitle-generation-vad-model.ts
@@ -0,0 +1,6 @@
+export const SUBTITLE_GENERATION_VAD_MODEL = {
+  filename: 'ggml-silero-v6.2.0.bin',
+  size: 885098,
+  sha256: '2aa269b785eeb53a82983a20501ddf7c1d9c48e33ab63a41391ac6c9f7fb6987',
+  url: 'https://huggingface.co/ggml-org/whisper-vad/resolve/9ffd54a1e1ee413ddf265af9913beaf518d1639b/ggml-silero-v6.2.0.bin',
+} as const;
diff --git a/src/shared/subtitle-generation.ts b/src/shared/subtitle-generation.ts
new file mode 100644
index 00000000..7da146f2
--- /dev/null
+++ b/src/shared/subtitle-generation.ts
@@ -0,0 +1,114 @@
+import {
+  isSubtitleGenerationModelId,
+  RECOMMENDED_SUBTITLE_GENERATION_MODEL,
+  type SubtitleGenerationModelId,
+} from './subtitle-generation-model-catalog';
+
+export interface SubtitleGenerationConfig {
+  whisperPath: string;
+  modelPath: string;
+  managedModel: SubtitleGenerationModelId;
+  threads: number;
+  ffmpegPath: string;
+  ffprobePath: string;
+  vadModelPath: string;
+  vadPath: string;
+}
+
+export const DEFAULT_SUBTITLE_GENERATION_CONFIG: SubtitleGenerationConfig = {
+  whisperPath: '',
+  modelPath: '',
+  managedModel: RECOMMENDED_SUBTITLE_GENERATION_MODEL,
+  threads: 4,
+  ffmpegPath: '',
+  ffprobePath: '',
+  vadModelPath: '',
+  vadPath: '',
+};
+
+export interface SubtitleGenerationProgress {
+  stage: 'download' | 'extract' | 'transcribe' | 'write';
+  percent?: number;
+  message: string;
+}
+
+export type SubtitleGenerationModelStatus =
+  | { kind: 'external' | 'managed'; path: string }
+  | { kind: 'missing'; path: string }
+  | { kind: 'invalid'; path: string; message: string };
+
+export type SubtitleGenerationToolStatus =
+  | { kind: 'found'; path: string }
+  | { kind: 'missing'; message: string };
+
+export type SubtitleGenerationAcceleration =
+  | { kind: 'nvidia-cuda'; gpuName: string }
+  | { kind: 'unavailable' };
+
+export function recommendedSubtitleGenerationModel(acceleration: SubtitleGenerationAcceleration) {
+  return acceleration.kind === 'nvidia-cuda'
+    ? 'large-v3-turbo'
+    : RECOMMENDED_SUBTITLE_GENERATION_MODEL;
+}
+
+/** Executables generation depends on. `vad` is null unless dialogue mode is on. */
+export interface SubtitleGenerationTools {
+  ffmpeg: SubtitleGenerationToolStatus;
+  ffprobe: SubtitleGenerationToolStatus;
+  whisper: SubtitleGenerationToolStatus;
+  vad: SubtitleGenerationToolStatus | null;
+}
+
+export function missingSubtitleGenerationTools(tools: SubtitleGenerationTools): string[] {
+  return [tools.ffmpeg, tools.ffprobe, tools.whisper, tools.vad].flatMap((tool) =>
+    tool?.kind === 'missing' ? [tool.message] : [],
+  );
+}
+
+export function resolveSubtitleGenerationConfig(
+  value: unknown,
+  onWarning?: (key: string, value: unknown, message: string) => void,
+): SubtitleGenerationConfig {
+  const result = { ...DEFAULT_SUBTITLE_GENERATION_CONFIG };
+  if (value === undefined) return result;
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    onWarning?.('subtitleGeneration', value, 'Expected an object.');
+    return result;
+  }
+  for (const [key, rawValue] of Object.entries(value)) {
+    if (
+      key !== 'whisperPath' &&
+      key !== 'modelPath' &&
+      key !== 'ffmpegPath' &&
+      key !== 'ffprobePath' &&
+      key !== 'vadModelPath' &&
+      key !== 'vadPath'
+    )
+      continue;
+    const candidate: unknown = rawValue;
+    if (typeof candidate === 'string') {
+      result[key] = candidate.trim();
+    } else onWarning?.(key, candidate, 'Expected a string.');
+  }
+  if ('managedModel' in value) {
+    if (isSubtitleGenerationModelId(value.managedModel)) {
+      result.managedModel = value.managedModel;
+    } else
+      onWarning?.(
+        'managedModel',
+        value.managedModel,
+        'Expected a supported multilingual Whisper model.',
+      );
+  }
+  if ('threads' in value) {
+    if (
+      typeof value.threads === 'number' &&
+      Number.isInteger(value.threads) &&
+      value.threads >= 1 &&
+      value.threads <= 256
+    ) {
+      result.threads = value.threads;
+    } else onWarning?.('threads', value.threads, 'Expected an integer between 1 and 256.');
+  }
+  return result;
+}
diff --git a/src/shared/subtitle-selection.ts b/src/shared/subtitle-selection.ts
new file mode 100644
index 00000000..a32cf900
--- /dev/null
+++ b/src/shared/subtitle-selection.ts
@@ -0,0 +1,33 @@
+export interface SubtitleSelectionState {
+  mediaPath: string;
+  tracks: { id: number; label: string }[];
+  primary: number | null;
+  secondary: number | null;
+}
+
+export type SubtitleSelectionRequest = Pick<
+  SubtitleSelectionState,
+  'mediaPath' | 'primary' | 'secondary'
+>;
+
+export function parseSubtitleSelectionRequest(value: unknown): SubtitleSelectionRequest {
+  if (
+    typeof value !== 'object' ||
+    value === null ||
+    !('mediaPath' in value) ||
+    typeof value.mediaPath !== 'string' ||
+    !value.mediaPath ||
+    !('primary' in value) ||
+    !isTrackSelection(value.primary) ||
+    !('secondary' in value) ||
+    !isTrackSelection(value.secondary)
+  )
+    throw new Error('Invalid subtitle selection.');
+  if (value.primary !== null && value.primary === value.secondary)
+    throw new Error('Choose different primary and secondary tracks.');
+  return { mediaPath: value.mediaPath, primary: value.primary, secondary: value.secondary };
+}
+
+function isTrackSelection(value: unknown): value is number | null {
+  return value === null || (typeof value === 'number' && Number.isSafeInteger(value) && value > 0);
+}
diff --git a/src/stats-daemon-runner.ts b/src/stats-daemon-runner.ts
index 2e0f77e2..16e40729 100644
--- a/src/stats-daemon-runner.ts
+++ b/src/stats-daemon-runner.ts
@@ -7,6 +7,9 @@ import { createLogger, setLogLevel } from './logger';
 import { ImmersionTrackerService } from './core/services/immersion-tracker-service';
 import { createCoverArtFetcher } from './core/services/anilist/cover-art-fetcher';
 import { createAnilistRateLimiter } from './core/services/anilist/rate-limiter';
+import { createLiveActionMetadataResolver } from './core/services/tmdb/live-action-resolver';
+import { createTmdbClient, createTmdbApiKeyResolver } from './core/services/tmdb/tmdb-client';
+import { readBundledTmdbApiKey } from './core/services/tmdb/bundled-api-key';
 import { startStatsServer } from './core/services/stats-server';
 import {
   removeBackgroundStatsServerState,
@@ -124,10 +127,12 @@ const daemonUserDataPath = userDataPath;
 const statePath = path.join(userDataPath, 'stats-daemon.json');
 const knownWordCachePath = path.join(userDataPath, 'known-words-cache.json');
 const statsDistPath = path.join(__dirname, '..', 'stats', 'dist');
+const bundledTmdbApiKey = readBundledTmdbApiKey(__dirname);
 const wordHelperScriptPath = path.join(__dirname, 'stats-word-helper.js');
 
 let tracker: ImmersionTrackerService | null = null;
-let statsServer: ReturnType<typeof startStatsServer> | null = null;
+let statsServer: Awaited<ReturnType<typeof startStatsServer>> | null = null;
+let shutdownPromise: Promise<void> | null = null;
 
 function writeFailureResponse(message: string): void {
   if (!responsePath) return;
@@ -147,25 +152,32 @@ function clearOwnedState(): void {
   }
 }
 
-function shutdown(code = 0): void {
-  try {
-    statsServer?.close();
-  } catch {
-    // ignore
-  }
-  statsServer = null;
-  try {
-    tracker?.destroy();
-  } catch {
-    // ignore
-  }
-  tracker = null;
-  clearOwnedState();
-  process.exit(code);
+function shutdown(code = 0): Promise<void> {
+  shutdownPromise ??= (async () => {
+    try {
+      await statsServer?.close();
+    } catch {
+      // ignore
+    }
+    statsServer = null;
+    try {
+      await tracker?.destroy();
+    } catch {
+      // ignore
+    }
+    tracker = null;
+    clearOwnedState();
+    process.exit(code);
+  })();
+  return shutdownPromise;
 }
 
-process.on('SIGINT', () => shutdown(0));
-process.on('SIGTERM', () => shutdown(0));
+process.on('SIGINT', () => {
+  void shutdown(0);
+});
+process.on('SIGTERM', () => {
+  void shutdown(0);
+});
 
 async function main(): Promise<void> {
   try {
@@ -194,16 +206,25 @@ async function main(): Promise<void> {
         },
       },
     });
+    const tmdbClient = createTmdbClient({
+      resolveApiKey: createTmdbApiKeyResolver(
+        () => configService.reloadConfig().tmdb,
+        () => bundledTmdbApiKey,
+      ),
+    });
     tracker.setCoverArtFetcher(
-      createCoverArtFetcher(createAnilistRateLimiter(), createLogger('stats-daemon:cover-art')),
+      createCoverArtFetcher(createAnilistRateLimiter(), createLogger('stats-daemon:cover-art'), {
+        liveAction: createLiveActionMetadataResolver(tmdbClient, createLogger('stats-daemon:tmdb')),
+      }),
     );
 
-    statsServer = startStatsServer({
+    statsServer = await startStatsServer({
       port: config.stats.serverPort,
       staticDir: statsDistPath,
       tracker,
       knownWordCachePath,
       getAnkiConnectConfig: () => configService.reloadConfig().ankiConnect,
+      tmdbClient,
       getYomitanAnkiDeckName: async () =>
         await readStatsYomitanDeckName({
           helperScriptPath: wordHelperScriptPath,
@@ -237,7 +258,7 @@ async function main(): Promise<void> {
     const message = error instanceof Error ? error.message : String(error);
     logger.error('Failed to start stats daemon', message);
     writeFailureResponse(message);
-    shutdown(1);
+    await shutdown(1);
   }
 }
 
diff --git a/src/subtitle-timing-tracker.ts b/src/subtitle-timing-tracker.ts
index 04d8fe8d..f55c603e 100644
--- a/src/subtitle-timing-tracker.ts
+++ b/src/subtitle-timing-tracker.ts
@@ -67,8 +67,13 @@ export class SubtitleTimingTracker {
 
     // Check for duplicate of most recent entry (deduplicate adjacent repeats)
     const lastEntry = this.history[this.history.length - 1];
-    if (lastEntry && lastEntry.timingKey === timingKey) {
-      // Update timing to most recent occurrence
+    if (
+      lastEntry &&
+      lastEntry.timingKey === timingKey &&
+      lastEntry.startTime === startTime &&
+      lastEntry.endTime === endTime
+    ) {
+      // Refresh metadata for repeated notifications of the same subtitle event.
       lastEntry.startTime = startTime;
       lastEntry.endTime = endTime;
       lastEntry.secondaryText = displaySecondaryText;
@@ -107,28 +112,20 @@ export class SubtitleTimingTracker {
   }
 
   /**
-   * Get recent subtitle blocks in chronological order.
-   * Returns the last `count` subtitle events (oldest → newest).
+   * Get recent subtitle blocks in timeline order.
+   * Returns up to `count` known subtitle events ending at the current event.
    * Blocks preserve internal line breaks and are joined with blank lines.
    */
   getRecentBlocks(count: number): string[] {
-    if (count <= 0) return [];
-    if (count > this.history.length) {
-      count = this.history.length;
-    }
-    return this.history.slice(-count).map((entry) => entry.displayText);
+    return this.getRecentTimelineEntries(count).map((entry) => entry.displayText);
   }
 
   /**
-   * Get recent subtitle blocks with their original event timings.
-   * Returns the last `count` subtitle events (oldest → newest).
+   * Get recent subtitle blocks with their original event timings in timeline order.
+   * Returns up to `count` known subtitle events ending at the current event.
    */
   getRecentEntries(count: number): SubtitleTimingBlock[] {
-    if (count <= 0) return [];
-    if (count > this.history.length) {
-      count = this.history.length;
-    }
-    return this.history.slice(-count).map((entry) => ({
+    return this.getRecentTimelineEntries(count).map((entry) => ({
       displayText: entry.displayText,
       startTime: entry.startTime,
       endTime: entry.endTime,
@@ -144,6 +141,43 @@ export class SubtitleTimingTracker {
     return lastEntry ? lastEntry.displayText : null;
   }
 
+  private getRecentTimelineEntries(count: number): HistoryEntry[] {
+    if (count <= 0) return [];
+
+    const currentEntry = this.history[this.history.length - 1];
+    if (!currentEntry) return [];
+
+    const timelineEntries: HistoryEntry[] = [];
+    for (const entry of this.history) {
+      const existingIndex = timelineEntries.findIndex((candidate) =>
+        this.isSameSubtitleEvent(candidate, entry),
+      );
+      if (existingIndex === -1) {
+        timelineEntries.push(entry);
+      } else {
+        timelineEntries[existingIndex] = entry;
+      }
+    }
+
+    timelineEntries.sort(
+      (left, right) => left.startTime - right.startTime || left.endTime - right.endTime,
+    );
+    const currentIndex = timelineEntries.findIndex((entry) =>
+      this.isSameSubtitleEvent(entry, currentEntry),
+    );
+    if (currentIndex === -1) return [];
+
+    return timelineEntries.slice(Math.max(0, currentIndex - count + 1), currentIndex + 1);
+  }
+
+  private isSameSubtitleEvent(left: HistoryEntry, right: HistoryEntry): boolean {
+    return (
+      left.timingKey === right.timingKey &&
+      left.startTime === right.startTime &&
+      left.endTime === right.endTime
+    );
+  }
+
   private findFuzzyMatch(text: string): { startTime: number; endTime: number } | null {
     let bestMatch: TimingEntry | null = null;
     let bestScore = 0;
diff --git a/src/syncui/style.css b/src/syncui/style.css
index 43fea1c2..3aa84ca0 100644
--- a/src/syncui/style.css
+++ b/src/syncui/style.css
@@ -1,6 +1,6 @@
 @font-face {
   font-family: 'M PLUS 1';
-  src: url('./fonts/MPLUS1[wght].ttf') format('truetype');
+  src: url('../fonts/MPLUS1[wght].ttf') format('truetype');
   font-weight: 100 900;
   font-display: swap;
 }
diff --git a/src/types/anki.ts b/src/types/anki.ts
index 22adea92..1ddcc732 100644
--- a/src/types/anki.ts
+++ b/src/types/anki.ts
@@ -11,6 +11,99 @@ export type CardKind = 'sentence' | 'audio' | 'word-and-sentence' | 'click';
 /** Card kind SubMiner flags on word cards; 'none' leaves the flag fields untouched. */
 export type WordCardKind = CardKind | 'none';
 
+export type MediaTimingReviewKind = 'word' | 'sentence' | 'audio';
+
+export interface MediaTimingReviewRequest {
+  kind: MediaTimingReviewKind;
+  text: string;
+  startTime: number;
+  endTime: number;
+  noteId?: number;
+  audioPadding: number;
+  maxMediaDuration: number;
+  /** Still screenshots only; animated images continue to follow the audio range. */
+  screenshotEnabled?: boolean;
+}
+
+/** A subtitle line adjacent to the mined one that the review can pull onto the card. */
+export interface MediaTimingReviewContextLine {
+  text: string;
+  startTime: number;
+  endTime: number;
+}
+
+export type MediaTimingReviewDecision =
+  /** `text` is set when the review combined adjacent lines into the card sentence. */
+  | {
+      action: 'confirm';
+      startTime: number;
+      endTime: number;
+      text?: string;
+      screenshotTime?: number;
+    }
+  | { action: 'use-original' }
+  | { action: 'skip-media' }
+  | { action: 'discard' };
+
+export interface MediaTimingReviewOpenPayload {
+  reviewId: string;
+  kind: MediaTimingReviewKind;
+  text: string;
+  /** Lines before/after the mined one, both chronological: nearest previous line is last, nearest next line is first. */
+  previousLines: MediaTimingReviewContextLine[];
+  nextLines: MediaTimingReviewContextLine[];
+  noteId?: number;
+  originalStartTime: number;
+  originalEndTime: number;
+  selectionStartTime: number;
+  selectionEndTime: number;
+  timelineStartTime: number;
+  timelineEndTime: number;
+  mediaDuration?: number;
+  maxMediaDuration: number;
+  screenshotEnabled?: boolean;
+}
+
+export interface MediaTimingReviewFrameRequest {
+  reviewId: string;
+  timestamp: number;
+  /** Step to the adjacent decoded frame instead of seeking to a time. */
+  direction?: -1 | 1;
+}
+
+export interface MediaTimingReviewFrameResult extends MediaTimingReviewActionResult {
+  dataUrl?: string;
+  timestamp?: number;
+}
+
+export interface MediaTimingReviewPreviewRequest {
+  reviewId: string;
+  startTime: number;
+  endTime: number;
+}
+
+export interface MediaTimingReviewWaveformRequest {
+  reviewId: string;
+  startTime: number;
+  endTime: number;
+}
+
+export interface MediaTimingReviewWaveformResult extends MediaTimingReviewActionResult {
+  peaks?: number[];
+}
+
+export interface MediaTimingReviewResolveRequest {
+  reviewId: string;
+  decision: MediaTimingReviewDecision;
+}
+
+export interface MediaTimingReviewActionResult {
+  ok: boolean;
+  message?: string;
+  /** The review this request targeted has already ended; the renderer should close. */
+  stale?: boolean;
+}
+
 export interface NotificationOptions {
   body?: string;
   icon?: string;
@@ -64,6 +157,7 @@ export interface AnkiConnectConfig {
   fields?: {
     word?: string;
     audio?: string;
+    wordAudio?: string;
     image?: string;
     sentence?: string;
     miscInfo?: string;
@@ -85,6 +179,7 @@ export interface AnkiConnectConfig {
     syncAnimatedImageToWordAudio?: boolean;
     normalizeAudio?: boolean;
     mirrorMpvVolume?: boolean;
+    reviewTiming?: boolean;
     audioPadding?: number;
     fallbackDuration?: number;
     maxMediaDuration?: number;
@@ -124,6 +219,11 @@ export interface AnkiConnectConfig {
     fieldGrouping?: 'auto' | 'manual' | 'disabled';
     deleteDuplicateInAuto?: boolean;
   };
+  isSenren?: {
+    enabled?: boolean;
+    fieldGrouping?: 'auto' | 'manual' | 'disabled';
+    deleteDuplicateInAuto?: boolean;
+  };
   lapisKiku?: {
     wordCardKind?: WordCardKind;
   };
diff --git a/src/types/config.ts b/src/types/config.ts
index 406f63e6..bfc6c5e8 100644
--- a/src/types/config.ts
+++ b/src/types/config.ts
@@ -1,4 +1,5 @@
 import type { AnkiConnectConfig, WordCardKind } from './anki';
+import type { SubtitleGenerationConfig } from '../shared/subtitle-generation';
 import type {
   AiConfig,
   AiFeatureConfig,
@@ -11,6 +12,7 @@ import type {
   ImmersionTrackingRetentionMode,
   ImmersionTrackingRetentionPreset,
   TsukihimeConfig,
+  TmdbConfig,
   JellyfinConfig,
   JimakuConfig,
   JimakuLanguagePreference,
@@ -124,6 +126,8 @@ export interface ShortcutsConfig {
   openRuntimeOptions?: string | null;
   openJimaku?: string | null;
   openTsukihime?: string | null;
+  openSubtitleSelection?: string | null;
+  openSubtitleGeneration?: string | null;
   openSessionHelp?: string | null;
   openControllerSelect?: string | null;
   openControllerDebug?: string | null;
@@ -149,6 +153,8 @@ export interface Config {
   shortcuts?: RawShortcutsConfig;
   secondarySub?: SecondarySubConfig;
   subsync?: SubsyncConfig;
+  subtitleSelection?: { enabled?: boolean };
+  subtitleGeneration?: Partial<SubtitleGenerationConfig>;
   startupWarmups?: StartupWarmupsConfig;
   subtitleStyle?: SubtitleStyleConfig;
   subtitleSidebar?: SubtitleSidebarConfig;
@@ -157,6 +163,7 @@ export interface Config {
   /** @deprecated Use tsukihime. */
   animetosho?: TsukihimeConfig;
   tsukihime?: TsukihimeConfig;
+  tmdb?: TmdbConfig;
   anilist?: AnilistConfig;
   yomitan?: YomitanConfig;
   jellyfin?: JellyfinConfig;
@@ -225,6 +232,7 @@ export interface ResolvedConfig {
     fields: {
       word: string;
       audio: string;
+      wordAudio: string;
       image: string;
       sentence: string;
       miscInfo: string;
@@ -248,6 +256,7 @@ export interface ResolvedConfig {
       syncAnimatedImageToWordAudio: boolean;
       normalizeAudio: boolean;
       mirrorMpvVolume: boolean;
+      reviewTiming: boolean;
       audioPadding: number;
       fallbackDuration: number;
       maxMediaDuration: number;
@@ -285,6 +294,11 @@ export interface ResolvedConfig {
       fieldGrouping: 'auto' | 'manual' | 'disabled';
       deleteDuplicateInAuto: boolean;
     };
+    isSenren: {
+      enabled: boolean;
+      fieldGrouping: 'auto' | 'manual' | 'disabled';
+      deleteDuplicateInAuto: boolean;
+    };
     lapisKiku: {
       wordCardKind: WordCardKind;
     };
@@ -292,6 +306,8 @@ export interface ResolvedConfig {
   shortcuts: Required<ShortcutsConfig>;
   secondarySub: Required<SecondarySubConfig>;
   subsync: Required<SubsyncConfig>;
+  subtitleSelection: { enabled: boolean };
+  subtitleGeneration: SubtitleGenerationConfig;
   startupWarmups: {
     lowPowerMode: boolean;
     mecab: boolean;
@@ -322,6 +338,10 @@ export interface ResolvedConfig {
     apiBaseUrl: string;
     maxSearchResults: number;
   };
+  tmdb: {
+    apiKey: string;
+    apiKeyCommand: string;
+  };
   anilist: {
     enabled: boolean;
     accessToken: string;
diff --git a/src/types/integrations.ts b/src/types/integrations.ts
index a67c8833..d7ef5ddc 100644
--- a/src/types/integrations.ts
+++ b/src/types/integrations.ts
@@ -190,8 +190,12 @@ export interface JimakuMediaInfo {
   rawTitle: string;
 }
 
+export type JimakuSearchCategory = 'anime' | 'liveAction';
+
 export interface JimakuSearchQuery {
   query: string;
+  // Which Jimaku catalogue to search; defaults to anime when omitted.
+  category?: JimakuSearchCategory;
 }
 
 export interface JimakuEntryFlags {
@@ -283,3 +287,9 @@ export interface TsukihimeConfig {
   apiBaseUrl?: string;
   maxSearchResults?: number;
 }
+
+/** TMDB (The Movie Database) access for live-action drama and movie metadata. */
+export interface TmdbConfig {
+  apiKey?: string;
+  apiKeyCommand?: string;
+}
diff --git a/src/types/runtime-options.ts b/src/types/runtime-options.ts
index 9c2b423a..f1d59d89 100644
--- a/src/types/runtime-options.ts
+++ b/src/types/runtime-options.ts
@@ -1,11 +1,13 @@
 export type RuntimeOptionId =
   | 'anki.autoUpdateNewCards'
+  | 'anki.mediaReviewTiming'
   | 'subtitle.annotation.knownWords.highlightEnabled'
   | 'subtitle.annotation.knownWords.maturityEnabled'
   | 'subtitle.annotation.nPlusOne'
   | 'subtitle.annotation.jlpt'
   | 'subtitle.annotation.frequency'
   | 'anki.kikuFieldGrouping'
+  | 'anki.senrenFieldGrouping'
   | 'anki.nPlusOneMatchMode';
 
 export type RuntimeOptionScope = 'ankiConnect' | 'subtitle';
diff --git a/src/types/runtime.ts b/src/types/runtime.ts
index 9fcc76c8..8ff84287 100644
--- a/src/types/runtime.ts
+++ b/src/types/runtime.ts
@@ -1,10 +1,25 @@
+import type { MpvInputBindingsSnapshot } from './session-bindings';
 import type {
   KikuFieldGroupingChoice,
   KikuFieldGroupingRequestData,
   KikuMergePreviewRequest,
   KikuMergePreviewResponse,
+  MediaTimingReviewActionResult,
+  MediaTimingReviewOpenPayload,
+  MediaTimingReviewPreviewRequest,
+  MediaTimingReviewResolveRequest,
+  MediaTimingReviewFrameRequest,
+  MediaTimingReviewFrameResult,
+  MediaTimingReviewWaveformRequest,
+  MediaTimingReviewWaveformResult,
 } from './anki';
 import type { ChangelogSnapshot } from './changelog';
+import type { SubtitleGenerationProgress } from '../shared/subtitle-generation';
+import type { SubtitleGenerationModelId } from '../shared/subtitle-generation-model-catalog';
+import type {
+  SubtitleGenerationResult,
+  SubtitleGenerationStatus,
+} from '../shared/subtitle-generation-ipc';
 import type { ResolvedConfig, ShortcutsConfig } from './config';
 import type {
   CompiledSessionBinding,
@@ -424,6 +439,20 @@ export interface SessionNumericSelectionStartPayload {
 }
 
 export interface ElectronAPI {
+  requestSubtitleGenerationOpen: () => Promise<boolean>;
+  onSubtitleGenerationOpen: (callback: () => void) => void;
+  getSubtitleGenerationStatus: () => Promise<SubtitleGenerationStatus>;
+  selectSubtitleGenerationModel: (
+    model: SubtitleGenerationModelId,
+  ) => Promise<SubtitleGenerationStatus>;
+  startSubtitleGeneration: () => Promise<SubtitleGenerationResult>;
+  downloadSubtitleGenerationModel: () => Promise<SubtitleGenerationResult>;
+  downloadSubtitleGenerationVadModel: () => Promise<SubtitleGenerationResult>;
+  setSubtitleGenerationVadEnabled: (enabled: boolean) => Promise<SubtitleGenerationStatus>;
+  cancelSubtitleGeneration: () => Promise<void>;
+  onSubtitleGenerationProgress: (
+    callback: (progress: SubtitleGenerationProgress) => void,
+  ) => () => void;
   getOverlayLayer: () => 'visible' | 'modal' | null;
   getPathForFile: (file: File) => string;
   onSubtitle: (callback: (data: SubtitleData) => void) => void;
@@ -442,6 +471,7 @@ export interface ElectronAPI {
   getCurrentSubtitleRaw: () => Promise<string>;
   getCurrentSubtitleAss: () => Promise<string>;
   getSubtitleSidebarSnapshot: () => Promise<SubtitleSidebarSnapshot>;
+  copySubtitleSidebarSelection: (text: string) => Promise<void>;
   getSubtitleSidebarOpen: () => Promise<boolean>;
   getPlaybackPaused: () => Promise<boolean | null>;
   onSubtitleAss: (callback: (assText: string) => void) => void;
@@ -455,6 +485,7 @@ export interface ElectronAPI {
   setMecabEnabled: (enabled: boolean) => void;
   sendMpvCommand: (command: (string | number)[]) => void;
   getKeybindings: () => Promise<Keybinding[]>;
+  getMpvInputBindings: () => Promise<MpvInputBindingsSnapshot>;
   getSessionBindings: () => Promise<CompiledSessionBinding[]>;
   getConfiguredShortcuts: () => Promise<Required<ShortcutsConfig>>;
   dispatchSessionAction: (
@@ -494,6 +525,13 @@ export interface ElectronAPI {
   focusMainWindow: () => Promise<void>;
   activatePlaybackWindowForOverlayInteraction: () => Promise<boolean>;
   getSubtitleStyle: () => Promise<SubtitleRendererStyleConfig | null>;
+  onSubtitleSelectionOpen: (callback: () => void) => void;
+  getSubtitleSelection: () => Promise<
+    import('../shared/subtitle-selection').SubtitleSelectionState
+  >;
+  applySubtitleSelection: (
+    request: import('../shared/subtitle-selection').SubtitleSelectionRequest,
+  ) => Promise<void>;
   onSubsyncManualOpen: (callback: (payload: SubsyncManualPayload) => void) => void;
   runSubsyncManual: (request: SubsyncManualRunRequest) => Promise<SubsyncResult>;
   onKikuFieldGroupingRequest: (callback: (data: KikuFieldGroupingRequestData) => void) => void;
@@ -516,6 +554,21 @@ export interface ElectronAPI {
   onOpenJimaku: (callback: () => void) => void;
   onOpenTsukihime: (callback: () => void) => void;
   onOpenYoutubeTrackPicker: (callback: (payload: YoutubePickerOpenPayload) => void) => void;
+  onOpenMediaTimingReview: (callback: (payload: MediaTimingReviewOpenPayload) => void) => void;
+  onMediaTimingReviewPreviewEnded: (callback: (reviewId: string) => void) => void;
+  previewMediaTimingReview: (
+    request: MediaTimingReviewPreviewRequest,
+  ) => Promise<MediaTimingReviewActionResult>;
+  getMediaTimingReviewFrame: (
+    request: MediaTimingReviewFrameRequest,
+  ) => Promise<MediaTimingReviewFrameResult>;
+  getMediaTimingReviewWaveform: (
+    request: MediaTimingReviewWaveformRequest,
+  ) => Promise<MediaTimingReviewWaveformResult>;
+  stopMediaTimingReviewPreview: (reviewId: string) => Promise<MediaTimingReviewActionResult>;
+  resolveMediaTimingReview: (
+    request: MediaTimingReviewResolveRequest,
+  ) => Promise<MediaTimingReviewActionResult>;
   onOpenPlaylistBrowser: (callback: () => void) => void;
   onOpenCharacterDictionaryManager: (callback: () => void) => void;
   onSubtitleSidebarToggle: (callback: () => void) => void;
@@ -558,9 +611,12 @@ export interface ElectronAPI {
     modal:
       | 'runtime-options'
       | 'subsync'
+      | 'subtitle-selection'
+      | 'subtitle-generation'
       | 'jimaku'
       | 'tsukihime'
       | 'youtube-track-picker'
+      | 'media-timing-review'
       | 'playlist-browser'
       | 'kiku'
       | 'controller-select'
@@ -574,9 +630,12 @@ export interface ElectronAPI {
     modal:
       | 'runtime-options'
       | 'subsync'
+      | 'subtitle-selection'
+      | 'subtitle-generation'
       | 'jimaku'
       | 'tsukihime'
       | 'youtube-track-picker'
+      | 'media-timing-review'
       | 'playlist-browser'
       | 'kiku'
       | 'controller-select'
@@ -587,6 +646,7 @@ export interface ElectronAPI {
       | 'changelog',
   ) => void;
   reportOverlayContentBounds: (measurement: OverlayContentMeasurement) => void;
+  onSessionBindingsChanged: (callback: (bindings: CompiledSessionBinding[]) => void) => void;
   onConfigHotReload: (callback: (payload: ConfigHotReloadPayload) => void) => void;
 }
 
diff --git a/src/types/session-bindings.ts b/src/types/session-bindings.ts
index 3e0deeb1..9873e21f 100644
--- a/src/types/session-bindings.ts
+++ b/src/types/session-bindings.ts
@@ -23,6 +23,8 @@ export type SessionActionId =
   | 'openControllerDebug'
   | 'openJimaku'
   | 'openTsukihime'
+  | 'openSubtitleSelection'
+  | 'openSubtitleGeneration'
   | 'openYoutubePicker'
   | 'openPlaylistBrowser'
   | 'replayCurrentSubtitle'
@@ -34,6 +36,11 @@ export interface SessionKeySpec {
   modifiers: SessionKeyModifier[];
 }
 
+export interface MpvInputBindingsSnapshot {
+  keys: string[];
+  blockedKeys: SessionKeySpec[];
+}
+
 export interface SessionBindingWarning {
   kind: 'unsupported' | 'conflict' | 'deprecated-config';
   path: string;
diff --git a/src/types/stats-http-contract.ts b/src/types/stats-http-contract.ts
index a920761a..53dd8cbe 100644
--- a/src/types/stats-http-contract.ts
+++ b/src/types/stats-http-contract.ts
@@ -27,6 +27,7 @@ import type {
   WatchTimePerAnime,
   WordDetailData,
 } from './stats-wire';
+import type { TmdbMediaType } from '../shared/media-kind';
 
 export type StatsTrendRange = '7d' | '30d' | '90d' | '365d' | 'all';
 export type StatsTrendGroupBy = 'day' | 'month';
@@ -78,6 +79,25 @@ export interface StatsAnilistSearchResult {
   title: { romaji: string | null; english: string | null; native: string | null } | null;
 }
 
+export interface StatsTmdbSearchResult {
+  tmdbId: number;
+  tmdbType: TmdbMediaType;
+  /** English title when TMDB has one, otherwise the original title. */
+  title: string;
+  originalTitle: string;
+  originalLanguage: string;
+  overview: string | null;
+  posterUrl: string | null;
+  year: number | null;
+  /** True when TMDB tags the title with the Animation genre. */
+  isAnimation: boolean;
+}
+
+export interface StatsTmdbAssignment {
+  tmdbId: number;
+  tmdbType: TmdbMediaType;
+}
+
 export interface StatsAnilistAssignment {
   anilistId: number;
   titleRomaji?: string | null;
@@ -209,11 +229,13 @@ export interface StatsJsonResponseMap {
   moveVideoToAnime: StatsMoveVideoResponse;
   dismissAnimeMergeRecommendation: StatsOkResponse;
   anilistSearch: StatsAnilistSearchResult[];
+  tmdbSearch: StatsTmdbSearchResult[];
   knownWords: string[];
   knownWordsSummary: StatsKnownWordsSummary;
   animeKnownWordsSummary: StatsKnownWordsSummary;
   mediaKnownWordsSummary: StatsKnownWordsSummary;
   reassignAnimeAnilist: StatsOkResponse;
+  reassignAnimeTmdb: StatsOkResponse;
   coverImages: StatsCoverImagesData;
   episodeDetail: EpisodeDetailData;
   ankiBrowse: StatsAnkiBrowseResponse;
@@ -302,6 +324,8 @@ export interface StatsHttpClient {
   getMediaKnownWordsSummary: (videoId: number) => Promise<StatsKnownWordsSummary>;
   searchAnilist: (query: string) => Promise<StatsAnilistSearchResult[]>;
   reassignAnimeAnilist: (animeId: number, info: StatsAnilistAssignment) => Promise<void>;
+  searchTmdb: (query: string) => Promise<StatsTmdbSearchResult[]>;
+  reassignAnimeTmdb: (animeId: number, info: StatsTmdbAssignment) => Promise<void>;
   mineCard: (params: StatsMineCardParams) => Promise<StatsMineCardResponse>;
   ankiBrowse: (noteId: number) => Promise<void>;
   ankiNotesInfo: (noteIds: number[]) => Promise<StatsAnkiNoteInfo[]>;
diff --git a/src/types/stats-wire.ts b/src/types/stats-wire.ts
index 40ff0865..4875085f 100644
--- a/src/types/stats-wire.ts
+++ b/src/types/stats-wire.ts
@@ -1,3 +1,5 @@
+import type { MediaKind, TmdbMediaType } from '../shared/media-kind';
+
 export interface SessionSummary {
   sessionId: number;
   canonicalTitle: string | null;
@@ -240,9 +242,12 @@ export const EventType = {
 export type EventType = (typeof EventType)[keyof typeof EventType];
 
 export interface AnimeLibraryItem {
+  mediaKind: MediaKind;
   animeId: number;
   canonicalTitle: string;
   anilistId: number | null;
+  tmdbId: number | null;
+  tmdbType: TmdbMediaType | null;
   totalSessions: number;
   totalActiveMs: number;
   totalCards: number;
@@ -261,9 +266,12 @@ export interface AnilistEntry {
 
 export interface AnimeDetailData {
   detail: {
+    mediaKind: MediaKind;
     animeId: number;
     canonicalTitle: string;
     anilistId: number | null;
+    tmdbId: number | null;
+    tmdbType: TmdbMediaType | null;
     titleRomaji: string | null;
     titleEnglish: string | null;
     titleNative: string | null;
diff --git a/src/types/subtitle.ts b/src/types/subtitle.ts
index 409d0e2e..64b0226d 100644
--- a/src/types/subtitle.ts
+++ b/src/types/subtitle.ts
@@ -1,4 +1,4 @@
-import type { SubtitleCue } from '../core/services/subtitle-cue-parser';
+import type { AssVerticalBand, SubtitleCue } from '../core/services/subtitle-cue-parser';
 
 export enum PartOfSpeech {
   noun = 'noun',
@@ -187,7 +187,7 @@ export interface ResolvedTokenPos2ExclusionConfig {
 
 export type FrequencyDictionaryMode = 'single' | 'banded';
 
-export type { SubtitleCue };
+export type { AssVerticalBand, SubtitleCue };
 
 export type SubtitleSidebarLayout = 'overlay' | 'embedded';
 
@@ -227,6 +227,7 @@ export interface SubtitleData {
 }
 
 export interface SubtitleSidebarSnapshot {
+  sourceKey: string | null;
   cues: SubtitleCue[];
   currentTimeSec?: number | null;
   currentSubtitle: {
@@ -243,6 +244,10 @@ export interface SubtitleMiningContext {
   startTime: number;
   endTime: number;
   capturedAtMs?: number;
+  /** Explicit generator padding. Confirmed timing-review ranges set this to zero. */
+  mediaPaddingSeconds?: number;
+  /** Independent still screenshot selected during media timing review. */
+  screenshotTime?: number;
 }
 
 export interface SubtitleHoverTokenPayload {
diff --git a/src/workflow-test-helpers.test.ts b/src/workflow-test-helpers.test.ts
new file mode 100644
index 00000000..c4190b8d
--- /dev/null
+++ b/src/workflow-test-helpers.test.ts
@@ -0,0 +1,97 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  commandPositions,
+  executableRunLines,
+  stepRunsCommand,
+  stepsMissingEnvDeclaration,
+  templateExpressionsInRunBodies,
+} from './workflow-test-helpers';
+
+const runs = (run: string): boolean => stepRunsCommand({ run }, /^bun run verify --flag "\$VALUE"/);
+
+test('stepRunsCommand matches a command that actually executes', () => {
+  assert.equal(runs('bun run verify --flag "$VALUE"'), true);
+  assert.equal(runs('if ! bun run verify --flag "$VALUE"; then\nexit 1\nfi'), true);
+  assert.equal(runs('set -e && bun run verify --flag "$VALUE"'), true);
+  assert.equal(runs('  bun run verify --flag "$VALUE" || exit 1'), true);
+});
+
+test('stepRunsCommand rejects commands that are only mentioned, not run', () => {
+  assert.equal(runs('# bun run verify --flag "$VALUE"'), false);
+  assert.equal(runs('echo \'bun run verify --flag "$VALUE"\''), false);
+  assert.equal(runs("printf '%s\\n' 'bun run verify --flag \"$VALUE\"'"), false);
+  assert.equal(runs('echo "run: bun run verify --flag \\"$VALUE\\"" >> notes.txt'), false);
+  // A different argument list is a different command.
+  assert.equal(runs('bun run verify'), false);
+});
+
+test('stepRunsCommand ignores separators inside quotes and inline comments', () => {
+  assert.equal(runs('echo \'note; bun run verify --flag "$VALUE"\''), false);
+  assert.equal(runs('echo "note && bun run verify --flag \\"$VALUE\\""'), false);
+  assert.equal(runs("printf '%s\\n' 'a | bun run verify --flag \"$VALUE\"'"), false);
+  assert.equal(runs('if false; then # bun run verify --flag "$VALUE"'), false);
+  // A trailing comment does not hide the command in front of it.
+  assert.equal(runs('bun run verify --flag "$VALUE" # keep this'), true);
+  // A pipe is a real separator; a redirect is not.
+  assert.equal(runs('cat notes | bun run verify --flag "$VALUE"'), true);
+  assert.equal(stepRunsCommand({ run: 'gh release view "$V" 2>&1 | tee log' }, /^tee\b/), true);
+});
+
+test('stepRunsCommand treats backslash-escaped separators as literal text', () => {
+  assert.equal(runs(String.raw`echo foo \; bun run verify --flag "$VALUE"`), false);
+  assert.equal(runs(String.raw`echo foo \| bun run verify --flag "$VALUE"`), false);
+  assert.equal(runs(String.raw`find . -exec bun run verify --flag "$VALUE" \;`), false);
+  // An escape does not swallow a following real separator.
+  assert.equal(runs(String.raw`echo a\b; bun run verify --flag "$VALUE"`), true);
+});
+
+test('commandPositions splits on separators and strips control-flow prefixes', () => {
+  assert.deepEqual(
+    commandPositions({ run: 'if gh release view "$V"; then\ngh release edit "$V"\nfi' }),
+    ['gh release view "$V"', 'then', 'gh release edit "$V"', 'fi'],
+  );
+});
+
+test('executableRunLines drops blank and comment-only lines', () => {
+  assert.deepEqual(executableRunLines({ run: '\n# a comment\n  \nreal command\n' }), [
+    'real command',
+  ]);
+});
+
+test('templateExpressionsInRunBodies reports every expression spelling in a run body', () => {
+  const workflow = {
+    jobs: {
+      release: {
+        steps: [
+          { name: 'Safe', env: { V: '${{ steps.version.outputs.VERSION }}' }, run: 'echo "$V"' },
+          { name: 'Dotted', run: 'echo "${{ steps.version.outputs.VERSION }}"' },
+          { name: 'Bracketed', run: 'echo "${{ steps.version.outputs[\'VERSION\'] }}"' },
+          { name: 'Github', run: 'echo "${{ github[\'ref_name\'] }}"' },
+        ],
+      },
+    },
+  };
+
+  assert.deepEqual(templateExpressionsInRunBodies(workflow), [
+    'release/Dotted: ${{ steps.version.outputs.VERSION }}',
+    "release/Bracketed: ${{ steps.version.outputs['VERSION'] }}",
+    "release/Github: ${{ github['ref_name'] }}",
+  ]);
+});
+
+test('stepsMissingEnvDeclaration finds shell reads with no matching env entry', () => {
+  const workflow = {
+    jobs: {
+      release: {
+        steps: [
+          { name: 'Declared', env: { TAG: 'x' }, run: 'echo "$TAG"' },
+          { name: 'Undeclared', run: 'echo "${TAG}"' },
+          { name: 'Unrelated', run: 'echo "$TAGGED"' },
+        ],
+      },
+    },
+  };
+
+  assert.deepEqual(stepsMissingEnvDeclaration(workflow, 'TAG'), ['release/Undeclared']);
+});
diff --git a/src/workflow-test-helpers.ts b/src/workflow-test-helpers.ts
new file mode 100644
index 00000000..5aeeb59d
--- /dev/null
+++ b/src/workflow-test-helpers.ts
@@ -0,0 +1,182 @@
+import { readFileSync } from 'node:fs';
+
+export type WorkflowStep = {
+  name?: string;
+  run?: string;
+  env?: Record<string, unknown>;
+  uses?: string;
+  with?: Record<string, unknown>;
+};
+
+export type ParsedWorkflow = {
+  on?: { workflow_call?: { secrets?: Record<string, { required?: boolean }> } };
+  jobs?: Record<
+    string,
+    | {
+        steps?: WorkflowStep[];
+        uses?: string;
+        needs?: string | string[];
+        permissions?: Record<string, string>;
+        secrets?: string | Record<string, string>;
+      }
+    | undefined
+  >;
+};
+
+// Workflow tests only ever run under `bun test`, which parses YAML natively.
+function parseWorkflowYaml(source: string): ParsedWorkflow {
+  const bunRuntime = globalThis as typeof globalThis & {
+    Bun?: { YAML?: { parse?: (input: string) => unknown } };
+  };
+  const parse = bunRuntime.Bun?.YAML?.parse;
+  if (!parse) {
+    throw new Error('Bun.YAML.parse is unavailable; workflow tests must run under bun.');
+  }
+  return parse(source) as ParsedWorkflow;
+}
+
+export function readWorkflow(workflowPath: string): ParsedWorkflow {
+  return parseWorkflowYaml(readFileSync(workflowPath, 'utf8'));
+}
+
+// Steps of one job, in declaration order. Throws on an unknown job so a renamed
+// job fails loudly instead of silently emptying an ordering assertion.
+export function jobSteps(workflow: ParsedWorkflow, jobName: string): WorkflowStep[] {
+  const job = workflow.jobs?.[jobName];
+  if (!job) {
+    throw new Error(`Workflow has no job named ${jobName}.`);
+  }
+  return job.steps ?? [];
+}
+
+function allSteps(workflow: ParsedWorkflow): Array<{ job: string; step: WorkflowStep }> {
+  return Object.entries(workflow.jobs ?? {}).flatMap(([job, definition]) =>
+    (definition?.steps ?? []).map((step) => ({ job, step })),
+  );
+}
+
+// Lines of a step's shell body that actually execute. Comments are dropped so a
+// commented-out command cannot satisfy a "this step runs X" assertion.
+export function executableRunLines(step: WorkflowStep): string[] {
+  return (typeof step.run === 'string' ? step.run.split('\n') : [])
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0 && !line.startsWith('#'));
+}
+
+// Leading shell keywords and operators that can precede a real command.
+const COMMAND_PREFIX = /^(?:if|elif|while|until|then|else|do|!|&&|\|\||\(|\{)\s+/;
+
+// Splits one shell line on command separators, tracking quotes so a separator
+// inside a string is not treated as a command break, and stopping at an
+// unquoted inline comment.
+function splitCommandSeparators(line: string): string[] {
+  const segments: string[] = [];
+  let current = '';
+  let quote: "'" | '"' | null = null;
+
+  for (let index = 0; index < line.length; index += 1) {
+    const char = line[index]!;
+
+    if (quote) {
+      current += char;
+      if (char === '\\' && quote === '"' && index + 1 < line.length) {
+        current += line[index + 1]!;
+        index += 1;
+      } else if (char === quote) {
+        quote = null;
+      }
+      continue;
+    }
+
+    // An unquoted backslash escapes the next character, so `\;` is literal text
+    // rather than a separator. Checked before comments and separators.
+    if (char === '\\' && index + 1 < line.length) {
+      current += char + line[index + 1]!;
+      index += 1;
+      continue;
+    }
+
+    if (char === "'" || char === '"') {
+      quote = char;
+      current += char;
+      continue;
+    }
+
+    // An unquoted # starts a comment when it opens a word; the rest is inert.
+    if (char === '#' && (current === '' || /\s$/.test(current))) {
+      break;
+    }
+
+    const next = line[index + 1];
+    if (char === ';') {
+      segments.push(current);
+      current = '';
+      continue;
+    }
+    if ((char === '&' || char === '|') && next === char) {
+      segments.push(current);
+      current = '';
+      index += 1;
+      continue;
+    }
+    // A lone pipe separates commands; a redirect such as 2>&1 does not.
+    if (char === '|' && !/[0-9<>&]$/.test(current)) {
+      segments.push(current);
+      current = '';
+      continue;
+    }
+
+    current += char;
+  }
+
+  segments.push(current);
+  return segments;
+}
+
+// Command positions within a step's shell body: each line split on separators,
+// with control-flow prefixes stripped. A pattern anchored with ^ therefore
+// matches only where a command actually starts, so text quoted inside an
+// `echo`/`printf` argument is not mistaken for the command running.
+export function commandPositions(step: WorkflowStep): string[] {
+  return executableRunLines(step).flatMap((line) =>
+    splitCommandSeparators(line)
+      .map((segment) => {
+        let candidate = segment.trim();
+        let stripped = candidate.replace(COMMAND_PREFIX, '');
+        while (stripped !== candidate) {
+          candidate = stripped;
+          stripped = candidate.replace(COMMAND_PREFIX, '');
+        }
+        return candidate;
+      })
+      .filter(Boolean),
+  );
+}
+
+// Whether a step actually executes a command matching the pattern. Anchor the
+// pattern with ^ so it has to match at a command position.
+export function stepRunsCommand(step: WorkflowStep, pattern: RegExp): boolean {
+  return commandPositions(step).some((position) => pattern.test(position));
+}
+
+// GitHub substitutes ${{ }} into a run script before the shell parses it, so any
+// value used that way is executed as script rather than read as data. Reporting
+// every expression (rather than allow-listing known-safe ones) also covers
+// alternate spellings such as ${{ steps.version.outputs['VERSION'] }}.
+export function templateExpressionsInRunBodies(workflow: ParsedWorkflow): string[] {
+  return allSteps(workflow).flatMap(({ job, step }) =>
+    (typeof step.run === 'string' ? (step.run.match(/\$\{\{[\s\S]*?\}\}/g) ?? []) : []).map(
+      (expression) => `${job}/${step.name ?? '<unnamed>'}: ${expression}`,
+    ),
+  );
+}
+
+// Steps whose shell body reads $NAME without the step declaring it in env, which
+// would silently expand to an empty string at run time.
+export function stepsMissingEnvDeclaration(workflow: ParsedWorkflow, name: string): string[] {
+  const reference = new RegExp(`\\$${name}\\b|\\$\\{${name}\\b`);
+  return allSteps(workflow)
+    .filter(({ step }) => typeof step.run === 'string' && reference.test(step.run))
+    .filter(({ step }) => !Object.prototype.hasOwnProperty.call(step.env ?? {}, name))
+    .map(({ job, step }) => `${job}/${step.name ?? '<unnamed>'}`);
+}
diff --git a/stats/src/App.tsx b/stats/src/App.tsx
index f2348d4c..018a8893 100644
--- a/stats/src/App.tsx
+++ b/stats/src/App.tsx
@@ -4,7 +4,6 @@ import { DeleteProgressToast } from './components/common/DeleteProgressToast';
 import { TabBar } from './components/layout/TabBar';
 import { OverviewTab } from './components/overview/OverviewTab';
 import { useExcludedWords } from './hooks/useExcludedWords';
-import { assetUrl } from './lib/asset-url';
 import type { TabId } from './components/layout/TabBar';
 import {
   closeMediaDetail,
@@ -142,7 +141,7 @@ export function App() {
           onClick={() => handleTabChange('overview')}
           className="flex items-center gap-2 mb-2 hover:opacity-80 transition-opacity"
         >
-          <img src={assetUrl('favicon.png')} alt="" className="h-6 object-contain" />
+          <img src={'/favicon.png'} alt="" className="h-6 object-contain" />
           <h1 className="text-lg font-semibold text-ctp-text">SubMiner Stats</h1>
         </button>
         <TabBar activeTab={activeTab} onTabChange={handleTabChange} />
diff --git a/stats/src/components/anime/AnimeCard.test.tsx b/stats/src/components/anime/AnimeCard.test.tsx
index bcbd3c00..36a1c9c1 100644
--- a/stats/src/components/anime/AnimeCard.test.tsx
+++ b/stats/src/components/anime/AnimeCard.test.tsx
@@ -7,9 +7,12 @@ test('AnimeCard includes linked AniList id in cover URLs to avoid stale library
   const markup = renderToStaticMarkup(
     <AnimeCard
       anime={{
+        mediaKind: 'anime',
         animeId: 42,
         canonicalTitle: 'Test Anime',
         anilistId: 21699,
+        tmdbId: null,
+        tmdbType: null,
         totalSessions: 1,
         totalActiveMs: 600_000,
         totalCards: 0,
diff --git a/stats/src/components/anime/AnimeCard.tsx b/stats/src/components/anime/AnimeCard.tsx
index c22658e7..6243da55 100644
--- a/stats/src/components/anime/AnimeCard.tsx
+++ b/stats/src/components/anime/AnimeCard.tsx
@@ -29,7 +29,7 @@ export function AnimeCard({
         <AnimeCoverImage
           animeId={anime.animeId}
           title={anime.canonicalTitle}
-          coverRetryToken={anime.anilistId ?? 0}
+          coverRetryToken={anime.anilistId ?? anime.tmdbId ?? 0}
           className="w-full aspect-[3/4] rounded-t-lg transition-transform duration-200 group-hover:scale-105"
         />
         {selectable && (
@@ -48,7 +48,8 @@ export function AnimeCard({
       <div className="p-3">
         <div className="text-sm font-medium text-ctp-text truncate">{anime.canonicalTitle}</div>
         <div className="text-xs text-ctp-overlay2 mt-1">
-          {anime.episodeCount} episode{anime.episodeCount !== 1 ? 's' : ''}
+          {anime.episodeCount} {anime.mediaKind === 'youtube' ? 'video' : 'episode'}
+          {anime.episodeCount !== 1 ? 's' : ''}
         </div>
         <div className="text-xs text-ctp-overlay2">
           {formatDuration(anime.totalActiveMs)} · {formatNumber(anime.totalCards)} cards
diff --git a/stats/src/components/anime/AnimeCoverImage.test.tsx b/stats/src/components/anime/AnimeCoverImage.test.tsx
index dfaf927f..db520547 100644
--- a/stats/src/components/anime/AnimeCoverImage.test.tsx
+++ b/stats/src/components/anime/AnimeCoverImage.test.tsx
@@ -16,9 +16,12 @@ test('AnimeHeader uses the linked AniList id to avoid stale cached cover art', (
   const markup = renderToStaticMarkup(
     <AnimeHeader
       detail={{
+        mediaKind: 'anime',
         animeId: 42,
         canonicalTitle: 'Test Anime',
         anilistId: 21699,
+        tmdbId: null,
+        tmdbType: null,
         titleRomaji: null,
         titleEnglish: null,
         titleNative: null,
diff --git a/stats/src/components/anime/AnimeDetailView.tsx b/stats/src/components/anime/AnimeDetailView.tsx
index df1405ce..88e7db95 100644
--- a/stats/src/components/anime/AnimeDetailView.tsx
+++ b/stats/src/components/anime/AnimeDetailView.tsx
@@ -7,6 +7,7 @@ import { AnimeHeader } from './AnimeHeader';
 import { EpisodeList } from './EpisodeList';
 import { AnimeWordList } from './AnimeWordList';
 import { AnilistSelector } from './AnilistSelector';
+import { TmdbSelector } from './TmdbSelector';
 import { AnimeOverviewStats } from './AnimeOverviewStats';
 import { CHART_THEME } from '../../lib/chart-theme';
 import { BarChart, Bar, XAxis, YAxis, Tooltip, ResponsiveContainer } from 'recharts';
@@ -20,11 +21,11 @@ interface AnimeDetailViewProps {
   /** Called after the whole library entry is deleted, so the caller can refresh. */
   onAnimeDeleted?: () => void;
   /**
-   * Called after the AniList link changes. The library list caches the old
-   * anilistId (and with it the cover URL), so it has to refetch or the grid
-   * keeps showing the previous title's art.
+   * Called after the AniList or TMDB link changes. The library list caches the
+   * old provider ids (and with them the cover URL and media kind), so it has to
+   * refetch or the grid keeps showing the previous title's art.
    */
-  onAnilistRelinked?: () => void;
+  onProviderRelinked?: () => void;
   /** Called after an episode is reassigned to another entry. */
   onEpisodeMoved?: () => void;
 }
@@ -151,11 +152,12 @@ export function AnimeDetailView({
   onNavigateToWord,
   onOpenEpisodeDetail,
   onAnimeDeleted,
-  onAnilistRelinked,
+  onProviderRelinked,
   onEpisodeMoved,
 }: AnimeDetailViewProps) {
   const { data, loading, error, reload } = useAnimeDetail(animeId);
   const [showAnilistSelector, setShowAnilistSelector] = useState(false);
+  const [showTmdbSelector, setShowTmdbSelector] = useState(false);
   const [coverRetryToken, setCoverRetryToken] = useState(0);
   const [isDeletingAnime, setIsDeletingAnime] = useState(false);
   const [deleteError, setDeleteError] = useState<string | null>(null);
@@ -168,7 +170,7 @@ export function AnimeDetailView({
 
   if (loading) return <div className="text-ctp-overlay2 p-4">Loading...</div>;
   if (error) return <div className="text-ctp-red p-4">Error: {error}</div>;
-  if (!data?.detail) return <div className="text-ctp-overlay2 p-4">Anime not found</div>;
+  if (!data?.detail) return <div className="text-ctp-overlay2 p-4">Library entry not found</div>;
 
   const { detail, episodes, anilistEntries } = data;
 
@@ -219,6 +221,7 @@ export function AnimeDetailView({
         anilistEntries={anilistEntries ?? []}
         coverRetryToken={coverRetryToken}
         onChangeAnilist={() => setShowAnilistSelector(true)}
+        onChangeTmdb={() => setShowTmdbSelector(true)}
         onDeleteAnime={() => void handleDeleteAnime()}
         isDeletingAnime={isDeletingAnime}
       />
@@ -226,6 +229,7 @@ export function AnimeDetailView({
       <AnimeOverviewStats detail={detail} knownWordsSummary={knownWordsSummary} />
       <EpisodeList
         episodes={episodes}
+        mediaKind={detail.mediaKind}
         animeId={animeId}
         onEpisodeMoved={(removedPreviousAnime) => {
           onEpisodeMoved?.();
@@ -237,7 +241,7 @@ export function AnimeDetailView({
       />
       <AnimeWatchChart animeId={animeId} />
       <AnimeWordList animeId={animeId} onNavigateToWord={onNavigateToWord} />
-      {showAnilistSelector && (
+      {detail.mediaKind !== 'youtube' && showAnilistSelector && (
         <AnilistSelector
           animeId={animeId}
           initialQuery={detail.canonicalTitle}
@@ -246,7 +250,20 @@ export function AnimeDetailView({
             setShowAnilistSelector(false);
             setCoverRetryToken((value) => value + 1);
             reload();
-            onAnilistRelinked?.();
+            onProviderRelinked?.();
+          }}
+        />
+      )}
+      {showTmdbSelector && (
+        <TmdbSelector
+          animeId={animeId}
+          initialQuery={detail.canonicalTitle}
+          onClose={() => setShowTmdbSelector(false)}
+          onLinked={() => {
+            setShowTmdbSelector(false);
+            setCoverRetryToken((value) => value + 1);
+            reload();
+            onProviderRelinked?.();
           }}
         />
       )}
diff --git a/stats/src/components/anime/AnimeDialogAccessibility.test.tsx b/stats/src/components/anime/AnimeDialogAccessibility.test.tsx
index ea5dbea6..c3f8f813 100644
--- a/stats/src/components/anime/AnimeDialogAccessibility.test.tsx
+++ b/stats/src/components/anime/AnimeDialogAccessibility.test.tsx
@@ -46,9 +46,12 @@ function installDom(): () => void {
 
 function libraryItem(animeId: number, title: string): AnimeLibraryItem {
   return {
+    mediaKind: 'anime',
     animeId,
     canonicalTitle: title,
     anilistId: null,
+    tmdbId: null,
+    tmdbType: null,
     totalSessions: 1,
     totalActiveMs: 1000,
     totalCards: 0,
diff --git a/stats/src/components/anime/AnimeHeader.test.tsx b/stats/src/components/anime/AnimeHeader.test.tsx
index 9f542a37..4277166e 100644
--- a/stats/src/components/anime/AnimeHeader.test.tsx
+++ b/stats/src/components/anime/AnimeHeader.test.tsx
@@ -6,9 +6,12 @@ import { confirmAnimeDelete, setDeleteConfirmPresenter } from '../../lib/delete-
 import type { AnimeDetailData } from '../../types/stats';
 
 const DETAIL: AnimeDetailData['detail'] = {
+  mediaKind: 'anime',
   animeId: 3,
   canonicalTitle: 'Project Radio Noise Season 2',
   anilistId: 20661,
+  tmdbId: null,
+  tmdbType: null,
   titleRomaji: 'Toaru Kagaku no Railgun S',
   titleEnglish: 'A Certain Scientific Railgun S',
   titleNative: null,
@@ -69,3 +72,56 @@ test('confirmAnimeDelete spells out how much data the entry deletion removes', a
   assert.match(seen[1] ?? '', /3 episodes/);
   assert.match(seen[0] ?? '', /every session and stat/);
 });
+
+test('AnimeHeader shows TMDB actions for a live-action entry and hides AniList links', () => {
+  const markup = renderToStaticMarkup(
+    <AnimeHeader
+      detail={{
+        ...DETAIL,
+        anilistId: null,
+        mediaKind: 'live_action',
+        tmdbId: 61222,
+        tmdbType: 'tv',
+        titleRomaji: null,
+        titleEnglish: 'Hanzawa Naoki',
+        titleNative: '半沢直樹',
+        description: 'A banker fights back.',
+      }}
+      anilistEntries={[]}
+      onChangeAnilist={() => {}}
+      onChangeTmdb={() => {}}
+    />,
+  );
+
+  assert.match(markup, /https:\/\/www\.themoviedb\.org\/tv\/61222/);
+  assert.match(markup, /Change TMDB Title/);
+  assert.match(markup, /Live action/);
+  assert.match(markup, /A banker fights back\./);
+  assert.doesNotMatch(markup, /anilist\.co/);
+});
+
+test('AnimeHeader offers to link an unlinked anime entry to TMDB', () => {
+  const markup = renderToStaticMarkup(
+    <AnimeHeader
+      detail={{ ...DETAIL, anilistId: null }}
+      anilistEntries={[]}
+      onChangeTmdb={() => {}}
+    />,
+  );
+
+  assert.match(markup, /Link to TMDB/);
+  assert.doesNotMatch(markup, /themoviedb\.org/);
+});
+
+test('YouTube channel headers show videos and omit all AniList controls', () => {
+  const markup = renderToStaticMarkup(
+    <AnimeHeader
+      detail={{ ...DETAIL, mediaKind: 'youtube' }}
+      anilistEntries={[{ anilistId: 20661, titleRomaji: null, titleEnglish: null, season: null }]}
+      onChangeAnilist={() => {}}
+    />,
+  );
+  assert.match(markup, /YouTube channel/);
+  assert.match(markup, /video/);
+  assert.doesNotMatch(markup, /AniList|anilist\.co|episode/);
+});
diff --git a/stats/src/components/anime/AnimeHeader.tsx b/stats/src/components/anime/AnimeHeader.tsx
index a6871cc3..032bf1a5 100644
--- a/stats/src/components/anime/AnimeHeader.tsx
+++ b/stats/src/components/anime/AnimeHeader.tsx
@@ -6,6 +6,7 @@ interface AnimeHeaderProps {
   anilistEntries: AnilistEntry[];
   coverRetryToken?: number;
   onChangeAnilist?: () => void;
+  onChangeTmdb?: () => void;
   onDeleteAnime?: () => void;
   isDeletingAnime?: boolean;
 }
@@ -34,16 +35,23 @@ export function AnimeHeader({
   anilistEntries,
   coverRetryToken = 0,
   onChangeAnilist,
+  onChangeTmdb,
   onDeleteAnime,
   isDeletingAnime = false,
 }: AnimeHeaderProps) {
+  const isYoutube = detail.mediaKind === 'youtube';
   const altTitles = [detail.titleRomaji, detail.titleEnglish, detail.titleNative].filter(
     (t): t is string => t != null && t !== detail.canonicalTitle,
   );
   const uniqueAltTitles = [...new Set(altTitles)];
 
   const hasMultipleEntries = anilistEntries.length > 1;
-  const coverCacheToken = (detail.anilistId ?? 0) * 1_000_000 + coverRetryToken;
+  const isLiveAction = detail.mediaKind === 'live_action';
+  const tmdbUrl =
+    detail.tmdbId && detail.tmdbType
+      ? `https://www.themoviedb.org/${detail.tmdbType}/${detail.tmdbId}`
+      : null;
+  const coverCacheToken = (detail.anilistId ?? detail.tmdbId ?? 0) * 1_000_000 + coverRetryToken;
 
   return (
     <div className="flex gap-4">
@@ -60,34 +68,55 @@ export function AnimeHeader({
             {uniqueAltTitles.join(' · ')}
           </div>
         )}
-        <div className="text-sm text-ctp-subtext0 mt-2">
-          {detail.episodeCount} episode{detail.episodeCount !== 1 ? 's' : ''}
+        <div className="text-sm text-ctp-subtext0 mt-2 flex items-center gap-2">
+          <span>
+            {isYoutube ? 'YouTube channel · ' : ''}
+            {detail.episodeCount} {isYoutube ? 'video' : 'episode'}
+            {detail.episodeCount !== 1 ? 's' : ''}
+          </span>
+          {isLiveAction && (
+            <span className="px-1.5 py-0.5 rounded text-[10px] uppercase tracking-wide bg-ctp-peach/15 text-ctp-peach">
+              {detail.tmdbType === 'movie' ? 'Movie' : 'Live action'}
+            </span>
+          )}
         </div>
         <div className="flex flex-wrap gap-1.5 mt-2">
-          {anilistEntries.length > 0 ? (
-            hasMultipleEntries ? (
-              anilistEntries.map((entry) => <AnilistButton key={entry.anilistId} entry={entry} />)
-            ) : (
+          {tmdbUrl && (
+            <a
+              href={tmdbUrl}
+              target="_blank"
+              rel="noopener noreferrer"
+              className="inline-flex items-center gap-1 px-2 py-1 text-xs rounded bg-ctp-surface1 text-ctp-blue hover:bg-ctp-surface2 hover:text-ctp-sapphire transition-colors"
+            >
+              View on TMDB <span className="text-[10px]">{'\u2197'}</span>
+            </a>
+          )}
+          {!isYoutube &&
+            !isLiveAction &&
+            (anilistEntries.length > 0 ? (
+              hasMultipleEntries ? (
+                anilistEntries.map((entry) => <AnilistButton key={entry.anilistId} entry={entry} />)
+              ) : (
+                <a
+                  href={`https://anilist.co/anime/${anilistEntries[0]!.anilistId}`}
+                  target="_blank"
+                  rel="noopener noreferrer"
+                  className="inline-flex items-center gap-1 px-2 py-1 text-xs rounded bg-ctp-surface1 text-ctp-blue hover:bg-ctp-surface2 hover:text-ctp-sapphire transition-colors"
+                >
+                  View on AniList <span className="text-[10px]">{'\u2197'}</span>
+                </a>
+              )
+            ) : detail.anilistId ? (
               <a
-                href={`https://anilist.co/anime/${anilistEntries[0]!.anilistId}`}
+                href={`https://anilist.co/anime/${detail.anilistId}`}
                 target="_blank"
                 rel="noopener noreferrer"
                 className="inline-flex items-center gap-1 px-2 py-1 text-xs rounded bg-ctp-surface1 text-ctp-blue hover:bg-ctp-surface2 hover:text-ctp-sapphire transition-colors"
               >
                 View on AniList <span className="text-[10px]">{'\u2197'}</span>
               </a>
-            )
-          ) : detail.anilistId ? (
-            <a
-              href={`https://anilist.co/anime/${detail.anilistId}`}
-              target="_blank"
-              rel="noopener noreferrer"
-              className="inline-flex items-center gap-1 px-2 py-1 text-xs rounded bg-ctp-surface1 text-ctp-blue hover:bg-ctp-surface2 hover:text-ctp-sapphire transition-colors"
-            >
-              View on AniList <span className="text-[10px]">{'\u2197'}</span>
-            </a>
-          ) : null}
-          {onChangeAnilist && (
+            ) : null)}
+          {!isYoutube && onChangeAnilist && (
             <button
               type="button"
               onClick={onChangeAnilist}
@@ -99,6 +128,16 @@ export function AnimeHeader({
                 : 'Link to AniList'}
             </button>
           )}
+          {!isYoutube && onChangeTmdb && (
+            <button
+              type="button"
+              onClick={onChangeTmdb}
+              title="Search TMDB and link this title to a live-action drama or movie"
+              className="inline-flex items-center gap-1 px-2 py-1 text-xs rounded bg-ctp-surface1 text-ctp-overlay2 hover:bg-ctp-surface2 hover:text-ctp-subtext0 transition-colors"
+            >
+              {tmdbUrl ? 'Change TMDB Title' : 'Link to TMDB'}
+            </button>
+          )}
           {onDeleteAnime && (
             <button
               type="button"
diff --git a/stats/src/components/anime/AnimeMergeDialog.tsx b/stats/src/components/anime/AnimeMergeDialog.tsx
index 066707a7..f9712e62 100644
--- a/stats/src/components/anime/AnimeMergeDialog.tsx
+++ b/stats/src/components/anime/AnimeMergeDialog.tsx
@@ -11,6 +11,27 @@ interface AnimeMergeDialogProps {
   onMerged: (survivingAnimeId: number) => void;
 }
 
+const PROVIDER_CONFLICT_MESSAGE =
+  'AniList-linked and TMDB-linked entries cannot be merged together. Relink one of them first.';
+const KIND_CONFLICT_MESSAGE =
+  'YouTube channels cannot be merged with anime or live-action entries.';
+
+/** Merging an AniList entry with a TMDB entry is rejected by the server (409), as is mixing in a channel. */
+function hasProviderConflict(entries: AnimeLibraryItem[]): boolean {
+  return (
+    entries.some((entry) => entry.anilistId !== null) &&
+    entries.some((entry) => entry.tmdbId !== null)
+  );
+}
+
+function describeMergeError(err: unknown, entries: AnimeLibraryItem[]): string {
+  const message = err instanceof Error ? err.message : '';
+  if (/^Stats API error: 409\b/.test(message)) {
+    return hasProviderConflict(entries) ? PROVIDER_CONFLICT_MESSAGE : KIND_CONFLICT_MESSAGE;
+  }
+  return message || 'Failed to merge these entries.';
+}
+
 /** Biggest entry first: the one most likely to carry the right title and art. */
 function pickDefaultKeeper(entries: AnimeLibraryItem[]): number {
   const best = [...entries].sort(
@@ -26,6 +47,7 @@ export function AnimeMergeDialog({ entries, onClose, onMerged }: AnimeMergeDialo
   const [keeperId, setKeeperId] = useState(() => pickDefaultKeeper(entries));
   const [merging, setMerging] = useState(false);
   const [error, setError] = useState<string | null>(null);
+  const providerConflict = hasProviderConflict(entries);
 
   const totalEpisodes = entries.reduce((sum, entry) => sum + entry.episodeCount, 0);
   const totalCards = entries.reduce((sum, entry) => sum + entry.totalCards, 0);
@@ -42,14 +64,14 @@ export function AnimeMergeDialog({ entries, onClose, onMerged }: AnimeMergeDialo
     const sourceAnimeIds = entries
       .map((entry) => entry.animeId)
       .filter((animeId) => animeId !== keeperId);
-    if (sourceAnimeIds.length === 0) return;
+    if (sourceAnimeIds.length === 0 || providerConflict) return;
     setMerging(true);
     setError(null);
     try {
       const result = await apiClient.mergeAnime(keeperId, sourceAnimeIds);
       onMerged(result.animeId);
     } catch (err) {
-      setError(err instanceof Error ? err.message : 'Failed to merge these entries.');
+      setError(describeMergeError(err, entries));
       setMerging(false);
     }
   };
@@ -120,7 +142,7 @@ export function AnimeMergeDialog({ entries, onClose, onMerged }: AnimeMergeDialo
               <AnimeCoverImage
                 animeId={entry.animeId}
                 title={entry.canonicalTitle}
-                coverRetryToken={entry.anilistId ?? 0}
+                coverRetryToken={entry.anilistId ?? entry.tmdbId ?? 0}
                 className="w-10 h-14 rounded shrink-0"
               />
               <div className="min-w-0 flex-1">
@@ -138,7 +160,11 @@ export function AnimeMergeDialog({ entries, onClose, onMerged }: AnimeMergeDialo
         </div>
 
         <div className="p-4 border-t border-ctp-surface1 space-y-2">
-          {error ? (
+          {providerConflict ? (
+            <div role="alert" className="text-xs text-ctp-peach">
+              {PROVIDER_CONFLICT_MESSAGE}
+            </div>
+          ) : error ? (
             <div role="alert" className="text-xs text-ctp-red">
               {error}
             </div>
@@ -150,7 +176,7 @@ export function AnimeMergeDialog({ entries, onClose, onMerged }: AnimeMergeDialo
             </div>
             <button
               type="button"
-              disabled={merging}
+              disabled={merging || providerConflict}
               onClick={() => void handleMerge()}
               className="px-3 py-1.5 rounded-lg bg-ctp-blue/15 border border-ctp-blue/40 text-xs text-ctp-blue hover:bg-ctp-blue/25 transition-colors disabled:opacity-50"
             >
diff --git a/stats/src/components/anime/AnimeMergeFlow.test.tsx b/stats/src/components/anime/AnimeMergeFlow.test.tsx
index 64c7a808..7aa140bb 100644
--- a/stats/src/components/anime/AnimeMergeFlow.test.tsx
+++ b/stats/src/components/anime/AnimeMergeFlow.test.tsx
@@ -5,6 +5,7 @@ import { act } from 'react';
 import { createRoot } from 'react-dom/client';
 import { apiClient } from '../../lib/api-client';
 import type { AnimeLibraryItem, StatsMergeAnimeResponse } from '../../types/stats';
+import { AnimeMergeDialog } from './AnimeMergeDialog';
 import { AnimeTab } from './AnimeTab';
 
 interface TestWindow extends Window {
@@ -45,9 +46,12 @@ function installDom(): () => void {
 
 function libraryItem(animeId: number, title: string, episodeCount: number): AnimeLibraryItem {
   return {
+    mediaKind: 'anime',
     animeId,
     canonicalTitle: title,
     anilistId: null,
+    tmdbId: null,
+    tmdbType: null,
     totalSessions: 1,
     totalActiveMs: 1000,
     totalCards: 1,
@@ -68,7 +72,9 @@ function findButton(container: Element, label: string): HTMLElement {
 
 /** Library cards only expose aria-pressed while selection mode is on. */
 function cardButtons(container: Element): HTMLButtonElement[] {
-  return [...container.querySelectorAll('button[aria-pressed]')] as unknown as HTMLButtonElement[];
+  return [
+    ...container.querySelectorAll('.grid button[aria-pressed]'),
+  ] as unknown as HTMLButtonElement[];
 }
 
 function mergeButton(container: Element): HTMLButtonElement {
@@ -162,6 +168,52 @@ test('AnimeTab merges the selected duplicate entries into the chosen keeper', as
   }
 });
 
+test('AnimeMergeDialog refuses to merge an AniList entry with a TMDB entry', async () => {
+  const uninstallDom = installDom();
+  const originalMerge = apiClient.mergeAnime;
+  let mergeCalls = 0;
+  apiClient.mergeAnime = (async () => {
+    mergeCalls += 1;
+    throw new Error('unexpected merge');
+  }) as typeof apiClient.mergeAnime;
+
+  const anime = { ...libraryItem(1, 'Show', 2), anilistId: 100 };
+  const drama = {
+    ...libraryItem(2, 'Show', 1),
+    mediaKind: 'live_action' as const,
+    tmdbId: 200,
+    tmdbType: 'tv' as const,
+  };
+
+  try {
+    const container = document.createElement('div');
+    document.body.append(container);
+    const root = createRoot(container);
+
+    await act(async () => {
+      root.render(
+        <AnimeMergeDialog entries={[anime, drama]} onClose={() => {}} onMerged={() => {}} />,
+      );
+    });
+
+    const merge = findButton(container, 'Merge Entries') as HTMLButtonElement;
+    assert.equal(merge.disabled, true);
+    assert.match(container.textContent ?? '', /cannot be merged together/);
+
+    await act(async () => {
+      merge.click();
+    });
+    assert.equal(mergeCalls, 0);
+
+    await act(async () => {
+      root.unmount();
+    });
+  } finally {
+    apiClient.mergeAnime = originalMerge;
+    uninstallDom();
+  }
+});
+
 test('AnimeTab keeps a suggested duplicate visible until it is reviewed and merged', async () => {
   const uninstallDom = installDom();
   const original = {
diff --git a/stats/src/components/anime/AnimeOverviewStats.tsx b/stats/src/components/anime/AnimeOverviewStats.tsx
index 434a6a08..f03b4523 100644
--- a/stats/src/components/anime/AnimeOverviewStats.tsx
+++ b/stats/src/components/anime/AnimeOverviewStats.tsx
@@ -53,19 +53,19 @@ export function AnimeOverviewStats({ detail, knownWordsSummary }: AnimeOverviewS
           label="Watch Time"
           value={formatDuration(detail.totalActiveMs)}
           color="text-ctp-blue"
-          tooltip="Total active watch time for this anime"
+          tooltip="Total active watch time for this title"
         />
         <Metric
           label="Sessions"
           value={String(detail.totalSessions)}
           color="text-ctp-peach"
-          tooltip="Number of immersion sessions on this anime"
+          tooltip="Number of immersion sessions on this title"
         />
         <Metric
-          label="Episodes"
+          label={detail.mediaKind === 'youtube' ? 'Videos' : 'Episodes'}
           value={String(detail.episodeCount)}
           color="text-ctp-yellow"
-          tooltip="Number of completed episodes for this anime"
+          tooltip={`Number of tracked ${detail.mediaKind === 'youtube' ? 'videos' : 'episodes'} for this title`}
         />
         <Metric
           label="Words Seen"
@@ -81,7 +81,7 @@ export function AnimeOverviewStats({ detail, knownWordsSummary }: AnimeOverviewS
           label="Cards Mined"
           value={formatNumber(detail.totalCards)}
           color="text-ctp-cards-mined"
-          tooltip="Anki cards created from subtitle lines in this anime"
+          tooltip="Anki cards created from subtitle lines in this title"
         />
         <Metric
           label="Lookups"
@@ -109,7 +109,7 @@ export function AnimeOverviewStats({ detail, knownWordsSummary }: AnimeOverviewS
             label="Known Words"
             value={`${knownPct}%`}
             color="text-ctp-green"
-            tooltip={`${formatNumber(knownWordsSummary!.knownWordCount)} known out of ${formatNumber(knownWordsSummary!.totalUniqueWords)} unique words in this anime`}
+            tooltip={`${formatNumber(knownWordsSummary!.knownWordCount)} known out of ${formatNumber(knownWordsSummary!.totalUniqueWords)} unique words in this title`}
           />
         ) : (
           <Metric
diff --git a/stats/src/components/anime/AnimeTab.test.tsx b/stats/src/components/anime/AnimeTab.test.tsx
index c02d9590..12287d66 100644
--- a/stats/src/components/anime/AnimeTab.test.tsx
+++ b/stats/src/components/anime/AnimeTab.test.tsx
@@ -45,9 +45,12 @@ function installDom(): () => void {
 
 function libraryItem(anilistId: number | null): AnimeLibraryItem {
   return {
+    mediaKind: 'anime',
     animeId: 7,
     canonicalTitle: 'Test Anime Season 2',
     anilistId,
+    tmdbId: null,
+    tmdbType: null,
     totalSessions: 1,
     totalActiveMs: 1000,
     totalCards: 0,
@@ -61,9 +64,12 @@ function libraryItem(anilistId: number | null): AnimeLibraryItem {
 function detailData(anilistId: number | null): AnimeDetailData {
   return {
     detail: {
+      mediaKind: 'anime',
       animeId: 7,
       canonicalTitle: 'Test Anime Season 2',
       anilistId,
+      tmdbId: null,
+      tmdbType: null,
       titleRomaji: null,
       titleEnglish: null,
       titleNative: null,
@@ -177,3 +183,92 @@ test('AnimeTab refetches the library after the AniList entry is relinked', async
     uninstallDom();
   }
 });
+
+test('AnimeTab watch time follows the displayed kind filter', async () => {
+  const uninstallDom = installDom();
+  const original = apiClient.getAnimeLibrary;
+  apiClient.getAnimeLibrary = async () => [
+    { ...libraryItem(42), totalActiveMs: 3600000 },
+    {
+      ...libraryItem(null),
+      animeId: 8,
+      canonicalTitle: 'Drama',
+      mediaKind: 'live_action',
+      tmdbId: 12,
+      tmdbType: 'tv',
+      totalActiveMs: 7200000,
+    },
+  ];
+  const container = document.createElement('div');
+  document.body.append(container);
+  const root = createRoot(container);
+  try {
+    await act(async () => {
+      root.render(<AnimeTab />);
+    });
+    assert.match(container.textContent ?? '', /2 titles · 3h/);
+    await act(async () => {
+      findButton(container, 'Live Action').click();
+    });
+    assert.match(container.textContent ?? '', /1 title · 2h/);
+    assert.equal(findButton(container, 'Live Action').getAttribute('aria-pressed'), 'true');
+  } finally {
+    await act(async () => {
+      root.unmount();
+    });
+    apiClient.getAnimeLibrary = original;
+    uninstallDom();
+  }
+});
+
+test('Library kind filter separates YouTube channels from anime and updates totals', async () => {
+  const uninstallDom = installDom();
+  const original = {
+    getAnimeLibrary: apiClient.getAnimeLibrary,
+    getAnimeMergeRecommendations: apiClient.getAnimeMergeRecommendations,
+  };
+  apiClient.getAnimeLibrary = async () => [
+    { ...libraryItem(null), totalActiveMs: 60_000 },
+    {
+      ...libraryItem(null),
+      animeId: 8,
+      mediaKind: 'youtube',
+      canonicalTitle: 'Language Channel',
+      totalActiveMs: 120_000,
+    },
+  ];
+  apiClient.getAnimeMergeRecommendations = async () => ({ recommendations: [] });
+  const container = document.createElement('div');
+  document.body.append(container);
+  const root = createRoot(container);
+  try {
+    await act(async () => {
+      root.render(<AnimeTab />);
+    });
+    assert.match(container.textContent ?? '', /Test Anime Season 2/);
+    assert.match(container.textContent ?? '', /Language Channel/);
+    assert.match(container.textContent ?? '', /2 titles · 3m/);
+    await act(async () => {
+      findButton(container, 'YouTube').click();
+    });
+    assert.doesNotMatch(container.textContent ?? '', /Test Anime Season 2/);
+    assert.match(container.textContent ?? '', /Language Channel/);
+    assert.match(container.textContent ?? '', /1 channel · 2m/);
+    assert.equal(findButton(container, 'YouTube').getAttribute('aria-pressed'), 'true');
+    await act(async () => {
+      findButton(container, 'Anime').click();
+    });
+    assert.match(container.textContent ?? '', /Test Anime Season 2/);
+    assert.doesNotMatch(container.textContent ?? '', /Language Channel/);
+    await act(async () => {
+      findButton(container, 'All Titles').click();
+    });
+    assert.match(container.textContent ?? '', /Language Channel/);
+  } finally {
+    await act(async () => {
+      root.unmount();
+    });
+    Object.assign(apiClient, original);
+    uninstallDom();
+  }
+});
diff --git a/stats/src/components/anime/AnimeTab.tsx b/stats/src/components/anime/AnimeTab.tsx
index a6cc45b6..54275b57 100644
--- a/stats/src/components/anime/AnimeTab.tsx
+++ b/stats/src/components/anime/AnimeTab.tsx
@@ -1,3 +1,8 @@
+import {
+  MEDIA_KINDS,
+  shareTitleNamespace,
+  type MediaKind,
+} from '../../../../src/shared/media-kind';
 import { useState, useMemo, useEffect } from 'react';
 import { useAnimeLibrary } from '../../hooks/useAnimeLibrary';
 import { formatDuration } from '../../lib/formatters';
@@ -20,6 +25,13 @@ const GRID_CLASSES: Record<LibraryCardSize, string> = {
   lg: 'grid-cols-3 sm:grid-cols-4 md:grid-cols-5 lg:grid-cols-7',
 };
 
+const KIND_LABELS: Record<MediaKind | 'all', string> = {
+  all: 'All Titles',
+  anime: 'Anime',
+  live_action: 'Live Action',
+  youtube: 'YouTube',
+};
+
 const SORT_OPTIONS: { key: SortKey; label: string }[] = [
   { key: 'lastWatched', label: 'Last Watched' },
   { key: 'watchTime', label: 'Watch Time' },
@@ -67,6 +79,7 @@ export function AnimeTab({
     clearRecommendation,
   } = useAnimeLibrary();
   const [search, setSearch] = useState('');
+  const [mediaKind, setMediaKind] = useState<MediaKind | 'all'>('all');
   const [sortKey, setSortKey] = useState<SortKey>('lastWatched');
   const [cardSize, setCardSize] = useState<LibraryCardSize>(() =>
     readLibraryCardSizePreference(
@@ -108,16 +121,22 @@ export function AnimeTab({
   }, [initialAnimeId, onClearInitialAnime]);
 
   const filtered = useMemo(() => {
+    const entries = anime.filter((entry) => mediaKind === 'all' || entry.mediaKind === mediaKind);
     const base = search.trim()
-      ? anime.filter((a) => a.canonicalTitle.toLowerCase().includes(search.toLowerCase()))
-      : anime;
+      ? entries.filter((a) => a.canonicalTitle.toLowerCase().includes(search.toLowerCase()))
+      : entries;
     return sortAnime(base, sortKey);
-  }, [anime, search, sortKey]);
+  }, [anime, search, sortKey, mediaKind]);
 
-  const totalMs = anime.reduce((sum, a) => sum + a.totalActiveMs, 0);
+  const totalMs = filtered.reduce((sum, a) => sum + a.totalActiveMs, 0);
   const checkedEntries = checkedAnimeIds
     .map((animeId) => anime.find((entry) => entry.animeId === animeId))
     .filter((entry): entry is (typeof anime)[number] => entry !== undefined);
+  // Anime and live-action entries may be combined (the server only rejects
+  // conflicting AniList/TMDB links); channels never mix with either.
+  const mixedKindsChecked = checkedEntries.some(
+    (entry) => !shareTitleNamespace(entry.mediaKind, checkedEntries[0]!.mediaKind),
+  );
   const hydratedRecommendations = recommendations
     .map((recommendation) => ({
       ...recommendation,
@@ -125,7 +144,12 @@ export function AnimeTab({
         .map((animeId) => anime.find((entry) => entry.animeId === animeId))
         .filter((entry): entry is (typeof anime)[number] => entry !== undefined),
     }))
-    .filter((recommendation) => recommendation.entries.length >= 2);
+    .filter(
+      (recommendation) =>
+        recommendation.entries.length >= 2 &&
+        (mediaKind === 'all' ||
+          recommendation.entries.every((entry) => entry.mediaKind === mediaKind)),
+    );
   const activeRecommendation = hydratedRecommendations[0] ?? null;
   const reviewEntries = (reviewAnimeIds ?? [])
     .map((animeId) => anime.find((entry) => entry.animeId === animeId))
@@ -144,7 +168,7 @@ export function AnimeTab({
             : undefined
         }
         onAnimeDeleted={reload}
-        onAnilistRelinked={reload}
+        onProviderRelinked={reload}
         onEpisodeMoved={reload}
       />
     );
@@ -155,7 +179,31 @@ export function AnimeTab({
 
   return (
     <div className="space-y-4">
-      <div className="flex items-center gap-3">
+      <div className="flex flex-wrap items-center gap-3">
+        <div
+          className="flex bg-ctp-surface0 rounded-lg p-0.5 border border-ctp-surface1"
+          aria-label="Media kind"
+          role="group"
+        >
+          {(['all', ...MEDIA_KINDS] as const).map((kind) => (
+            <button
+              key={kind}
+              type="button"
+              aria-pressed={mediaKind === kind}
+              onClick={() => {
+                setMediaKind(kind);
+                exitSelectionMode();
+              }}
+              className={`px-3 py-1.5 rounded-md text-xs transition-colors ${
+                mediaKind === kind
+                  ? 'bg-ctp-surface2 text-ctp-text'
+                  : 'text-ctp-overlay2 hover:text-ctp-subtext0'
+              }`}
+            >
+              {KIND_LABELS[kind]}
+            </button>
+          ))}
+        </div>
         <input
           type="text"
           placeholder="Search library..."
@@ -170,7 +218,7 @@ export function AnimeTab({
         >
           {SORT_OPTIONS.map((opt) => (
             <option key={opt.key} value={opt.key}>
-              {opt.label}
+              {opt.key === 'episodes' && mediaKind === 'youtube' ? 'Videos' : opt.label}
             </option>
           ))}
         </select>
@@ -202,7 +250,15 @@ export function AnimeTab({
           {selectionMode ? 'Cancel' : 'Select'}
         </button>
         <div className="text-xs text-ctp-overlay2 shrink-0">
-          {filtered.length} titles · {formatDuration(totalMs)}
+          {filtered.length}{' '}
+          {mediaKind === 'youtube'
+            ? filtered.length === 1
+              ? 'channel'
+              : 'channels'
+            : filtered.length === 1
+              ? 'title'
+              : 'titles'}{' '}
+          · {formatDuration(totalMs)}
         </div>
       </div>
 
@@ -227,11 +283,13 @@ export function AnimeTab({
           <div className="text-xs text-ctp-overlay2">
             {checkedEntries.length === 0
               ? 'Pick the duplicate entries to combine'
-              : `${checkedEntries.length} selected`}
+              : mixedKindsChecked
+                ? 'YouTube channels cannot be combined with other titles'
+                : `${checkedEntries.length} selected`}
           </div>
           <button
             type="button"
-            disabled={checkedEntries.length < 2}
+            disabled={checkedEntries.length < 2 || mixedKindsChecked}
             onClick={() => setShowMergeDialog(true)}
             className="px-3 py-1.5 rounded-lg bg-ctp-blue/15 border border-ctp-blue/40 text-xs text-ctp-blue hover:bg-ctp-blue/25 transition-colors disabled:opacity-40 disabled:cursor-not-allowed"
           >
@@ -258,6 +316,11 @@ export function AnimeTab({
         </div>
       )}
 
+      <p className="text-[11px] text-ctp-overlay2 pt-2">
+        Cover art and synopses come from AniList and TMDB. This product uses the TMDB API but is not
+        endorsed or certified by TMDB.
+      </p>
+
       {showMergeDialog && mergeEntries.length >= 2 && (
         <AnimeMergeDialog
           entries={mergeEntries}
diff --git a/stats/src/components/anime/EpisodeList.tsx b/stats/src/components/anime/EpisodeList.tsx
index daddafdc..adf05b3b 100644
--- a/stats/src/components/anime/EpisodeList.tsx
+++ b/stats/src/components/anime/EpisodeList.tsx
@@ -6,6 +6,7 @@ import { buildLookupRateDisplay } from '../../lib/yomitan-lookup';
 import { EpisodeDetail } from './EpisodeDetail';
 import { LibraryEntryPicker } from './LibraryEntryPicker';
 import type { AnimeEpisode } from '../../types/stats';
+import type { MediaKind } from '../../../../src/shared/media-kind';
 
 /**
  * Row actions that only appear on hover. Keyboard focus and pointers with no
@@ -17,6 +18,8 @@ const HOVER_REVEALED =
 
 interface EpisodeListProps {
   episodes: AnimeEpisode[];
+  /** Kind of the owning entry; the move picker only offers entries of the same kind. */
+  mediaKind?: MediaKind;
   /** Entry these episodes currently belong to; excluded from the move picker. */
   animeId?: number;
   onEpisodeDeleted?: () => void;
@@ -27,11 +30,13 @@ interface EpisodeListProps {
 
 export function EpisodeList({
   episodes: initialEpisodes,
+  mediaKind = 'anime',
   animeId,
   onEpisodeDeleted,
   onEpisodeMoved,
   onOpenDetail,
 }: EpisodeListProps) {
+  const isYoutube = mediaKind === 'youtube';
   const [expandedVideoId, setExpandedVideoId] = useState<number | null>(null);
   const [episodes, setEpisodes] = useState(initialEpisodes);
   const [movingEpisode, setMovingEpisode] = useState<AnimeEpisode | null>(null);
@@ -90,7 +95,7 @@ export function EpisodeList({
   return (
     <div className="bg-ctp-surface0 border border-ctp-surface1 rounded-lg p-4">
       <div className="flex items-center justify-between mb-3">
-        <h3 className="text-sm font-semibold text-ctp-text">Episodes</h3>
+        <h3 className="text-sm font-semibold text-ctp-text">{isYoutube ? 'Videos' : 'Episodes'}</h3>
         <span className="text-xs text-ctp-overlay2">
           {watchedCount}/{episodes.length} watched
         </span>
@@ -178,7 +183,7 @@ export function EpisodeList({
                               onOpenDetail(ep.videoId);
                             }}
                             className="px-2 py-1 rounded border border-ctp-surface2 text-[11px] text-ctp-blue hover:border-ctp-blue/50 hover:bg-ctp-blue/10 transition-colors"
-                            title="Open episode details"
+                            title={isYoutube ? 'Open video details' : 'Open episode details'}
                           >
                             Details
                           </button>
@@ -218,8 +223,8 @@ export function EpisodeList({
                             void handleDeleteEpisode(ep.videoId, ep.canonicalTitle);
                           }}
                           className={`w-5 h-5 rounded border border-ctp-surface2 text-transparent hover:border-ctp-red/50 hover:text-ctp-red focus-visible:text-ctp-red hover:bg-ctp-red/10 transition-colors text-xs flex items-center justify-center ${HOVER_REVEALED}`}
-                          title="Delete episode"
-                          aria-label="Delete episode"
+                          title={isYoutube ? 'Delete video' : 'Delete episode'}
+                          aria-label={isYoutube ? 'Delete video' : 'Delete episode'}
                         >
                           {'\u2715'}
                         </button>
@@ -243,6 +248,7 @@ export function EpisodeList({
         <LibraryEntryPicker
           heading={`Move "${movingEpisode.canonicalTitle}" To`}
           excludeAnimeIds={animeId != null ? [animeId] : []}
+          mediaKind={mediaKind}
           busyAnimeId={moveTargetId}
           error={moveError}
           onSelect={(entry) => void handleMoveEpisode(movingEpisode.videoId, entry.animeId)}
diff --git a/stats/src/components/anime/EpisodeMove.test.tsx b/stats/src/components/anime/EpisodeMove.test.tsx
index 57a40966..6f1f7ae2 100644
--- a/stats/src/components/anime/EpisodeMove.test.tsx
+++ b/stats/src/components/anime/EpisodeMove.test.tsx
@@ -63,9 +63,12 @@ function episode(videoId: number, title: string): AnimeEpisode {
 
 function libraryItem(animeId: number, title: string): AnimeLibraryItem {
   return {
+    mediaKind: 'anime',
     animeId,
     canonicalTitle: title,
     anilistId: null,
+    tmdbId: null,
+    tmdbType: null,
     totalSessions: 1,
     totalActiveMs: 1000,
     totalCards: 0,
diff --git a/stats/src/components/anime/LibraryEntryPicker.tsx b/stats/src/components/anime/LibraryEntryPicker.tsx
index 222d9519..51b0252c 100644
--- a/stats/src/components/anime/LibraryEntryPicker.tsx
+++ b/stats/src/components/anime/LibraryEntryPicker.tsx
@@ -4,11 +4,14 @@ import { formatDuration } from '../../lib/formatters';
 import { useModalFocus } from '../../hooks/useModalFocus';
 import { AnimeCoverImage } from './AnimeCoverImage';
 import type { AnimeLibraryItem } from '../../types/stats';
+import { shareTitleNamespace, type MediaKind } from '../../../../src/shared/media-kind';
 
 interface LibraryEntryPickerProps {
   heading: string;
   /** Entries that cannot be picked, typically the one being moved away from. */
   excludeAnimeIds?: number[];
+  /** When set, only entries of this kind are offered. */
+  mediaKind?: MediaKind;
   initialQuery?: string;
   busyAnimeId?: number | null;
   error?: string | null;
@@ -19,6 +22,7 @@ interface LibraryEntryPickerProps {
 export function LibraryEntryPicker({
   heading,
   excludeAnimeIds = [],
+  mediaKind,
   initialQuery = '',
   busyAnimeId = null,
   error = null,
@@ -69,9 +73,10 @@ export function LibraryEntryPicker({
     const term = query.trim().toLowerCase();
     return (entries ?? [])
       .filter((entry) => !excluded.has(entry.animeId))
+      .filter((entry) => mediaKind === undefined || shareTitleNamespace(entry.mediaKind, mediaKind))
       .filter((entry) => !term || entry.canonicalTitle.toLowerCase().includes(term))
       .sort((a, b) => b.lastWatchedMs - a.lastWatchedMs);
-  }, [entries, excluded, query]);
+  }, [entries, excluded, mediaKind, query]);
 
   return (
     <div
@@ -144,14 +149,14 @@ export function LibraryEntryPicker({
               <AnimeCoverImage
                 animeId={entry.animeId}
                 title={entry.canonicalTitle}
-                coverRetryToken={entry.anilistId ?? 0}
+                coverRetryToken={entry.anilistId ?? entry.tmdbId ?? 0}
                 className="w-10 h-14 rounded shrink-0"
               />
               <div className="min-w-0 flex-1">
                 <div className="text-sm text-ctp-text truncate">{entry.canonicalTitle}</div>
                 <div className="text-xs text-ctp-overlay2 mt-0.5">
-                  {entry.episodeCount} episode{entry.episodeCount !== 1 ? 's' : ''} ·{' '}
-                  {formatDuration(entry.totalActiveMs)}
+                  {entry.episodeCount} {entry.mediaKind === 'youtube' ? 'video' : 'episode'}
+                  {entry.episodeCount !== 1 ? 's' : ''} · {formatDuration(entry.totalActiveMs)}
                 </div>
               </div>
               {busyAnimeId === entry.animeId ? (
diff --git a/stats/src/components/anime/TmdbSelector.test.tsx b/stats/src/components/anime/TmdbSelector.test.tsx
new file mode 100644
index 00000000..0a530319
--- /dev/null
+++ b/stats/src/components/anime/TmdbSelector.test.tsx
@@ -0,0 +1,387 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { Window } from 'happy-dom';
+import { act } from 'react';
+import { createRoot } from 'react-dom/client';
+import { apiClient } from '../../lib/api-client';
+import type { StatsTmdbSearchResult } from '../../types/stats';
+import { TmdbSelector } from './TmdbSelector';
+
+interface TestWindow extends Window {
+  IS_REACT_ACT_ENVIRONMENT?: boolean;
+}
+
+function installDom(): () => void {
+  const previousWindow = globalThis.window;
+  const previousDocument = globalThis.document;
+  const previousHTMLElement = globalThis.HTMLElement;
+  const previousISReactActEnvironment = (
+    globalThis as typeof globalThis & { IS_REACT_ACT_ENVIRONMENT?: boolean }
+  ).IS_REACT_ACT_ENVIRONMENT;
+  const window = new Window() as TestWindow;
+
+  Object.defineProperty(globalThis, 'window', { value: window, configurable: true });
+  Object.defineProperty(globalThis, 'document', { value: window.document, configurable: true });
+  Object.defineProperty(globalThis, 'HTMLElement', {
+    value: window.HTMLElement,
+    configurable: true,
+  });
+  (
+    globalThis as typeof globalThis & { IS_REACT_ACT_ENVIRONMENT?: boolean }
+  ).IS_REACT_ACT_ENVIRONMENT = true;
+
+  return () => {
+    Object.defineProperty(globalThis, 'window', { value: previousWindow, configurable: true });
+    Object.defineProperty(globalThis, 'document', {
+      value: previousDocument,
+      configurable: true,
+    });
+    Object.defineProperty(globalThis, 'HTMLElement', {
+      value: previousHTMLElement,
+      configurable: true,
+    });
+    (
+      globalThis as typeof globalThis & { IS_REACT_ACT_ENVIRONMENT?: boolean }
+    ).IS_REACT_ACT_ENVIRONMENT = previousISReactActEnvironment;
+  };
+}
+
+const HANZAWA: StatsTmdbSearchResult = {
+  tmdbId: 61222,
+  tmdbType: 'tv',
+  title: 'Hanzawa Naoki',
+  originalTitle: '半沢直樹',
+  originalLanguage: 'ja',
+  overview: null,
+  posterUrl: null,
+  year: 2013,
+  isAnimation: false,
+};
+
+test('TmdbSelector searches the normalized title and links the picked result by id', async () => {
+  const uninstallDom = installDom();
+  const original = {
+    searchTmdb: apiClient.searchTmdb,
+    reassignAnimeTmdb: apiClient.reassignAnimeTmdb,
+  };
+  const searchCalls: string[] = [];
+  const linkCalls: Array<[number, { tmdbId: number; tmdbType: string }]> = [];
+  let linked = 0;
+  apiClient.searchTmdb = (async (query: string) => {
+    searchCalls.push(query);
+    return [HANZAWA];
+  }) as typeof apiClient.searchTmdb;
+  apiClient.reassignAnimeTmdb = (async (animeId: number, info) => {
+    linkCalls.push([animeId, info]);
+  }) as typeof apiClient.reassignAnimeTmdb;
+
+  try {
+    const container = document.createElement('div');
+    document.body.append(container);
+    const root = createRoot(container);
+
+    await act(async () => {
+      root.render(
+        <TmdbSelector
+          animeId={9}
+          initialQuery="Hanzawa Naoki Season 2"
+          onClose={() => {}}
+          onLinked={() => {
+            linked += 1;
+          }}
+        />,
+      );
+    });
+
+    assert.deepEqual(searchCalls, ['Hanzawa Naoki']);
+    assert.match(container.textContent ?? '', /半沢直樹/);
+    assert.match(container.textContent ?? '', /TV · 2013/);
+
+    const pick = [...container.querySelectorAll('button')].find((button) =>
+      /Select/.test(button.textContent ?? ''),
+    );
+    assert.ok(pick);
+    await act(async () => {
+      pick.click();
+    });
+
+    assert.deepEqual(linkCalls, [[9, { tmdbId: 61222, tmdbType: 'tv' }]]);
+    assert.equal(linked, 1);
+
+    await act(async () => {
+      root.unmount();
+    });
+  } finally {
+    apiClient.searchTmdb = original.searchTmdb;
+    apiClient.reassignAnimeTmdb = original.reassignAnimeTmdb;
+    uninstallDom();
+  }
+});
+
+test('TmdbSelector explains a missing API key instead of showing "No results"', async () => {
+  const uninstallDom = installDom();
+  const originalSearch = apiClient.searchTmdb;
+  apiClient.searchTmdb = (async () => {
+    throw new Error('Stats API error: 503 {"error":"TMDB API key not configured."}');
+  }) as typeof apiClient.searchTmdb;
+
+  try {
+    const container = document.createElement('div');
+    document.body.append(container);
+    const root = createRoot(container);
+
+    await act(async () => {
+      root.render(
+        <TmdbSelector
+          animeId={1}
+          initialQuery="Hanzawa Naoki"
+          onClose={() => {}}
+          onLinked={() => {}}
+        />,
+      );
+    });
+
+    assert.match(container.textContent ?? '', /tmdb\.apiKey/);
+    assert.doesNotMatch(container.textContent ?? '', /No results/);
+
+    await act(async () => {
+      root.unmount();
+    });
+  } finally {
+    apiClient.searchTmdb = originalSearch;
+    uninstallDom();
+  }
+});
+
+test('TmdbSelector reports a failed link as a link problem, not a search failure', async () => {
+  const uninstallDom = installDom();
+  const original = {
+    searchTmdb: apiClient.searchTmdb,
+    reassignAnimeTmdb: apiClient.reassignAnimeTmdb,
+  };
+  apiClient.searchTmdb = (async () => [HANZAWA]) as typeof apiClient.searchTmdb;
+  apiClient.reassignAnimeTmdb = (async () => {
+    throw new Error('Stats API error: 404');
+  }) as typeof apiClient.reassignAnimeTmdb;
+
+  try {
+    const container = document.createElement('div');
+    document.body.append(container);
+    const root = createRoot(container);
+
+    await act(async () => {
+      root.render(
+        <TmdbSelector
+          animeId={9}
+          initialQuery="Hanzawa Naoki"
+          onClose={() => {}}
+          onLinked={() => {}}
+        />,
+      );
+    });
+
+    const pick = [...container.querySelectorAll('button')].find((button) =>
+      /Select/.test(button.textContent ?? ''),
+    );
+    assert.ok(pick);
+    await act(async () => {
+      pick.click();
+    });
+
+    assert.match(container.textContent ?? '', /TMDB has no details for this title/);
+    assert.doesNotMatch(container.textContent ?? '', /search failed/);
+    // The results stay on screen so the user can pick another one.
+    assert.match(container.textContent ?? '', /半沢直樹/);
+
+    await act(async () => {
+      root.unmount();
+    });
+  } finally {
+    apiClient.searchTmdb = original.searchTmdb;
+    apiClient.reassignAnimeTmdb = original.reassignAnimeTmdb;
+    uninstallDom();
+  }
+});
+
+test('TmdbSelector cannot be dismissed while a link is in flight', async () => {
+  const uninstallDom = installDom();
+  const original = {
+    searchTmdb: apiClient.searchTmdb,
+    reassignAnimeTmdb: apiClient.reassignAnimeTmdb,
+  };
+  let finishLink: () => void = () => {};
+  let closed = 0;
+  apiClient.searchTmdb = (async () => [HANZAWA]) as typeof apiClient.searchTmdb;
+  apiClient.reassignAnimeTmdb = (() =>
+    new Promise<void>((resolve) => {
+      finishLink = resolve;
+    })) as typeof apiClient.reassignAnimeTmdb;
+
+  try {
+    const container = document.createElement('div');
+    document.body.append(container);
+    const root = createRoot(container);
+
+    await act(async () => {
+      root.render(
+        <TmdbSelector
+          animeId={9}
+          initialQuery="Hanzawa Naoki"
+          onClose={() => {
+            closed += 1;
+          }}
+          onLinked={() => {}}
+        />,
+      );
+    });
+
+    const pick = [...container.querySelectorAll('button')].find((button) =>
+      /Select/.test(button.textContent ?? ''),
+    );
+    assert.ok(pick);
+    await act(async () => {
+      pick.click();
+    });
+
+    const close = [...container.querySelectorAll('button')].find((button) =>
+      /✕/.test(button.textContent ?? ''),
+    ) as HTMLButtonElement | undefined;
+    assert.ok(close);
+    assert.equal(close.disabled, true);
+    await act(async () => {
+      (container.firstElementChild as HTMLElement).click();
+    });
+    assert.equal(closed, 0);
+
+    await act(async () => {
+      finishLink();
+    });
+
+    await act(async () => {
+      root.unmount();
+    });
+  } finally {
+    apiClient.searchTmdb = original.searchTmdb;
+    apiClient.reassignAnimeTmdb = original.reassignAnimeTmdb;
+    uninstallDom();
+  }
+});
+
+for (const staleFailure of [false, true]) {
+  test(`TmdbSelector ignores superseded ${staleFailure ? 'errors' : 'results'} and loading changes`, async () => {
+    const uninstallDom = installDom();
+    const originalSearch = apiClient.searchTmdb;
+    const requests: Array<{
+      resolve: (results: StatsTmdbSearchResult[]) => void;
+      reject: (error: Error) => void;
+    }> = [];
+    apiClient.searchTmdb = () =>
+      new Promise((resolve, reject) => {
+        requests.push({ resolve, reject });
+      });
+    const container = document.createElement('div');
+    document.body.append(container);
+    const root = createRoot(container);
+    try {
+      const render = (initialQuery: string) =>
+        root.render(
+          <TmdbSelector
+            animeId={1}
+            initialQuery={initialQuery}
+            onClose={() => {}}
+            onLinked={() => {}}
+          />,
+        );
+      await act(async () => {
+        render('First title');
+      });
+      await act(async () => {
+        render('Second title');
+      });
+      assert.equal(requests.length, 2);
+      await act(async () => {
+        if (staleFailure) requests[0]!.reject(new Error('stale error'));
+        else requests[0]!.resolve([HANZAWA]);
+      });
+      assert.match(container.textContent ?? '', /Searching/);
+      assert.doesNotMatch(container.textContent ?? '', /Hanzawa|failed/);
+      await act(async () => {
+        requests[1]!.resolve([HANZAWA]);
+      });
+      assert.match(container.textContent ?? '', /Hanzawa/);
+      assert.doesNotMatch(container.textContent ?? '', /Searching/);
+      await act(async () => {
+        render('Third title');
+      });
+      await act(async () => {
+        render('');
+      });
+      await act(async () => {
+        requests[2]!.resolve([HANZAWA]);
+      });
+      assert.doesNotMatch(container.textContent ?? '', /Hanzawa|Searching/);
+    } finally {
+      await act(async () => {
+        root.unmount();
+      });
+      apiClient.searchTmdb = originalSearch;
+      uninstallDom();
+    }
+  });
+}
+
+test('TmdbSelector invalidates requests as soon as the user edits or clears the query', async () => {
+  const uninstallDom = installDom();
+  const originalSearch = apiClient.searchTmdb;
+  const requests: Array<(results: StatsTmdbSearchResult[]) => void> = [];
+  apiClient.searchTmdb = () =>
+    new Promise((resolve) => {
+      requests.push(resolve);
+    });
+  const container = document.createElement('div');
+  document.body.append(container);
+  const root = createRoot(container);
+  try {
+    await act(async () => {
+      root.render(
+        <TmdbSelector animeId={1} initialQuery="First" onClose={() => {}} onLinked={() => {}} />,
+      );
+    });
+    const input = container.querySelector('input');
+    assert.ok(input);
+    const setValue = Object.getOwnPropertyDescriptor(
+      window.HTMLInputElement.prototype,
+      'value',
+    )?.set;
+    assert.ok(setValue);
+    const edit = async (value: string) => {
+      await act(async () => {
+        setValue.call(input, value);
+        input.dispatchEvent(new window.Event('input', { bubbles: true }));
+        input.dispatchEvent(new window.KeyboardEvent('keyup', { bubbles: true }));
+      });
+    };
+    await edit('Second');
+    await act(async () => {
+      requests[0]!([HANZAWA]);
+    });
+    assert.doesNotMatch(container.textContent ?? '', /Hanzawa|No results/);
+    assert.match(container.textContent ?? '', /Searching/);
+    await act(async () => {
+      await new Promise((resolve) => setTimeout(resolve, 450));
+    });
+    assert.equal(requests.length, 2);
+    await edit('');
+    assert.doesNotMatch(container.textContent ?? '', /Searching/);
+    await act(async () => {
+      requests[1]!([HANZAWA]);
+    });
+    assert.doesNotMatch(container.textContent ?? '', /Hanzawa|Searching/);
+  } finally {
+    await act(async () => {
+      root.unmount();
+    });
+    apiClient.searchTmdb = originalSearch;
+    uninstallDom();
+  }
+});
diff --git a/stats/src/components/anime/TmdbSelector.tsx b/stats/src/components/anime/TmdbSelector.tsx
new file mode 100644
index 00000000..f77ecfa3
--- /dev/null
+++ b/stats/src/components/anime/TmdbSelector.tsx
@@ -0,0 +1,199 @@
+import { useState, useEffect, useRef } from 'react';
+import { apiClient } from '../../lib/api-client';
+import { normalizeAnilistSearchQuery } from '../../lib/anilist-search-query';
+import type { StatsTmdbSearchResult } from '../../types/stats';
+
+interface TmdbSelectorProps {
+  animeId: number;
+  initialQuery: string;
+  onClose: () => void;
+  onLinked: () => void;
+}
+
+const MISSING_KEY_MESSAGE =
+  'TMDB API key not configured. Set tmdb.apiKey or tmdb.apiKeyCommand in your config.';
+
+function statusOf(err: unknown): number | null {
+  const match = err instanceof Error ? /^Stats API error: (\d{3})\b/.exec(err.message) : null;
+  return match ? Number(match[1]) : null;
+}
+
+// The stats API answers a missing key with 503 and the message from config.
+function describeSearchError(err: unknown): string {
+  if (statusOf(err) === 503) return MISSING_KEY_MESSAGE;
+  return 'TMDB search failed. Check your connection and API key.';
+}
+
+// The link route answers 404 when TMDB has no details for the picked id or
+// when the library entry itself is gone.
+function describeLinkError(err: unknown): string {
+  switch (statusOf(err)) {
+    case 503:
+      return MISSING_KEY_MESSAGE;
+    case 404:
+      return 'TMDB has no details for this title. Pick another result or refresh the Library.';
+    default:
+      return 'Linking to TMDB failed. Check your connection and try again.';
+  }
+}
+
+export function TmdbSelector({ animeId, initialQuery, onClose, onLinked }: TmdbSelectorProps) {
+  const [query, setQuery] = useState(() => normalizeAnilistSearchQuery(initialQuery));
+  const [results, setResults] = useState<StatsTmdbSearchResult[]>([]);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [linking, setLinking] = useState<number | null>(null);
+  const inputRef = useRef<HTMLInputElement>(null);
+  const debounceRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const searchSequenceRef = useRef(0);
+
+  useEffect(() => {
+    inputRef.current?.focus();
+    const normalizedInitialQuery = normalizeAnilistSearchQuery(initialQuery);
+    setQuery(normalizedInitialQuery);
+    setResults([]);
+    setError(null);
+    setLoading(false);
+    setLinking(null);
+    if (debounceRef.current) clearTimeout(debounceRef.current);
+    if (normalizedInitialQuery) void doSearch(normalizedInitialQuery);
+    return () => {
+      searchSequenceRef.current += 1;
+      if (debounceRef.current) clearTimeout(debounceRef.current);
+    };
+  }, [initialQuery, animeId]);
+
+  const doSearch = async (q: string) => {
+    const sequence = ++searchSequenceRef.current;
+    const searchQuery = normalizeAnilistSearchQuery(q);
+    if (!searchQuery) {
+      setResults([]);
+      setError(null);
+      setLoading(false);
+      return;
+    }
+    setLoading(true);
+    setError(null);
+    try {
+      const nextResults = await apiClient.searchTmdb(searchQuery);
+      if (sequence === searchSequenceRef.current) setResults(nextResults);
+    } catch (err) {
+      if (sequence !== searchSequenceRef.current) return;
+      setResults([]);
+      setError(describeSearchError(err));
+    } finally {
+      if (sequence === searchSequenceRef.current) setLoading(false);
+    }
+  };
+
+  const handleInput = (value: string) => {
+    searchSequenceRef.current += 1;
+    setQuery(value);
+    setResults([]);
+    setError(null);
+    const hasQuery = Boolean(normalizeAnilistSearchQuery(value));
+    setLoading(hasQuery);
+    if (debounceRef.current) clearTimeout(debounceRef.current);
+    if (!hasQuery) return;
+    debounceRef.current = setTimeout(() => void doSearch(value), 400);
+  };
+
+  const handleSelect = async (media: StatsTmdbSearchResult) => {
+    setLinking(media.tmdbId);
+    setError(null);
+    try {
+      await apiClient.reassignAnimeTmdb(animeId, {
+        tmdbId: media.tmdbId,
+        tmdbType: media.tmdbType,
+      });
+      onLinked();
+    } catch (err) {
+      setError(describeLinkError(err));
+      setLinking(null);
+    }
+  };
+
+  // Dismissing mid-link would leave the caller unaware of a relink that is
+  // still going to land, so the backdrop and close button wait for it.
+  const handleDismiss = () => {
+    if (linking === null) onClose();
+  };
+
+  return (
+    <div
+      className="fixed inset-0 z-50 flex items-start justify-center pt-[10vh]"
+      onClick={handleDismiss}
+    >
+      <div className="absolute inset-0 bg-ctp-crust/70 backdrop-blur-[2px]" />
+      <div
+        className="relative bg-ctp-base border border-ctp-surface1 rounded-xl shadow-2xl w-full max-w-lg max-h-[70vh] flex flex-col animate-fade-in"
+        onClick={(e) => e.stopPropagation()}
+      >
+        <div className="p-4 border-b border-ctp-surface1">
+          <div className="flex items-center justify-between mb-3">
+            <h3 className="text-sm font-semibold text-ctp-text">Select TMDB Title</h3>
+            <button
+              type="button"
+              onClick={handleDismiss}
+              disabled={linking !== null}
+              className="text-ctp-overlay2 hover:text-ctp-text text-lg leading-none disabled:opacity-50"
+            >
+              {'✕'}
+            </button>
+          </div>
+          <input
+            ref={inputRef}
+            type="text"
+            value={query}
+            onChange={(e) => handleInput(e.target.value)}
+            placeholder="Search TMDB for a drama or movie..."
+            className="w-full bg-ctp-surface0 border border-ctp-surface1 rounded-lg px-3 py-2 text-sm text-ctp-text placeholder:text-ctp-overlay2 focus:outline-none focus:border-ctp-blue"
+          />
+        </div>
+
+        <div className="flex-1 overflow-y-auto p-2">
+          {loading && <div className="text-xs text-ctp-overlay2 p-3">Searching...</div>}
+          {error && <div className="text-xs text-ctp-red p-3">{error}</div>}
+          {!loading && !error && results.length === 0 && query.trim() && (
+            <div className="text-xs text-ctp-overlay2 p-3">No results</div>
+          )}
+          {results.map((media) => (
+            <button
+              key={`${media.tmdbType}-${media.tmdbId}`}
+              type="button"
+              disabled={linking !== null}
+              onClick={() => void handleSelect(media)}
+              className="w-full flex items-center gap-3 p-2.5 rounded-lg hover:bg-ctp-surface0 transition-colors text-left disabled:opacity-50"
+            >
+              {media.posterUrl ? (
+                <img
+                  src={media.posterUrl}
+                  alt=""
+                  className="w-10 h-14 rounded object-cover shrink-0 bg-ctp-surface1"
+                />
+              ) : (
+                <div className="w-10 h-14 rounded bg-ctp-surface1 shrink-0" />
+              )}
+              <div className="min-w-0 flex-1">
+                <div className="text-sm text-ctp-text truncate">{media.title}</div>
+                {media.originalTitle !== media.title && (
+                  <div className="text-xs text-ctp-subtext0 truncate">{media.originalTitle}</div>
+                )}
+                <div className="text-xs text-ctp-overlay2 mt-0.5">
+                  {media.tmdbType === 'movie' ? 'Movie' : 'TV'}
+                  {media.year ? ` · ${media.year}` : ''}
+                  {media.isAnimation ? ' · Animation' : ''}
+                </div>
+              </div>
+              {linking === media.tmdbId ? (
+                <span className="text-xs text-ctp-blue shrink-0">Linking...</span>
+              ) : (
+                <span className="text-xs text-ctp-overlay2 shrink-0">Select</span>
+              )}
+            </button>
+          ))}
+        </div>
+      </div>
+    </div>
+  );
+}
diff --git a/stats/src/components/vocabulary/WordDetailPanel.tsx b/stats/src/components/vocabulary/WordDetailPanel.tsx
index b44123b3..f1cd2ef4 100644
--- a/stats/src/components/vocabulary/WordDetailPanel.tsx
+++ b/stats/src/components/vocabulary/WordDetailPanel.tsx
@@ -1,7 +1,6 @@
 import { useRef, useState, useEffect } from 'react';
 import { useWordDetail } from '../../hooks/useWordDetail';
 import { apiClient } from '../../lib/api-client';
-import { assetUrl } from '../../lib/asset-url';
 import { epochMsFromDbTimestamp, formatNumber, formatRelativeDate } from '../../lib/formatters';
 import {
   buildStatsMineCardParams,
@@ -167,7 +166,7 @@ export function WordDetailPanel({
         if (typeof Notification !== 'undefined' && Notification.permission === 'granted') {
           new Notification('Anki Card Created', {
             body: `Mined: ${label}`,
-            icon: assetUrl('favicon.png'),
+            icon: '/favicon.png',
           });
         } else if (typeof Notification !== 'undefined' && Notification.permission !== 'denied') {
           Notification.requestPermission().then((p) => {
diff --git a/stats/src/lib/api-client.test.ts b/stats/src/lib/api-client.test.ts
index 0f6092ad..014e6bf9 100644
--- a/stats/src/lib/api-client.test.ts
+++ b/stats/src/lib/api-client.test.ts
@@ -1,36 +1,6 @@
 import assert from 'node:assert/strict';
 import test from 'node:test';
-import { apiClient, BASE_URL, resolveStatsBaseUrl } from './api-client';
-
-test('resolveStatsBaseUrl prefers apiBase query parameter for file-based overlay mode', () => {
-  const baseUrl = resolveStatsBaseUrl({
-    protocol: 'file:',
-    origin: 'null',
-    search: '?overlay=1&apiBase=http%3A%2F%2F127.0.0.1%3A6123',
-  });
-
-  assert.equal(baseUrl, 'http://127.0.0.1:6123');
-});
-
-test('resolveStatsBaseUrl falls back to configured window origin for browser mode', () => {
-  const baseUrl = resolveStatsBaseUrl({
-    protocol: 'http:',
-    origin: 'http://127.0.0.1:6123',
-    search: '',
-  });
-
-  assert.equal(baseUrl, 'http://127.0.0.1:6123');
-});
-
-test('resolveStatsBaseUrl keeps legacy localhost fallback for file mode without apiBase', () => {
-  const baseUrl = resolveStatsBaseUrl({
-    protocol: 'file:',
-    origin: 'null',
-    search: '?overlay=1',
-  });
-
-  assert.equal(baseUrl, 'http://127.0.0.1:6969');
-});
+import { apiClient, BASE_URL } from './api-client';
 
 test('getAnimeCoverUrl appends retry tokens for late cover refreshes', () => {
   const getAnimeCoverUrl = apiClient.getAnimeCoverUrl as (
@@ -38,10 +8,7 @@ test('getAnimeCoverUrl appends retry tokens for late cover refreshes', () => {
     retryToken?: number,
   ) => string;
 
-  assert.equal(
-    getAnimeCoverUrl(42, 3),
-    'http://127.0.0.1:6969/api/stats/anime/42/cover?coverRetry=3',
-  );
+  assert.equal(getAnimeCoverUrl(42, 3), `${BASE_URL}/api/stats/anime/42/cover?coverRetry=3`);
 });
 
 test('getAnimeMergeRecommendations loads pending duplicate pairs', async () => {
diff --git a/stats/src/lib/api-client.ts b/stats/src/lib/api-client.ts
index addf6ef6..3462d49c 100644
--- a/stats/src/lib/api-client.ts
+++ b/stats/src/lib/api-client.ts
@@ -15,6 +15,7 @@ import type {
   StatsMergeAnimeResponse,
   StatsMoveVideoRequest,
   StatsMoveVideoResponse,
+  StatsTmdbAssignment,
   StatsTrendGroupBy,
   StatsTrendRange,
   StatsVideoWatchedRequest,
@@ -23,24 +24,8 @@ import type { StatsMineCardParams, StatsMineCardResponse } from './mining';
 import { appendCoverRetryToken } from './cover-retry';
 import { trackDelete } from './delete-progress';
 
-type StatsLocationLike = Pick<Location, 'protocol' | 'origin' | 'search'>;
-
-export function resolveStatsBaseUrl(location?: StatsLocationLike): string {
-  const resolvedLocation =
-    location ??
-    (typeof window === 'undefined'
-      ? { protocol: 'file:', origin: 'null', search: '' }
-      : window.location);
-
-  const queryApiBase = new URLSearchParams(resolvedLocation.search).get('apiBase')?.trim();
-  if (queryApiBase) {
-    return queryApiBase;
-  }
-
-  return resolvedLocation.protocol === 'file:' ? 'http://127.0.0.1:6969' : resolvedLocation.origin;
-}
-
-export const BASE_URL = resolveStatsBaseUrl();
+// Both browser and in-app dashboards use the server that served the page.
+export const BASE_URL = typeof window === 'undefined' ? '' : window.location.origin;
 
 async function fetchResponse(path: string, init?: RequestInit): Promise<Response> {
   const res = await fetch(`${BASE_URL}${path}`, init);
@@ -256,6 +241,15 @@ export const apiClient = {
       body: JSON.stringify(info),
     });
   },
+  searchTmdb: (query: string) =>
+    fetchJson('tmdbSearch', `/api/stats/tmdb/search?q=${encodeURIComponent(query)}`),
+  reassignAnimeTmdb: async (animeId: number, info: StatsTmdbAssignment): Promise<void> => {
+    await fetchResponse(`/api/stats/anime/${animeId}/tmdb`, {
+      method: 'PATCH',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(info satisfies StatsTmdbAssignment),
+    });
+  },
   mineCard: async (params: StatsMineCardParams): Promise<StatsMineCardResponse> => {
     const res = await fetch(`${BASE_URL}/api/stats/mine-card?mode=${params.mode}`, {
       method: 'POST',
diff --git a/stats/src/lib/asset-url.test.ts b/stats/src/lib/asset-url.test.ts
deleted file mode 100644
index 399773ed..00000000
--- a/stats/src/lib/asset-url.test.ts
+++ /dev/null
@@ -1,39 +0,0 @@
-import assert from 'node:assert/strict';
-import test from 'node:test';
-import { assetUrl, resolveAssetUrl } from './asset-url';
-
-// vite.config.ts sets `base: './'`, so this is what the built bundle sees.
-const BUILT_BASE = './';
-
-test('built asset URLs are never root-absolute', () => {
-  assert.equal(resolveAssetUrl('favicon.png', BUILT_BASE).startsWith('/'), false);
-});
-
-test('built asset URL resolves next to a file:// index.html', () => {
-  const resolved = new URL(
-    resolveAssetUrl('favicon.png', BUILT_BASE),
-    'file:///opt/SubMiner/stats/dist/index.html',
-  );
-  assert.equal(resolved.href, 'file:///opt/SubMiner/stats/dist/favicon.png');
-});
-
-test('built asset URL resolves against the server root when served over http', () => {
-  const resolved = new URL(resolveAssetUrl('favicon.png', BUILT_BASE), 'http://127.0.0.1:8770/');
-  assert.equal(resolved.href, 'http://127.0.0.1:8770/favicon.png');
-});
-
-test('dev server base stays root-absolute', () => {
-  assert.equal(resolveAssetUrl('favicon.png', '/'), '/favicon.png');
-});
-
-test('a base without a trailing slash still joins cleanly', () => {
-  assert.equal(resolveAssetUrl('favicon.png', '/stats'), '/stats/favicon.png');
-});
-
-test('a leading slash in the requested path is tolerated', () => {
-  assert.equal(resolveAssetUrl('/favicon.png', BUILT_BASE), './favicon.png');
-});
-
-test('assetUrl falls back to a relative base outside a Vite bundle', () => {
-  assert.equal(assetUrl('favicon.png').startsWith('/'), false);
-});
diff --git a/stats/src/lib/asset-url.ts b/stats/src/lib/asset-url.ts
deleted file mode 100644
index 9a8e8d2f..00000000
--- a/stats/src/lib/asset-url.ts
+++ /dev/null
@@ -1,24 +0,0 @@
-/**
- * Resolve a bundled public asset against Vite's base URL.
- *
- * The in-player stats window is loaded with `loadFile`, so the document lives on
- * `file://`. A root-absolute path like `/favicon.png` resolves to the filesystem
- * root there and 404s, while the HTTP-served web app resolves it fine. Vite
- * rewrites asset refs in `index.html` but not string literals in JSX, so build
- * the URL from the configured base instead of hardcoding a leading slash.
- */
-export function resolveAssetUrl(path: string, base: string): string {
-  const normalizedBase = base.endsWith('/') ? base : `${base}/`;
-  return `${normalizedBase}${path.replace(/^\/+/, '')}`;
-}
-
-function currentBase(): string {
-  // Vite injects BASE_URL at build time ('./' per vite.config.ts) and serves '/'
-  // in dev. Outside a Vite bundle (tests) there is no env, so fall back to './'.
-  const env = (import.meta as { env?: Record<string, string | undefined> }).env;
-  return env?.BASE_URL || './';
-}
-
-export function assetUrl(path: string): string {
-  return resolveAssetUrl(path, currentBase());
-}
diff --git a/stats/src/lib/media-library-grouping.test.tsx b/stats/src/lib/media-library-grouping.test.tsx
index e57edf04..11448581 100644
--- a/stats/src/lib/media-library-grouping.test.tsx
+++ b/stats/src/lib/media-library-grouping.test.tsx
@@ -169,14 +169,14 @@ test('CoverImage renders explicit remote artwork when src is provided', () => {
 test('MediaCard uses the proxied cover endpoint instead of metadata artwork urls', () => {
   const markup = renderToStaticMarkup(<MediaCard item={youtubeEpisodeA} onClick={() => {}} />);
 
-  assert.match(markup, /src="http:\/\/127\.0\.0\.1:6969\/api\/stats\/media\/1\/cover"/);
+  assert.match(markup, /src="\/api\/stats\/media\/1\/cover"/);
   assert.doesNotMatch(markup, /https:\/\/i\.ytimg\.com\/vi\/yt-1\/hqdefault\.jpg/);
 });
 
 test('resolveMediaCoverApiUrl appends retry tokens for late cover refreshes', () => {
   assert.equal(
     resolveMediaCoverApiUrl(youtubeEpisodeA.videoId, 2),
-    'http://127.0.0.1:6969/api/stats/media/1/cover?coverRetry=2',
+    '/api/stats/media/1/cover?coverRetry=2',
   );
 });
 
diff --git a/stats/src/lib/yomitan-lookup.test.tsx b/stats/src/lib/yomitan-lookup.test.tsx
index 145f39d2..dac82c36 100644
--- a/stats/src/lib/yomitan-lookup.test.tsx
+++ b/stats/src/lib/yomitan-lookup.test.tsx
@@ -116,7 +116,10 @@ test('AnimeOverviewStats renders aggregate Yomitan lookup metrics', () => {
       detail={{
         animeId: 1,
         canonicalTitle: 'Anime',
+        mediaKind: 'anime',
         anilistId: null,
+        tmdbId: null,
+        tmdbType: null,
         titleRomaji: null,
         titleEnglish: null,
         titleNative: null,
diff --git a/vendor/subminer-yomitan b/vendor/subminer-yomitan
index 99d6bf85..57516d3b 160000
--- a/vendor/subminer-yomitan
+++ b/vendor/subminer-yomitan
@@ -1 +1 @@
-Subproject commit 99d6bf853ccf94f10114df5834d5abc68bc8ab55
+Subproject commit 57516d3b7f3bffa604f575026cd39390067137ce