fix(subtitles): suppress overlay duplicates and reset ASS cleanup

- Suppress overlapping decorative karaoke and shadow layer copies - Clear stale ASS-only fallback sanitization after source refresh failures
fix(subtitles): recover positioned word gaps in reconstructed translations
2026-08-24 00:15:26 -07:00 · 2026-08-23 23:02:44 -07:00 · 2026-08-23 21:37:48 -07:00 · 2026-08-23 21:11:51 -07:00 · 2026-08-23 21:00:43 -07:00 · 2026-08-23 20:45:30 -07:00
143 changed files with 5501 additions and 1208 deletions
@@ -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.
@@ -32,9 +32,11 @@ jobs:
      - name: Guard stable docs tag shape
        id: tag_guard
        if: github.ref_type == 'tag'
+        env:
+          TAG_NAME: ${{ github.ref_name }}
        run: |
-          if [[ ! "${{ github.ref_name }}" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
-            echo "::notice::Skipping non-stable docs tag ${{ github.ref_name }}"
+          if [[ ! "$TAG_NAME" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+            echo "::notice::Skipping non-stable docs tag $TAG_NAME"
            echo "stable_tag=false" >> "$GITHUB_OUTPUT"
            exit 0
          fi
@@ -274,7 +274,8 @@ jobs:
            config.example.jsonc \
            plugin/subminer \
            plugin/subminer.conf \
-            assets/themes/subminer.rasi
+            assets/themes/subminer.rasi \
+            assets/thumbnailers/subminer-ffmpegthumbnailer.thumbnailer

      - name: Generate checksums
        run: |
@@ -296,15 +297,22 @@ jobs:
        run: echo "VERSION=${GITHUB_REF#refs/tags/}" >> "$GITHUB_OUTPUT"

      - name: Verify committed prerelease notes
+        env:
+          RELEASE_VERSION: ${{ steps.version.outputs.VERSION }}
        run: |
          if [ ! -s release/prerelease-notes.md ]; then
            echo "::error::release/prerelease-notes.md is missing or empty. Run 'bun run changelog:prerelease-notes --version <version>' locally and commit the file before tagging."
            exit 1
          fi
+          if ! bun run changelog:check-prerelease-notes --version "$RELEASE_VERSION"; then
+            echo "::error::release/prerelease-notes.md was not generated for $RELEASE_VERSION. Rerun 'bun run changelog:prerelease-notes --version $RELEASE_VERSION' locally, commit, and retag."
+            exit 1
+          fi

      - name: Publish Prerelease
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          RELEASE_VERSION: ${{ steps.version.outputs.VERSION }}
        run: |
          set -euo pipefail

@@ -326,27 +334,27 @@ jobs:
            exit 1
          fi

-          if gh release view "${{ steps.version.outputs.VERSION }}" >/dev/null 2>&1; then
-            gh release edit "${{ steps.version.outputs.VERSION }}" \
+          if gh release view "$RELEASE_VERSION" >/dev/null 2>&1; then
+            gh release edit "$RELEASE_VERSION" \
              --draft \
              --prerelease \
-              --title "${{ steps.version.outputs.VERSION }}" \
+              --title "$RELEASE_VERSION" \
              --notes-file release/prerelease-notes.md
          else
-            gh release create "${{ steps.version.outputs.VERSION }}" \
+            gh release create "$RELEASE_VERSION" \
              --draft \
              --latest=false \
              --prerelease \
-              --title "${{ steps.version.outputs.VERSION }}" \
+              --title "$RELEASE_VERSION" \
              --notes-file release/prerelease-notes.md
          fi

          for asset in "${artifacts[@]}"; do
-            gh release upload "${{ steps.version.outputs.VERSION }}" "$asset" --clobber
+            gh release upload "$RELEASE_VERSION" "$asset" --clobber
          done

-          gh release edit "${{ steps.version.outputs.VERSION }}" \
+          gh release edit "$RELEASE_VERSION" \
            --draft=false \
            --prerelease \
-            --title "${{ steps.version.outputs.VERSION }}" \
+            --title "$RELEASE_VERSION" \
            --notes-file release/prerelease-notes.md
@@ -273,7 +273,8 @@ jobs:
            config.example.jsonc \
            plugin/subminer \
            plugin/subminer.conf \
-            assets/themes/subminer.rasi
+            assets/themes/subminer.rasi \
+            assets/thumbnailers/subminer-ffmpegthumbnailer.thumbnailer

      - name: Generate checksums
        run: |
@@ -295,33 +296,40 @@ jobs:
        run: echo "VERSION=${GITHUB_REF#refs/tags/}" >> "$GITHUB_OUTPUT"

      - name: Guard against pending changelog fragments
+        env:
+          RELEASE_VERSION: ${{ steps.version.outputs.VERSION }}
        run: |
          if find changes -maxdepth 1 -name '*.md' -not -name README.md -print -quit | grep -q .; then
-            echo "::error::Pending changelog fragments detected. Run 'bun run changelog:build --version ${{ steps.version.outputs.VERSION }}' locally and commit the polished CHANGELOG.md before tagging. CI no longer auto-builds the changelog because the polish step requires the local 'claude' CLI."
+            echo "::error::Pending changelog fragments detected. Run 'bun run changelog:build --version $RELEASE_VERSION' locally and commit the polished CHANGELOG.md before tagging. CI no longer auto-builds the changelog because the polish step requires the local 'claude' CLI."
            exit 1
          fi

      - name: Verify changelog is ready for tagged release
-        run: bun run changelog:check --version "${{ steps.version.outputs.VERSION }}"
+        env:
+          RELEASE_VERSION: ${{ steps.version.outputs.VERSION }}
+        run: bun run changelog:check --version "$RELEASE_VERSION"

      - name: Generate release notes from changelog
-        run: bun run changelog:release-notes --version "${{ steps.version.outputs.VERSION }}"
+        env:
+          RELEASE_VERSION: ${{ steps.version.outputs.VERSION }}
+        run: bun run changelog:release-notes --version "$RELEASE_VERSION"

      - name: Publish Release
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          RELEASE_VERSION: ${{ steps.version.outputs.VERSION }}
        run: |
          set -euo pipefail

-          if gh release view "${{ steps.version.outputs.VERSION }}" >/dev/null 2>&1; then
+          if gh release view "$RELEASE_VERSION" >/dev/null 2>&1; then
            # Do not pass the prerelease flag here; gh defaults to a normal release.
-            gh release edit "${{ steps.version.outputs.VERSION }}" \
+            gh release edit "$RELEASE_VERSION" \
              --draft=false \
-              --title "${{ steps.version.outputs.VERSION }}" \
+              --title "$RELEASE_VERSION" \
              --notes-file release/release-notes.md
          else
-            gh release create "${{ steps.version.outputs.VERSION }}" \
-              --title "${{ steps.version.outputs.VERSION }}" \
+            gh release create "$RELEASE_VERSION" \
+              --title "$RELEASE_VERSION" \
              --notes-file release/release-notes.md
          fi

@@ -344,7 +352,7 @@ jobs:
          fi

          for asset in "${artifacts[@]}"; do
-            gh release upload "${{ steps.version.outputs.VERSION }}" "$asset" --clobber
+            gh release upload "$RELEASE_VERSION" "$asset" --clobber
          done

  aur-publish:
@@ -420,9 +428,10 @@ jobs:
        if: steps.aur_prereqs.outputs.skip != 'true' && steps.aur_ssh.outputs.skip != 'true' && steps.aur_clone.outputs.skip != 'true'
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          RELEASE_VERSION: ${{ steps.version.outputs.VERSION }}
        run: |
          set -euo pipefail
-          version="${{ steps.version.outputs.VERSION }}"
+          version="$RELEASE_VERSION"
          install -dm755 .tmp/aur-release-assets
          gh release download "$version" \
            --dir .tmp/aur-release-assets \
@@ -432,15 +441,17 @@ jobs:

      - name: Update AUR packaging metadata
        if: steps.aur_prereqs.outputs.skip != 'true' && steps.aur_ssh.outputs.skip != 'true' && steps.aur_clone.outputs.skip != 'true'
+        env:
+          RELEASE_VERSION: ${{ steps.version.outputs.VERSION }}
        run: |
          set -euo pipefail
-          version_no_v="${{ steps.version.outputs.VERSION }}"
+          version_no_v="$RELEASE_VERSION"
          version_no_v="${version_no_v#v}"
          cp packaging/aur/subminer-bin/PKGBUILD aur-subminer-bin/PKGBUILD
          cp packaging/aur/subminer-bin/.SRCINFO aur-subminer-bin/.SRCINFO
          bash scripts/update-aur-package.sh \
            --pkg-dir aur-subminer-bin \
-            --version "${{ steps.version.outputs.VERSION }}" \
+            --version "$RELEASE_VERSION" \
            --appimage ".tmp/aur-release-assets/SubMiner-${version_no_v}.AppImage" \
            --wrapper ".tmp/aur-release-assets/subminer" \
            --assets ".tmp/aur-release-assets/subminer-assets.tar.gz"
@@ -450,6 +461,7 @@ jobs:
        working-directory: aur-subminer-bin
        env:
          GIT_SSH_COMMAND: ssh -i ~/.ssh/aur -o IdentitiesOnly=yes
+          RELEASE_VERSION: ${{ steps.version.outputs.VERSION }}
        run: |
          set -euo pipefail
          if git diff --quiet -- PKGBUILD .SRCINFO; then
@@ -459,7 +471,7 @@ jobs:
          git config user.name "github-actions[bot]"
          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
          git add PKGBUILD .SRCINFO
-          git commit -m "Update to ${{ steps.version.outputs.VERSION }}"
+          git commit -m "Update to $RELEASE_VERSION"

          attempts=3
          for attempt in $(seq 1 "$attempts"); do
@@ -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
@@ -2,8 +2,10 @@

 APP_NAME := subminer
 THEME_SOURCE := assets/themes/subminer.rasi
+THUMBNAILER_SOURCE := assets/thumbnailers/subminer-ffmpegthumbnailer.thumbnailer
 LAUNCHER_OUT := dist/launcher/$(APP_NAME)
 THEME_FILE := subminer.rasi
+THUMBNAILER_FILE := subminer-ffmpegthumbnailer.thumbnailer

 # Default install prefix for the wrapper script.
 PREFIX ?= $(HOME)/.local
@@ -221,11 +223,13 @@ docs-dev: ensure-bun


 install-linux: build-launcher
-	@printf '%s\n' "[INFO] Installing Linux wrapper/theme artifacts"
+	@printf '%s\n' "[INFO] Installing Linux wrapper/support artifacts"
 	@install -d "$(BINDIR)"
 	@install -m 0755 "$(LAUNCHER_OUT)" "$(BINDIR)/$(APP_NAME)"
 	@install -d "$(LINUX_DATA_DIR)/themes"
 	@install -m 0644 "./$(THEME_SOURCE)" "$(LINUX_DATA_DIR)/themes/$(THEME_FILE)"
+	@install -d "$(LINUX_DATA_DIR)/thumbnailers"
+	@install -m 0644 "./$(THUMBNAILER_SOURCE)" "$(LINUX_DATA_DIR)/thumbnailers/$(THUMBNAILER_FILE)"
 	@install -d "$(LINUX_DATA_DIR)/plugin/subminer"
 	@cp -R ./plugin/subminer/. "$(LINUX_DATA_DIR)/plugin/subminer/"
 	@if [ -n "$(APPIMAGE_SRC)" ]; then \
@@ -234,7 +238,7 @@ install-linux: build-launcher
 		printf '%s\n' "[WARN] No release/SubMiner-*.AppImage found; skipping AppImage install"; \
 		printf '%s\n' "       Build one with: make build"; \
 	fi
-	@printf '%s\n' "Installed to:" "  $(BINDIR)/subminer" "  $(LINUX_DATA_DIR)/themes/$(THEME_FILE)"
+	@printf '%s\n' "Installed to:" "  $(BINDIR)/subminer" "  $(LINUX_DATA_DIR)/themes/$(THEME_FILE)" "  $(LINUX_DATA_DIR)/thumbnailers/$(THUMBNAILER_FILE)"

 install-macos: build-launcher
 	@printf '%s\n' "[INFO] Installing macOS wrapper/theme/app artifacts"
@@ -275,8 +279,9 @@ uninstall:
 uninstall-linux:
 	@rm -f "$(BINDIR)/subminer" "$(BINDIR)/SubMiner.AppImage"
 	@rm -f "$(LINUX_DATA_DIR)/themes/$(THEME_FILE)"
+	@rm -f "$(LINUX_DATA_DIR)/thumbnailers/$(THUMBNAILER_FILE)"
 	@rm -rf "$(LINUX_DATA_DIR)/plugin/subminer"
-	@printf '%s\n' "Removed:" "  $(BINDIR)/subminer" "  $(BINDIR)/SubMiner.AppImage" "  $(LINUX_DATA_DIR)/themes/$(THEME_FILE)" "  $(LINUX_DATA_DIR)/plugin/subminer"
+	@printf '%s\n' "Removed:" "  $(BINDIR)/subminer" "  $(BINDIR)/SubMiner.AppImage" "  $(LINUX_DATA_DIR)/themes/$(THEME_FILE)" "  $(LINUX_DATA_DIR)/thumbnailers/$(THUMBNAILER_FILE)" "  $(LINUX_DATA_DIR)/plugin/subminer"

 uninstall-macos:
 	@rm -f "$(BINDIR)/subminer"
@@ -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>

@@ -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;
@@ -20,7 +20,7 @@
      "devDependencies": {
        "@types/node": "^24.10.0",
        "@types/ws": "^8.18.1",
-        "electron": "43.4.1",
+        "electron": "42.6.0",
        "electron-builder": "26.15.3",
        "esbuild": "^0.25.12",
        "eslint": "^10.8.0",
@@ -346,7 +346,7 @@

    "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@42.6.0", "", { "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-axGNgd+yCTg+vi1VEGrQqAj9WVWkePKwbICSAvMiT2eTaxhij9a/xhBHD6rXV8wrlW9ZfJzE5+xg752ImxrmTw=="],

    "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=="],

@@ -49,6 +49,7 @@ How fragments turn into a release:
 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
@@ -1,5 +1,5 @@
 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.
+- 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. Dense visual grids (sign walls, countdown frames, scattered glyph typesetting) stay out of the published text, while multi-row CC-style dialogue blocks and wrapped lyric rows are still published. Decorative letters that lyric effects render in symbol fonts over the syllables are dropped with the animation instead of corrupting the reconstructed line or leaking as stray cues. Karaoke highlight sweeps that repaint one syllable at a time over an already-visible lyric are suppressed instead of surfacing as rolling partial copies or lone flickering syllables beside the line, and drop-shadow glyph copies offset a few pixels from their base no longer double every syllable in the reconstructed lyric. Positioned word gaps are also recovered on lines where a single fragment carries a literal space, and between wide syllable chunks whose word gap is hidden by their own width, so reconstructed translations keep their spacing instead of running words together.
 - 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.
@@ -0,0 +1,5 @@
+type: fixed
+area: character dictionary
+
+- Reuse character dictionaries after MeCab completes without finding any name splits instead of regenerating character data and portraits on every launch.
+- Restore inline character portraits when a cached portrait index finishes loading after subtitles have already been tokenized.
@@ -0,0 +1,5 @@
+type: fixed
+area: subtitles
+
+- Embedded subtitle tracks on network-mounted (SMB/NFS) media are extracted and parsed again, restoring full karaoke reconstruction, sidebar cues, and mining for releases that ship subtitles only inside the container. Extraction reads the whole file once per episode (roughly 10 seconds per GB on gigabit), its timeout now accommodates large Bluray remuxes, and duplicate extraction requests share one ffmpeg process. Only true remote URLs keep the live-text-only path.
+- Live subtitle text from per-glyph typeset karaoke no longer shows a wall of scattered letters in the overlays while extraction is still running or when no parsed cues exist (remote URLs, unreadable sources); the glyph wall and its typed-syllable fragments are suppressed while concurrent dialogue lines remain.
@@ -1,6 +0,0 @@
-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.
- 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.
@@ -0,0 +1,4 @@
+type: fixed
+area: overlay
+
+- The macOS window-tracking helper is now built for macOS 12.0+, so the overlay attaches to mpv on older systems (previously the helper required the macOS version of the build machine and crashed on e.g. Ventura, leaving the overlay stuck on "Overlay loading").
@@ -1,4 +1,4 @@
 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.
+- Primary and secondary ASS subtitles now collapse layered and whitespace variants of full-span lyrics, including when playback starts or seeks into a line, reconstruct fragment-only karaoke per style, preserve authored stack order, keep canonical signs visible for their complete generated animation, navigate song lyrics by sanitized lines instead of generated animation events, and keep sidebar selections on the requested overlapping lyric while preserving unmatched dialogue and signs.
@@ -1,4 +1,4 @@
 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.
+- 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. Fragmented ASS karaoke keeps spaces authored at event boundaries and recovers Latin word spaces encoded only by positioned fragment gaps, including word gaps measured across wide glyphs that width normalization alone reads as ordinary letter advances. Progressive karaoke highlights, offset shadow copies, and overlapping decorative glyphs remain suppressed. Long ASS lines repeated as dialogue and positioned signs are also collapsed when they differ only in whitespace or terminal punctuation. Dense multi-row sign layouts no longer become concatenated primary or secondary lines. Live mpv text remains the fallback for unreadable tracks and applies full-line duplicate filtering before display. A failed source refresh also clears ASS-only cleanup so fallback text from other formats stays intact.
@@ -0,0 +1,4 @@
+type: fixed
+area: stats
+
+- Immersion statistics storage now applies its SQLite busy timeout before WAL setup, avoiding transient database-lock failures when worker connections overlap.
@@ -1,4 +0,0 @@
-type: docs
-area: documentation
-
- Hid the unfinished feature demos page from the documentation sidebar while keeping its direct URL available.
@@ -0,0 +1,5 @@
+type: changed
+area: release
+
+- Prerelease notes now open with a "Changes since" section that lists only what changed compared to the previous beta/RC of the same version, above the cumulative highlights.
+- CI now rejects prerelease tags whose committed notes were generated for a different beta/RC, instead of silently shipping stale notes.
@@ -0,0 +1,4 @@
+type: fixed
+area: overlay
+
+- Secondary subtitle overlays now show every rendered line instead of clipping text after roughly four lines.
@@ -0,0 +1,4 @@
+type: fixed
+area: launcher
+
+- Fixed missing MKV thumbnails in the Linux rofi picker when system thumbnailer registrations only advertise legacy Matroska MIME aliases.
@@ -5,7 +5,7 @@ Short recordings of SubMiner's key features and integrations from real playback
 <script setup>
 import { withBase } from 'vitepress';

-const v = '20260301-1';
+const v = '20260819-1';
 </script>

 ## Anki Card Mining & Enrichment
@@ -6,7 +6,7 @@ For internal architecture/workflow guidance, use `docs/README.md` at the repo ro

 - [Bun](https://bun.sh)
 - A system `lua` interpreter for `bun run test:launcher` / `bun run test:plugin:src`
- macOS builds compile a Swift helper via `scripts/build-macos-helper.sh` (skip with `SUBMINER_SKIP_MACOS_HELPER_BUILD=1`)
+- macOS builds compile a Swift helper via `scripts/prepare-build-assets.mjs` (skip with `SUBMINER_SKIP_MACOS_HELPER_BUILD=1`)

 ## Setup

@@ -64,10 +64,6 @@ make dev-watch                                # watch TS + renderer and launch E
 make dev-watch-macos                          # same as dev-watch, forcing --backend macos
 ```

-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.
-
 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:
@@ -88,7 +88,7 @@ features:
 <script setup>
 import { withBase } from 'vitepress';

-const demoAssetVersion = '20260223-2';
+const demoAssetVersion = '20260819-1';
 </script>

 <div class="landing-shell">
@@ -392,7 +392,7 @@ subminer -u
 subminer --update
 ```

-SubMiner verifies AppImage, launcher, and Linux support-asset downloads against `SHA256SUMS.txt`. On Linux those support assets include the launcher-managed runtime plugin copy under `SubMiner/plugin/subminer` plus the rofi theme at `SubMiner/themes/subminer.rasi`. If the binary is in a protected path, SubMiner shows the exact command to run rather than elevating itself.
+SubMiner verifies AppImage, launcher, and Linux support-asset downloads against `SHA256SUMS.txt`. On Linux those support assets include the launcher-managed runtime plugin copy under `SubMiner/plugin/subminer`, the rofi theme at `SubMiner/themes/subminer.rasi`, and the scoped Matroska thumbnailer registration under `SubMiner/thumbnailers`. If the binary is in a protected path, SubMiner shows the exact command to run rather than elevating itself.

 The tray "Check for Updates" entry installs the new app automatically on Linux, macOS, and Windows. On Linux it replaces the running `.AppImage` in place via `electron-updater` and refreshes the managed support assets from `subminer-assets.tar.gz`; AppImages managed by a system package (for example the AUR `/opt/SubMiner/SubMiner.AppImage`) are skipped so the package manager stays in charge.

@@ -404,7 +404,7 @@ SubMiner is an overlay that sits on top of mpv. It connects to mpv through an IP

 The `subminer` launcher handles mpv IPC socket setup automatically. If you launch mpv yourself or from another tool, you must pass `--input-ipc-server=/tmp/subminer-socket` (or `\\.\pipe\subminer-socket` on Windows) - without it the overlay starts but subtitles won't appear.

-The bundled mpv plugin is injected at runtime automatically - you don't need to install it separately. On Linux, the `subminer` launcher now checks for its managed runtime plugin copy and rofi theme before every mpv-managed launch and installs those support assets from the bundled app automatically if either one is missing. It provides in-player keybindings (the `y` chord) for controlling the overlay from within mpv. See [MPV Plugin](/mpv-plugin) for the full keybinding and configuration reference.
+The bundled mpv plugin is injected at runtime automatically - you don't need to install it separately. On Linux, the `subminer` launcher checks for its managed runtime plugin copy, rofi theme, and scoped thumbnailer registration before every mpv-managed launch and installs those support assets from the bundled app automatically if one is missing. For a rofi picker launch, this check runs before the picker opens. It provides in-player keybindings (the `y` chord) for controlling the overlay from within mpv. See [MPV Plugin](/mpv-plugin) for the full keybinding and configuration reference.

 ## Platform Notes

@@ -456,18 +456,20 @@ sudo chmod +x /usr/local/bin/subminer

 ### Linux Support Assets

-SubMiner ships the Linux rofi theme plus the launcher-managed runtime plugin copy in `subminer-assets.tar.gz`:
+SubMiner ships the Linux rofi theme, scoped Matroska thumbnailer registration, and launcher-managed runtime plugin copy in `subminer-assets.tar.gz`:

 ```bash
 wget https://github.com/ksyasuda/SubMiner/releases/latest/download/subminer-assets.tar.gz -O /tmp/subminer-assets.tar.gz
 tar -xzf /tmp/subminer-assets.tar.gz -C /tmp
 mkdir -p ~/.local/share/SubMiner/themes
 cp /tmp/assets/themes/subminer.rasi ~/.local/share/SubMiner/themes/subminer.rasi
+mkdir -p ~/.local/share/SubMiner/thumbnailers
+cp /tmp/assets/thumbnailers/subminer-ffmpegthumbnailer.thumbnailer ~/.local/share/SubMiner/thumbnailers/
 mkdir -p ~/.local/share/SubMiner/plugin
 cp -R /tmp/plugin/subminer ~/.local/share/SubMiner/plugin/subminer
 ```

-`subminer -u` and the tray updater keep those Linux support assets in sync automatically once the `SubMiner` data dir exists. Normal Linux launcher playback also auto-installs the managed runtime plugin copy and rofi theme from the bundled app if either support asset is missing, so manual extraction is mainly useful for pre-seeding or custom setups.
+`subminer -u` and the tray updater keep those Linux support assets in sync automatically once the `SubMiner` data dir exists. Normal Linux launcher playback also auto-installs all three assets from the bundled app if one is missing, so manual extraction is mainly useful for pre-seeding or custom setups. Rofi receives the SubMiner data path through its process-local `XDG_DATA_DIRS`, so the thumbnailer registration does not change the desktop-wide configuration.

 Override the theme path with `SUBMINER_ROFI_THEME=/absolute/path/to/theme.rasi`.

@@ -34,18 +34,22 @@ subminer -R -r -d ~/Anime              # rofi picker, recursive
 subminer -R /directory                 # rofi picker, directory shortcut
 ```

-rofi shows a GUI menu with icon thumbnails when available. SubMiner ships the rofi theme plus the Linux launcher-managed runtime plugin copy in the release assets tarball:
+rofi shows a GUI menu with icon thumbnails when available. SubMiner ships the rofi theme, a scoped `ffmpegthumbnailer` MIME registration, and the Linux launcher-managed runtime plugin copy in the release assets tarball:

 ```bash
 wget https://github.com/ksyasuda/SubMiner/releases/latest/download/subminer-assets.tar.gz -O /tmp/subminer-assets.tar.gz
 tar -xzf /tmp/subminer-assets.tar.gz -C /tmp
 mkdir -p ~/.local/share/SubMiner/themes
 cp /tmp/assets/themes/subminer.rasi ~/.local/share/SubMiner/themes/subminer.rasi
+mkdir -p ~/.local/share/SubMiner/thumbnailers
+cp /tmp/assets/thumbnailers/subminer-ffmpegthumbnailer.thumbnailer ~/.local/share/SubMiner/thumbnailers/
 mkdir -p ~/.local/share/SubMiner/plugin
 cp -R /tmp/plugin/subminer ~/.local/share/SubMiner/plugin/subminer
 ```

-Once the `SubMiner` data dir exists, `subminer -u` refreshes both assets automatically. Normal Linux launcher playback also checks for the managed runtime plugin copy and rofi theme before mpv launch and installs them from the bundled app automatically if either one is missing.
+Once the `SubMiner` data dir exists, `subminer -u` refreshes these assets automatically. Normal Linux launcher playback checks for all three assets and installs them from the bundled app when one is missing. For `subminer -R`, this repair runs before rofi opens.
+
+When `ffmpegthumbnailer` is installed, SubMiner prepends its own data directory to `XDG_DATA_DIRS` for the rofi process only. This lets rofi recognize the canonical Matroska MIME types used by newer GLib versions without changing the desktop-wide MIME or thumbnailer configuration. An existing registration in your own `$XDG_DATA_HOME/thumbnailers` still takes priority.

 The theme is auto-detected from these paths (first match wins):

@@ -108,8 +108,12 @@ The secondary bar is a compact top-strip region in the same overlay window. It s
 - Quick comprehension checks without leaving the mining flow.
 - Auto-populating the translation field on mined cards - when a card is created, SubMiner uses the secondary subtitle text as the translation field value (unless AI translation is configured to override it).

+For local media, SubMiner can parse supported embedded secondary tracks into timed cues. For remote URLs and files on network mounts, it uses mpv's live secondary subtitle text instead of scanning the media with ffmpeg.
+
 It is controlled by `secondarySub` configuration and shares its lifecycle with the main overlay window. Cycle which track feeds it with `Shift+J`.

+SubMiner collapses duplicate ASS layers in parsed secondary tracks. Exact repeated lines collapse at any length, while distinct simultaneous short lines remain separate. Long dialogue and positioned-sign copies also collapse when they differ only in whitespace or terminal punctuation. Dense multi-row sign layouts, such as translated timetables, are excluded instead of being concatenated into the secondary bar.
+
 ### Display Modes

 Both the primary and secondary subtitle bars share the same three visibility modes, and each can be changed independently at runtime:
@@ -9,7 +9,7 @@ The sidebar is enabled by default. Set `subtitleSidebar.enabled` to `false` if y
 When SubMiner parses the active subtitle source into a cue list, the sidebar becomes available. Toggle it with the `\` key (configurable via `subtitleSidebar.toggleKey`). While open:

 - The active cue is highlighted and kept in view as playback advances (when `autoScroll` is `true`).
- Clicking any cue seeks mpv to that timestamp.
+- Clicking any cue seeks mpv into that line. For overlapping ASS karaoke, SubMiner moves past the previous line's exit animation when the selected cue has enough time remaining.
 - The sidebar stays synchronized with the overlay - media transitions and subtitle source changes update both simultaneously.

 For typeset ASS karaoke and animated signs, SubMiner collapses generated animation frames and repeated full-line color phases before they reach the sidebar. It recovers a clean complete line from a matching timed authoring comment or from full-line events surrounding generated fragments. Ordinary ASS comments, editor notes, alternate lines, repeated dialogue, and separately positioned signs remain distinct.
@@ -109,14 +109,6 @@ If the overlay position is slightly off, right-click and drag on subtitle text t

 If you haven't set up dictionaries yet, see [Yomitan setup](/usage#yomitan-setup) first.

-**"Electron downgrade blocked" or "Unsupported Electron runtime"**
-
-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.
-
-**"Yomitan reported zero dictionaries after previously reporting ..."**
-
-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.
-
 **"Yomitan extension not found in any search path"**

 SubMiner bundles Yomitan and searches for it in these locations (in order):
@@ -155,7 +155,6 @@ The tray menu also includes `View Changelog`, which opens the in-app changelog m

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

@@ -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.

@@ -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();
@@ -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;
  }
@@ -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']);
+});
@@ -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,
@@ -36,6 +36,11 @@ test('runUpdateCommand updates directly on Linux without launching Electron', as
        launcher: { status: 'updated' },
        supportAssets: [
          { status: 'updated', component: 'theme', message: 'Installed theme.' },
+          {
+            status: 'updated',
+            component: 'thumbnailer',
+            message: 'Installed rofi thumbnailer.',
+          },
          { status: 'skipped', component: 'plugin', message: 'Plugin already up to date.' },
        ],
      };
@@ -52,6 +57,7 @@ test('runUpdateCommand updates directly on Linux without launching Electron', as
    'info:AppImage update: updated',
    'info:Launcher update: updated',
    'info:Support assets (theme) update: updated - Installed theme.',
+    'info:Support assets (thumbnailer) update: updated - Installed rofi thumbnailer.',
    'info:Support assets (plugin) update: skipped - Plugin already up to date.',
  ]);
 });
@@ -21,7 +21,10 @@ import {
  parseSha256Sums,
  type FetchLike,
 } from '../../src/main/runtime/update/release-assets.js';
-import { updateSupportAssetsFromRelease } from '../../src/main/runtime/update/support-assets.js';
+import {
+  updateSupportAssetsFromRelease,
+  type SupportAssetsUpdateResult,
+} from '../../src/main/runtime/update/support-assets.js';

 type UpdateCommandResponse = {
  ok: boolean;
@@ -36,15 +39,14 @@ type DirectReleaseUpdateRequest = {
  channel: UpdateChannel;
 };

+type DirectSupportAssetsUpdateResult = Omit<SupportAssetsUpdateResult, 'status'> & {
+  status: string;
+};
+
 type DirectReleaseUpdateResult = {
  appImage: { status: string; command?: string; message?: string };
  launcher: { status: string; command?: string; message?: string };
-  supportAssets: Array<{
-    status: string;
-    component?: 'theme' | 'plugin';
-    command?: string;
-    message?: string;
-  }>;
+  supportAssets: DirectSupportAssetsUpdateResult[];
 };

 type UpdateCommandDeps = {
@@ -129,12 +131,7 @@ function readUpdateChannel(root: Record<string, unknown> | null): UpdateChannel

 function logUpdateResult(
  label: string,
-  result: {
-    status: string;
-    component?: 'theme' | 'plugin';
-    command?: string;
-    message?: string;
-  },
+  result: DirectSupportAssetsUpdateResult,
  configuredLogLevel: NonNullable<LauncherCommandContext['args']['logLevel']>,
  deps: Pick<UpdateCommandDeps, 'log'>,
 ): void {
@@ -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"
@@ -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`,
+  );
+});
@@ -159,6 +159,9 @@ interface RofiIconEntry {
  iconPath?: string;
 }

+const ROFI_THUMBNAILER_FILE = 'subminer-ffmpegthumbnailer.thumbnailer';
+const DEFAULT_XDG_DATA_DIRS = ['/usr/local/share', '/usr/share'];
+
 function showRofiIconMenu(
  entries: RofiIconEntry[],
  prompt: string,
@@ -389,6 +392,47 @@ export function findRofiTheme(scriptPath: string): string | null {
  return null;
 }

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

@@ -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);
@@ -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,
+        );
      }
    });
  },
@@ -2,7 +2,7 @@
  "name": "subminer",
  "productName": "SubMiner",
  "desktopName": "SubMiner.desktop",
-  "version": "0.19.4-beta.1",
+  "version": "0.19.4-beta.4",
  "description": "All-in-one sentence mining overlay with AnkiConnect and dictionary integration",
  "packageManager": "bun@1.3.5",
  "main": "dist/main-entry.js",
@@ -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",
@@ -125,7 +126,7 @@
  "devDependencies": {
    "@types/node": "^24.10.0",
    "@types/ws": "^8.18.1",
-    "electron": "43.4.1",
+    "electron": "42.6.0",
    "electron-builder": "26.15.3",
    "undici": "7.29.0",
    "esbuild": "^0.25.12",
@@ -58,6 +58,8 @@ 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/"
@@ -4,37 +4,46 @@

 ## 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.
+
+- Library Merge & Reassignment
+  - Duplicate library cards for the same show can be combined: select entries in "Select" mode and use "Merge Selected" to combine their sessions, mined cards, and watch time onto one card.
+  - Episodes can be moved to a different entry with a per-episode "→" button, fixing stray files that split off their own entry; manual assignments now survive later filename parsing, Jellyfin refreshes, and season repair.
+  - Exact AniList matches with compatible seasons merge automatically, while likely (fuzzy) matches surface as a dismissible "Possible duplicate" suggestion instead of merging silently.
+
+- Duplicate Line Cleanup
+  - The Vocabulary tab's new **Duplicates** button scans a chosen time window for the repeated-line bursts described under Fixed below and collapses each burst to a single line once confirmed.
+  - A matching `subminer stats cleanup --duplicate-lines` command (with `--dry-run` and `--lookback-days <n>`) is available from the terminal.
+  - Only the affected subtitle lines and the vocabulary counts they inflated are touched; watch time and lines-seen totals are left as recorded.

 ### 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.
+- Subtitle Duplication from Karaoke & Animated Signs
+  - Typeset ASS karaoke and animated signs no longer flood the overlay, subtitle sidebar, immersion history, mined cards, or stats with repeated glyph fragments or per-frame duplicates; the complete authored line is recovered instead, without merging genuinely repeated dialogue or separately positioned signs.
+  - Fragmented karaoke now preserves the spaces the author placed between words instead of joining them together, and lyric transitions (including seeking into the middle of a line) resolve to the clean line instead of a stray entrance or exit frame.
+  - The secondary overlay shares the same deduplication logic as the primary overlay, including collapsing lines that differ only by whitespace or trailing punctuation, and sidebar navigation moves between clean lyric lines while keeping the right line selected.
+
+- Anki Media Generation
+  - Sentence-audio generation no longer times out on slow network-mounted video files with many subtitle and font streams, and a failed extraction now reports a clear error instead of a raw `ENOENT`.
+  - Mined audio and animated AVIF clips now capture the subtitle line you actually mined, instead of whatever line happened to be on screen once slow audio extraction finished.
+
+- Character Dictionary Performance & Notifications
+  - Character dictionary generation, merged rebuilds, and imports no longer freeze the app on large dictionaries, and cached results (including character portraits) are reused across launches instead of regenerating everything every time.
+  - Portraits also now display correctly if their cache finishes loading after subtitles have already started showing.
+  - Desktop progress notifications, including on Linux AppImage installs, now update in place instead of flickering closed and reopening.
+
+- Overlay Reliability
+  - Overlay modals (settings, stats, etc.) now open promptly on the first shortcut press, including on repeated sessions on Windows, and appear above fullscreen mpv on macOS instead of switching Spaces or opening off-screen.
+  - The macOS window-tracking helper is now built for macOS 12.0+, so the overlay attaches to mpv on older systems like Ventura instead of crashing and getting stuck on "Overlay loading."
+  - The overlay no longer gets stuck on "Overlay loading" indefinitely if mpv's connection stalls; it now retries and shows an actionable error after 30 seconds.
+  - Fixed native Wayland drag-and-drop from file managers like Thunar, and fixed system-wide mouse lag on Windows caused by the overlay's click-through handling.
+
+- Stats Dashboard
+  - Deletes, library merges, video moves, and AniList reassignments no longer freeze the stats dashboard or rebuild lifetime totals from scratch; large deletes that used to take minutes now finish in milliseconds.
+  - Vocabulary totals and charts now count all tracked vocabulary instead of just the first page, and new-word history uses corrected daily rollups.
+  - Calendar labels respect time zones west of UTC, and vocabulary cards refresh automatically after editing the word exclusion list (with a Retry option if a load fails).
+
+- Linux Launcher Thumbnails
+  - Fixed missing MKV thumbnails in the Linux rofi picker when the system thumbnailer only registers legacy Matroska MIME aliases.

 ## What's Changed

@@ -47,6 +56,13 @@
 - 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
+- fix(stats): report complete vocabulary totals and new-word history by @ksyasuda in #202
+- fix(mpv): recover from stalled IPC connects by @ksyasuda in #204
+- fix(dictionary): prevent freezes and restore AppImage notifications by @ksyasuda in #205
+- fix(subtitles): recover canonical lines from ASS animation by @ksyasuda in #207
+- fix(overlay): deduplicate secondary subtitle rendering by @ksyasuda in #208
+- fix(launcher): restore Matroska thumbnails in Linux rofi picker by @ksyasuda in #210
+- fix(character-dictionary): cache completed MeCab refreshes by @ksyasuda in #212

 ## Installation

@@ -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';
@@ -583,7 +584,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,7 +606,8 @@ 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/);
@@ -668,7 +670,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 +725,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 +792,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 +832,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 +1449,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 });
+  }
+});
@@ -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(
@@ -615,7 +784,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 +796,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 +947,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,
    '',
@@ -748,6 +989,7 @@ function writeReleaseNotesFile(
    contributions?: Contribution[];
    contributorSections?: string[];
    metadata?: string[];
+    deltaSection?: string[];
  },
 ): string {
  const mkdirSync = deps?.mkdirSync ?? fs.mkdirSync;
@@ -1079,6 +1321,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 +1357,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 +1499,11 @@ function main(): void {
    return;
  }

+  if (command === 'check-prerelease-notes') {
+    verifyPrereleaseNotesMatchVersion(options);
+    return;
+  }
+
  if (command === 'docs') {
    generateDocsChangelog(options);
    return;
@@ -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
@@ -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"
@@ -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"
@@ -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);
  });
 });
@@ -1,4 +1,5 @@
 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';
@@ -52,6 +53,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 +83,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) {
@@ -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\}/);
+});
@@ -82,6 +82,7 @@ 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.match(srcinfo, /^\tprovides = subminer=0\.6\.3$/m);
    assert.match(
@@ -47,7 +47,7 @@ test('stripFilenameTags normalizes common media-title formats', () => {
  );
 });

-async function backfillMissingCoverBlob(): Promise<void> {
+test('fetchIfMissing backfills a missing blob from an existing cover URL', async () => {
  const dbPath = makeDbPath();
  const db = new Database(dbPath);
  ensureSchema(db);
@@ -103,15 +103,9 @@ async function backfillMissingCoverBlob(): Promise<void> {
    db.close();
    cleanupDbPath(dbPath);
  }
-}
+});

-test(
-  'fetchIfMissing backfills a missing blob from an existing cover URL',
-  { timeout: 15_000 },
-  backfillMissingCoverBlob,
-);
-
-async function reuseCachedAnimeCoverArt(): Promise<void> {
+test('fetchIfMissing reuses cached cover art from another video in the same anime', async () => {
  const dbPath = makeDbPath();
  const db = new Database(dbPath);
  ensureSchema(db);
@@ -185,13 +179,7 @@ async function reuseCachedAnimeCoverArt(): Promise<void> {
    db.close();
    cleanupDbPath(dbPath);
  }
-}
-
-test(
-  'fetchIfMissing reuses cached cover art from another video in the same anime',
-  { timeout: 15_000 },
-  reuseCachedAnimeCoverArt,
-);
+});

 function createJsonResponse(payload: unknown): Response {
  return new Response(JSON.stringify(payload), {
@@ -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,18 @@ 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);
+});
@@ -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;
@@ -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);
@@ -315,10 +315,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}`);
 }

@@ -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 {
@@ -39,7 +39,6 @@ test('non-macOS modal overlay remains a regular window', () => {
  });

  assert.equal(options.type, undefined);
-  assert.equal(options.roundedCorners, false);
 });

 test('Linux visible overlay window allows compositor resize for mpv-sized placement', () => {
@@ -37,7 +37,6 @@ export function buildOverlayWindowOptions(
    paintWhenInitiallyHidden: true,
    backgroundColor: '#00000000',
    frame: false,
-    ...(platform === 'linux' ? { roundedCorners: false } : {}),
    alwaysOnTop: shouldStartAlwaysOnTop,
    skipTaskbar: true,
    resizable: shouldAllowCompositorResize,
@@ -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;
+}
@@ -67,7 +67,6 @@ export function buildStatsWindowOptions(options: {
    width: options.bounds?.width ?? DEFAULT_STATS_WINDOW_WIDTH,
    height: options.bounds?.height ?? DEFAULT_STATS_WINDOW_HEIGHT,
    frame: false,
-    ...(platform === 'linux' ? { roundedCorners: false } : {}),
    transparent: false,
    alwaysOnTop: true,
    resizable: false,
@@ -57,7 +57,6 @@ test('buildStatsWindowOptions remains a regular window off macOS', () => {
  });

  assert.equal(options.type, undefined);
-  assert.equal(options.roundedCorners, false);
 });

 test('stats panels present after document load on macOS', () => {
@@ -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;
  }
@@ -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);
+});
@@ -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'];
+}
@@ -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',
@@ -570,6 +576,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 +1027,655 @@ 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 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 a tall CC-style dialogue block publishable, not a fragment grid', () => {
+  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}燈をバンドに誘ったの？',
+  ].join('\n');
+
+  const cue = parseSubtitleCues(content, 'test.ass')[0];
+  assert.equal(cue?.text, 'たき（立希）ともりお前…　燈をバンドに誘ったの？');
+  assert.equal(cue?.assLayout?.kind, 'positioned');
+});
+
+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 repeated syllables publishable', () => {
+  const fragments = [
+    ['dreams', 300, 115],
+    ['ju', 250, 39],
+    ['n', 280, 39],
+    ['jo', 300, 39],
+    ['u', 330, 39],
+    ['to', 360, 39],
+    ['jo', 395, 39],
+    ['u', 425, 39],
+    ['ne', 455, 39],
+    ['tsu!', 485, 39],
+  ] as const;
+  const content = [
+    ...eventsHeader,
+    ...[0, 1].flatMap((layer) =>
+      fragments.map(
+        ([text, x, y], index) =>
+          `Dialogue: ${layer},0:00:01.00,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',
+  );
+});
@@ -2,25 +2,35 @@ import {
  assOverrideSignature,
  assToPlainText,
  collectAssOverrideCommands,
+  hasAssTemporalOverride,
  parseAssEffectField,
+  removeAssControlDebrisLines,
  type AssEffectKind,
  type AssOverrideCommand,
 } from './ass-text';
 import { hasAssAnimationEvidence, mergeDuplicateCues } from './subtitle-cue-dedup';

+export type AssCueLayout =
+  | { kind: 'positioned'; sourceOrder: number; y: number }
+  | { kind: 'fragment-grid'; sourceOrder: number }
+  | { kind: 'source-order'; sourceOrder: number };
+
 export interface SubtitleCue {
  startTime: number;
  endTime: number;
  text: string;
-  /** A complete authored line recovered from matching generated ASS animation events. */
-  source?: 'canonical-ass';
+  /** How a complete line was recovered from generated ASS animation events. */
+  source?: 'canonical-ass' | 'reconstructed-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.
+   * 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 +39,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 +85,59 @@ 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 attachAssLayout<T extends SubtitleCue>(cue: T, assLayout: AssCueLayout | undefined): T {
+  if (assLayout) {
+    Object.defineProperty(cue, 'assLayout', { value: assLayout, 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,
+    }) => {
+      const common = {
+        startTime,
+        endTime,
+        text,
+      };
+      if (source === 'reconstructed-ass') {
+        return attachAssLayout(
+          {
+            ...common,
+            source,
+            animationStartTime,
+            animationEndTime,
+            assStyle: style,
+          },
+          assLayout,
+        );
+      }
+      return attachAssLayout(
+        source ? { ...common, source, animationStartTime, animationEndTime } : common,
+        assLayout,
+      );
+    },
  );
 }

@@ -159,6 +213,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());
@@ -281,6 +340,27 @@ function fragmentPlacementAnchors(event: AnnotatedSubtitleCue): Set<string> {
  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;
+
+// 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.
+function fragmentAnchorPoints(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]! + args[2]!) / 2, y: (args[1]! + args[3]!) / 2 });
+    }
+  }
+  return points;
+}
+
 function isRepeatedFragmentCopy(
  previous: AnnotatedSubtitleCue,
  current: AnnotatedSubtitleCue,
@@ -289,6 +369,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 +387,685 @@ function isRepeatedFragmentCopy(
  );
 }

+function hasRelaxedAssFragmentEvidence(events: readonly AnnotatedSubtitleCue[]): boolean {
+  if (events.length < 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, 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') continue;
+    const placement = `${part.text}@${Math.round(part.layout.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 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 {
+  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 < MIN_FRAGMENT_LINE_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;
+}
+
+function reconstructAssFragmentLine(
+  events: readonly AnnotatedSubtitleCue[],
+): AnnotatedSubtitleCue | null {
+  const hasRelaxedEvidence = hasRelaxedAssFragmentEvidence(events);
+  const minimumEvents = hasRelaxedEvidence ? 2 : MIN_FRAGMENT_LINE_EVENTS;
+  if (events.length < minimumEvents || !hasAssAnimationEvidence(events)) {
+    return null;
+  }
+
+  const parts: AssFragmentPart[] = [];
+  for (const cue of events) {
+    const text = decodeSingleAssFragment(cue);
+    if (text === null) {
+      return null;
+    }
+    const compactText = compactAssMatchText(text);
+    const isLayerCopy = parts.some(
+      (part) =>
+        compactAssMatchText(part.text) === compactText && isRepeatedFragmentCopy(part.cue, cue),
+    );
+    if (!isLayerCopy) {
+      parts.push({ cue, text });
+    }
+  }
+
+  const minimumParts = hasRelaxedEvidence ? 1 : MIN_FRAGMENT_LINE_PARTS;
+  if (parts.length < minimumParts || (!hasRelaxedEvidence && parts.length === events.length)) {
+    return null;
+  }
+  const lengths = parts
+    .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 text = joinAssFragmentParts(parts);
+  if (!text) {
+    return null;
+  }
+  const owner = parts[0]!.cue;
+  const animationStartTime = earliestStartTime(events);
+  const animationEndTime = latestEndTime(events);
+  return {
+    ...owner,
+    startTime: animationStartTime,
+    endTime: animationEndTime,
+    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;
+}
+
+/**
+ * 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>();
+  for (const events of groups.values()) {
+    const decorative = decorativeGlyphEvents(events);
+    const lineEvents = decorative.size ? events.filter((event) => !decorative.has(event)) : events;
+    if (isProgressiveHighlightSweepGroup(lineEvents)) {
+      lineEvents.forEach((event) => suppressed.add(event));
+      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 && overlay.endTime > spanStart) {
+          suppressed.add(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((event) => suppressed.add(event));
+        continue;
+      }
+      recovered.push(line);
+      cluster.events.forEach((event) => suppressed.add(event));
+      // 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 && overlay.endTime > spanStart) {
+          suppressed.add(overlay);
+        }
+      }
+    }
+  }
+  if (recovered.length === 0 && suppressed.size === 0) {
+    return dialogue;
+  }
+  return [...dialogue.filter((cue) => !suppressed.has(cue)), ...recovered].sort(
+    (left, right) =>
+      left.startTime - right.startTime || left.endTime - right.endTime || left.order - right.order,
+  );
+}
+
 function groupConsecutiveAssFragments(events: readonly AnnotatedSubtitleCue[]): FragmentGroup[] {
  const groups: FragmentGroup[] = [];
  for (const event of events) {
@@ -507,6 +1277,37 @@ function recoverCanonicalAssEvents({
  );
 }

+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,
+): AssCueLayout {
+  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') {
+      y = parseAssCoordinate(args[1]) ?? y;
+      continue;
+    }
+    if (name !== 'move') continue;
+    const startY = parseAssCoordinate(args[1]);
+    const endY = parseAssCoordinate(args[3]);
+    if (startY !== null && endY !== null) {
+      y = (startY + endY) / 2;
+    }
+  }
+  return y === null
+    ? { kind: 'source-order', sourceOrder }
+    : { kind: 'positioned', sourceOrder, y };
+}
+
 function parseAnnotatedAssEvents(content: string): ParsedAssEvents {
  const cues: AnnotatedSubtitleCue[] = [];
  const comments: AnnotatedSubtitleCue[] = [];
@@ -535,6 +1336,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 +1370,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 +1383,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 +1394,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;
    }
@@ -615,6 +1420,7 @@ function parseAnnotatedAssEvents(content: string): ParsedAssEvents {
      overrides,
      overrideSignature: assOverrideSignature(overrides),
      order: eventOrder,
+      assLayout: buildAssCueLayout(overrides, eventOrder),
    };
    eventOrder += 1;
    if (eventPrefix === ASS_COMMENT_PREFIX) {
@@ -628,7 +1434,7 @@ function parseAnnotatedAssEvents(content: string): ParsedAssEvents {
 }

 function parseAnnotatedAssCues(content: string): AnnotatedSubtitleCue[] {
-  return recoverCanonicalAssEvents(parseAnnotatedAssEvents(content));
+  return recoverFragmentOnlyAssLines(recoverCanonicalAssEvents(parseAnnotatedAssEvents(content)));
 }

 export function parseAssCues(content: string): SubtitleCue[] {
@@ -606,93 +606,3 @@ test('configureEarlyAppPaths pins userData to canonical SubMiner config dir', ()
  assert.equal(userDataPath, '/tmp/xdg/SubMiner');
  assert.deepEqual(calls, ['name:SubMiner', 'path:userData:/tmp/xdg/SubMiner']);
 });
-
-test('configureEarlyAppPaths isolates development runs from the production profile', () => {
-  const calls: string[] = [];
-
-  const userDataPath = configureEarlyAppPaths(
-    {
-      setName: (name) => calls.push(`name:${name}`),
-      setPath: (key, value) => calls.push(`path:${key}:${value}`),
-    },
-    {
-      platform: 'linux',
-      homeDir: '/home/tester',
-      xdgConfigHome: '/tmp/xdg',
-      existsSync: () => false,
-      argv: ['electron', '.', '--start', '--dev'],
-      env: {},
-    },
-  );
-
-  assert.equal(userDataPath, '/tmp/xdg/SubMiner-dev');
-  assert.deepEqual(calls, ['name:SubMiner', 'path:userData:/tmp/xdg/SubMiner-dev']);
-});
-
-test('configureEarlyAppPaths ignores development flags forwarded to mpv', () => {
-  for (const forwardedFlag of ['--dev', '--debug']) {
-    let selectedPath = '';
-    const userDataPath = configureEarlyAppPaths(
-      {
-        setName: () => {},
-        setPath: (_key, value) => {
-          selectedPath = value;
-        },
-      },
-      {
-        platform: 'linux',
-        homeDir: '/home/tester',
-        xdgConfigHome: '/tmp/xdg',
-        existsSync: () => false,
-        argv: ['electron', '.', '--launch-mpv', forwardedFlag],
-        env: {},
-      },
-    );
-
-    assert.equal(userDataPath, '/tmp/xdg/SubMiner');
-    assert.equal(selectedPath, '/tmp/xdg/SubMiner');
-  }
-});
-
-test('configureEarlyAppPaths uses the supplied environment for config discovery', () => {
-  const paths: string[] = [];
-
-  const userDataPath = configureEarlyAppPaths(
-    {
-      setName: () => {},
-      setPath: (_key, value) => paths.push(value),
-    },
-    {
-      platform: 'linux',
-      homeDir: '/home/tester',
-      existsSync: () => false,
-      argv: ['electron', '.', '--start'],
-      env: { XDG_CONFIG_HOME: '/tmp/injected-xdg' },
-    },
-  );
-
-  assert.equal(userDataPath, '/tmp/injected-xdg/SubMiner');
-  assert.deepEqual(paths, ['/tmp/injected-xdg/SubMiner']);
-});
-
-test('configureEarlyAppPaths allows an explicit production-profile development run', () => {
-  const paths: string[] = [];
-
-  const userDataPath = configureEarlyAppPaths(
-    {
-      setName: () => {},
-      setPath: (_key, value) => paths.push(value),
-    },
-    {
-      platform: 'win32',
-      appDataDir: 'C:\\Users\\tester\\AppData\\Roaming',
-      homeDir: 'C:\\Users\\tester',
-      existsSync: () => false,
-      argv: ['electron.exe', '.', '--debug'],
-      env: { SUBMINER_USE_PRODUCTION_PROFILE: '1' },
-    },
-  );
-
-  assert.equal(userDataPath, 'C:\\Users\\tester\\AppData\\Roaming\\SubMiner');
-  assert.deepEqual(paths, ['C:\\Users\\tester\\AppData\\Roaming\\SubMiner']);
-});
@@ -1,6 +1,5 @@
 import fs from 'node:fs';
 import os from 'node:os';
-import path from 'node:path';
 import { spawn } from 'node:child_process';
 import { CliArgs, hasExplicitCommand, parseArgs, shouldStartApp } from './cli/args';
 import { resolveConfigDir } from './config/path-resolution';
@@ -15,8 +14,6 @@ const TRANSPORTED_APP_ARGC_ENV = 'SUBMINER_APP_ARGC';
 const TRANSPORTED_APP_ARG_PREFIX = 'SUBMINER_APP_ARG_';
 const MAX_TRANSPORTED_APP_ARGS = 256;
 const APP_NAME = 'SubMiner';
-const DEVELOPMENT_APP_NAME = 'SubMiner-dev';
-export const USE_PRODUCTION_PROFILE_ENV = 'SUBMINER_USE_PRODUCTION_PROFILE';
 const DEFAULT_APP_CONTROL_HANDOFF_TIMEOUT_MS = 500;
 const MACOS_APP_CONTROL_HANDOFF_TIMEOUT_MS = 3000;
 const MPV_LONG_OPTIONS_WITH_SEPARATE_VALUES = new Set([
@@ -56,8 +53,6 @@ type EarlyAppPathOptions = {
  xdgConfigHome?: string;
  homeDir?: string;
  existsSync?: (candidate: string) => boolean;
-  argv?: string[];
-  env?: NodeJS.ProcessEnv;
 };

 function removeLsfgLayer(env: NodeJS.ProcessEnv): void {
@@ -257,25 +252,13 @@ export function normalizeStartupArgv(argv: string[], env: NodeJS.ProcessEnv): st
 }

 export function configureEarlyAppPaths(app: EarlyAppLike, options?: EarlyAppPathOptions): string {
-  const platform = options?.platform ?? process.platform;
-  const env = options?.env ?? process.env;
-  const configDir = resolveConfigDir({
-    platform,
-    appDataDir: options?.appDataDir ?? env.APPDATA,
-    xdgConfigHome: options?.xdgConfigHome ?? env.XDG_CONFIG_HOME,
+  const userDataPath = resolveConfigDir({
+    platform: options?.platform ?? process.platform,
+    appDataDir: options?.appDataDir ?? process.env.APPDATA,
+    xdgConfigHome: options?.xdgConfigHome ?? process.env.XDG_CONFIG_HOME,
    homeDir: options?.homeDir ?? os.homedir(),
    existsSync: options?.existsSync ?? fs.existsSync,
  });
-  const argv = options?.argv ?? process.argv;
-  const launchMpvIndex = argv.indexOf('--launch-mpv');
-  const appArgv = launchMpvIndex === -1 ? argv : argv.slice(0, launchMpvIndex);
-  const useDevelopmentProfile =
-    (appArgv.includes('--dev') || appArgv.includes('--debug')) &&
-    env[USE_PRODUCTION_PROFILE_ENV] !== '1';
-  const platformPath = platform === 'win32' ? path.win32 : path.posix;
-  const userDataPath = useDevelopmentProfile
-    ? platformPath.join(platformPath.dirname(configDir), DEVELOPMENT_APP_NAME)
-    : configDir;

  app.setName(APP_NAME);
  app.setPath('userData', userDataPath);
@@ -22,10 +22,7 @@ import {
  shouldHandleStatsDaemonCommandAtEntry,
  spawnDetachedApp,
 } from './main-entry-runtime';
-import {
-  requestSingleInstanceLockEarly,
-  shouldBypassSingleInstanceLockForArgv,
-} from './main/early-single-instance';
+import { requestSingleInstanceLockEarly } from './main/early-single-instance';
 import { readConfiguredWindowsMpvLaunch } from './main-entry-launch-config';
 import { isAppControlServerAvailable, sendAppControlCommand } from './shared/app-control-client';
 import {
@@ -38,7 +35,6 @@ import { createWindowsMpvLaunchDeps, launchWindowsMpv } from './main/runtime/win
 import { runStatsDaemonControlFromProcess } from './stats-daemon-entry';
 import { handleSyncCliAtEntry } from './main/sync-cli';
 import { createFatalErrorReporter, registerFatalErrorHandlers } from './main/fatal-error';
-import { enforceElectronRuntimeGuard } from './main/electron-runtime-guard';
 import { buildMpvLoggingArgs } from './shared/mpv-logging-args';
 import {
  applyLogFileTogglesToEnv,
@@ -196,25 +192,11 @@ registerFatalErrorHandlers({
 });

 function startMainProcess(): void {
-  // Normal launches serialize the runtime guard with the profile-scoped lock. Stats daemon
-  // commands keep their existing lock bypass when Electron runs in Node mode.
-  const gotSingleInstanceLock =
-    shouldBypassSingleInstanceLockForArgv(process.argv) || requestSingleInstanceLockEarly(app);
+  const gotSingleInstanceLock = requestSingleInstanceLockEarly(app);
  if (!gotSingleInstanceLock) {
    app.exit(0);
    return;
  }
-
-  const runtimeGuard = enforceElectronRuntimeGuard({
-    electronVersion: process.versions.electron ?? '',
-    userDataPath,
-  });
-  if (!runtimeGuard.ok) {
-    console.error(runtimeGuard.details);
-    dialog.showErrorBox(runtimeGuard.title, runtimeGuard.details);
-    app.exit(1);
-    return;
-  }
  try {
    require('./main.js');
  } catch (error) {
@@ -36,10 +36,6 @@ import { openPlaylistBrowser as openPlaylistBrowserRuntime } from './main/runtim
 import { createAniSkipRuntime } from './main/runtime/aniskip-runtime';
 import { resolveAniSkipMetadataForFile } from './main/runtime/aniskip-metadata';
 import { createDiscordRpcClient } from './main/runtime/discord-rpc-client.js';
-import {
-  assertYomitanDictionaryMutationSafe,
-  observeYomitanDictionaryCount,
-} from './main/runtime/yomitan-dictionary-integrity';
 import { startAppControlServer } from './main/runtime/app-control-server';
 import { createEnsureBackgroundStatsServerHandler } from './main/runtime/background-stats-startup';
 import {
@@ -316,6 +312,7 @@ import {
  promoteSettingsWindowAboveOverlay,
  registerGlobalShortcuts as registerGlobalShortcutsCore,
  replayCurrentSubtitleRuntime,
+  resolveSanitizedSubtitleSeekCommand,
  resolveJellyfinPlaybackPlanRuntime,
  runStartupBootstrapRuntime,
  saveJellyfinSubtitleDelay,
@@ -591,9 +588,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';

@@ -768,7 +766,6 @@ type BootServices = MainBootServicesResult<
 const bootServices = createMainBootServices({
  platform: process.platform,
  argv: process.argv,
-  configDir: app.getPath('userData'),
  appDataDir: process.env.APPDATA,
  xdgConfigHome: process.env.XDG_CONFIG_HOME,
  homeDir: os.homedir(),
@@ -1437,10 +1434,6 @@ const firstRunSetupService = createFirstRunSetupService({
      error: (message, ...args) => logger.error(message, ...args),
      info: (message, ...args) => logger.info(message, ...args),
    });
-    const integrity = observeYomitanDictionaryCount(USER_DATA_PATH, dictionaries.length);
-    if (!integrity.safe) {
-      logger.error(`[dictionary:integrity] ${integrity.message}`);
-    }
    return dictionaries.length;
  },
  isExternalYomitanConfigured: () =>
@@ -1967,6 +1960,31 @@ let linuxVisibleOverlayOwnerBindingKey: string | null = null;
 let linuxVisibleOverlayWindowModeSwitchToken = 0;
 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 +2055,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 +2089,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),
@@ -2532,12 +2552,10 @@ const characterDictionaryAutoSyncRuntime = createCharacterDictionaryAutoSyncRunt
    ),
  getYomitanDictionaryInfo: async () => {
    await ensureYomitanExtensionLoaded();
-    const dictionaries = await getYomitanDictionaryInfo(getYomitanParserRuntimeDeps(), {
+    return await getYomitanDictionaryInfo(getYomitanParserRuntimeDeps(), {
      error: (message, ...args) => logger.error(message, ...args),
      info: (message, ...args) => logger.info(message, ...args),
    });
-    assertYomitanDictionaryMutationSafe(USER_DATA_PATH, dictionaries.length);
-    return dictionaries;
  },
  importYomitanDictionary: async (zipPath) => {
    if (yomitanProfilePolicy.isExternalReadOnlyMode()) {
@@ -2634,6 +2652,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
@@ -3941,6 +3965,7 @@ const {
      appState.yomitanSettingsWindow = null;
    },
    stopJellyfinRemoteSession: () => stopJellyfinRemoteSession(),
+    cleanupInternalSubtitleTrackCache: () => cachedInternalSubtitleTrackExtractor.clear(),
    cleanupYoutubeSubtitleTempDirs: () => youtubeFlowRuntime.cleanupSubtitleTempDirs(),
    cleanupYoutubeMediaCache: () => youtubeMediaCache.cleanup(),
    cleanupJellyfinSubtitleCache: () => cleanupJellyfinSubtitleCache(),
@@ -4058,7 +4083,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 +4094,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) {
@@ -4501,6 +4526,7 @@ const {
        appState.activeParsedSubtitleMediaPath,
      );
      if ((normalizedPath || null) !== previousPath) {
+        cachedInternalSubtitleTrackExtractor.clear();
        secondarySubtitleTrackController.reset();
        const resetSubtitlePayload = { text: '', tokens: null };
        const frequencyDictionary = configService.getConfig().subtitleStyle.frequencyDictionary;
@@ -4585,6 +4611,7 @@ const {
    reportJellyfinRemoteProgress: (forceImmediate) => {
      void reportJellyfinRemoteProgress(forceImmediate);
    },
+    consumeExplicitSeek: () => consumeExplicitSeekIntent(),
    onTimePosUpdate: (time) => {
      const delta = time - lastObservedTimePos;
      if (subtitlePrefetchService && (delta > SEEK_THRESHOLD_SECONDS || delta < 0)) {
@@ -5092,9 +5119,7 @@ function initializeOverlayRuntime(): void {
    overlayModalRuntime.primeModalWindow();
  }
  appState.ankiIntegration?.setRecordCardsMinedCallback(recordTrackedCardsMined);
-  appState.ankiIntegration?.setKnownWordCacheUpdatedCallback(
-    refreshCurrentSubtitleAfterKnownWordUpdate,
-  );
+  appState.ankiIntegration?.setKnownWordCacheUpdatedCallback(refreshCurrentSubtitleAnnotations);
  appState.ankiIntegration?.setSubtitleMiningContextConsumer(consumePendingSubtitleMiningContext);
  syncOverlayMpvSubtitleSuppression();
 }
@@ -5492,8 +5517,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,
@@ -5887,7 +5911,7 @@ const { registerIpcRuntimeHandlers } = composeIpcRuntimeHandlers({
        appState.ankiIntegration = integration;
        appState.ankiIntegration?.setRecordCardsMinedCallback(recordTrackedCardsMined);
        appState.ankiIntegration?.setKnownWordCacheUpdatedCallback(
-          refreshCurrentSubtitleAfterKnownWordUpdate,
+          refreshCurrentSubtitleAnnotations,
        );
        appState.ankiIntegration?.setSubtitleMiningContextConsumer(
          consumePendingSubtitleMiningContext,
@@ -138,56 +138,3 @@ test('createMainBootServices builds boot-phase service bundle', () => {
  assert.deepEqual(calls, ['mkdir:/tmp/subminer-config', 'exit:7']);
  assert.equal(setPathValue, '/tmp/subminer-config');
 });
-
-test('createMainBootServices honors the profile selected by the early entrypoint', () => {
-  const services = createMainBootServices({
-    platform: 'linux',
-    argv: ['electron', '.', '--dev'],
-    configDir: '/tmp/SubMiner-dev',
-    appDataDir: undefined,
-    xdgConfigHome: undefined,
-    homeDir: '/home/tester',
-    defaultMpvLogFile: '/tmp/default.log',
-    envMpvLog: undefined,
-    defaultTexthookerPort: 5174,
-    getDefaultSocketPath: () => '/tmp/subminer.sock',
-    resolveConfigDir: () => {
-      throw new Error('early profile should be authoritative');
-    },
-    existsSync: () => false,
-    mkdirSync: () => {},
-    joinPath: (...parts) => parts.join('/'),
-    app: {
-      setPath: () => {},
-      quit: () => {},
-      exit: () => {},
-      on: () => ({}),
-      whenReady: async () => {},
-    },
-    shouldBypassSingleInstanceLock: () => false,
-    requestSingleInstanceLockEarly: () => true,
-    registerSecondInstanceHandlerEarly: () => {},
-    onConfigStartupParseError: () => {},
-    createConfigService: (configDir) => ({ configDir }),
-    createAnilistTokenStore: (targetPath) => ({ targetPath }),
-    createJellyfinTokenStore: (targetPath) => ({ targetPath }),
-    createAnilistUpdateQueue: (targetPath) => ({ targetPath }),
-    createSubtitleWebSocket: (payloadMode) => ({ payloadMode }),
-    createLogger: () => ({ warn: () => {}, info: () => {}, error: () => {} }),
-    createMainRuntimeRegistry: () => ({}),
-    createOverlayManager: () => ({ getMainWindow: () => null, getModalWindow: () => null }),
-    createOverlayModalInputState: () => ({
-      getModalInputExclusive: () => false,
-      handleModalInputStateChange: () => {},
-    }),
-    createOverlayContentMeasurementStore: () => ({}),
-    getSyncOverlayShortcutsForModal: () => () => {},
-    getSyncOverlayVisibilityForModal: () => () => {},
-    createOverlayModalRuntime: () => ({}),
-    createAppState: (input) => input,
-  });
-
-  assert.equal(services.configDir, '/tmp/SubMiner-dev');
-  assert.equal(services.userDataPath, '/tmp/SubMiner-dev');
-  assert.deepEqual(services.configService, { configDir: '/tmp/SubMiner-dev' });
-});
@@ -31,7 +31,6 @@ export interface MainBootServicesParams<
 > {
  platform: NodeJS.Platform;
  argv: string[];
-  configDir?: string;
  appDataDir: string | undefined;
  xdgConfigHome: string | undefined;
  homeDir: string;
@@ -175,15 +174,13 @@ export function createMainBootServices<
  TAppState,
  TAppLifecycleApp
 > {
-  const configDir =
-    params.configDir ??
-    params.resolveConfigDir({
-      platform: params.platform,
-      appDataDir: params.appDataDir,
-      xdgConfigHome: params.xdgConfigHome,
-      homeDir: params.homeDir,
-      existsSync: params.existsSync,
-    });
+  const configDir = params.resolveConfigDir({
+    platform: params.platform,
+    appDataDir: params.appDataDir,
+    xdgConfigHome: params.xdgConfigHome,
+    homeDir: params.homeDir,
+    existsSync: params.existsSync,
+  });
  const userDataPath = configDir;
  const defaultMpvLogPath = params.envMpvLog?.trim() || params.defaultMpvLogFile;
  const defaultImmersionDbPath = params.joinPath(userDataPath, 'immersion.sqlite');
@@ -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,
@@ -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 = {
@@ -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;
      }
@@ -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/);
 });
@@ -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 };
 }
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
sudacode	60432ca2f3	fix(subtitles): suppress overlay duplicates and reset ASS cleanup - Suppress overlapping decorative karaoke and shadow layer copies - Clear stale ASS-only fallback sanitization after source refresh failures	2026-08-23 23:02:44 -07:00
sudacode	9044340676	fix(subtitles): recover positioned word gaps in reconstructed translations	2026-08-23 21:37:48 -07:00
sudacode	6d1a1b841a	fix(subtitles): suppress sweep stragglers and drop-shadow glyph doubles	2026-08-23 21:11:51 -07:00
sudacode	0ac5db1c92	fix(subtitles): suppress karaoke highlight sweeps from reconstructed lyrics	2026-08-23 21:00:43 -07:00
sudacode	4635bfb264	fix(subtitles): extract embedded subtitle tracks from network-mounted media The network-mount skip made SMB/NFS libraries fall back to live mpv text for any release shipping subtitles only inside the container, losing karaoke reconstruction, sidebar cues, and mining. The starvation it guarded against had a different cause, and measured extraction runs at wire speed (~10s/GB on gigabit) once per episode. Skip extraction only for true remote URLs, which have no on-disk container to demux, and raise the extraction timeout to cover large Bluray remuxes read over the network.	2026-08-23 20:45:30 -07:00
sudacode	1717d2d3f2	fix(subtitles): suppress per-glyph typesetting walls in live subtitle text When embedded-track extraction is skipped (network-mounted media), live mpv text during per-glyph typeset karaoke is a wall of simultaneous one-glyph lines plus the syllable being typed. No parsed cues exist to substitute, so the wall reached both overlays and recording verbatim. Detect bursts of many single-glyph lines in the live fallback paths and drop them with their short syllable companions, keeping concurrent dialogue lines.	2026-08-23 20:33:13 -07:00
sudacode	9f08adbfb9	fix(subtitles): drop symbol-font glyph decoration and recover wide-glyph word gaps Generated lyric effects can overlay each syllable with animated single letters rendered through \fn in a symbol font, where ordinary letters draw as sparkles. Reading them as text corrupted reconstructed lines ("sotto mimi ni ateru to a z x") and leaked junk cues ("hlk"). A font a style group uses only for scattered animated single glyphs now marks those events as decoration: they stay out of fragment reconstruction and are suppressed alongside the line they overlay. Per-glyph word gaps measured across a wide glyph ("waves\|within" over s/w) normalize to nearly a common advance, so the ratio test missed them. A word space adds a roughly constant extra distance regardless of neighbor widths, so glyph runs with enough gap samples also split when the advance exceeds the width-predicted advance by a material fraction of the line's common unit. Capital-to-lowercase pairs and short sample counts are excluded; both guards are pinned by corpus-derived regression tests. Across the 145-file library corpus this removes every scattered-letter malformation and recovers 30+ missing word spaces with no other output change.	2026-08-23 20:33:04 -07:00
sudacode	6f52008e5d	fix(subtitles): keep dialogue and wrapped lyrics out of ASS fragment gri - Only classify tall positioned ASS blocks as fragment grids when they read like tiling (sign walls, re-shown countdown frames, scattered single glyphs, or table columns), keeping CC-style dialogue blocks and wrapped lyric rows publishable - Widen Latin word-gap heuristics for per-glyph typesetting runs and short capitalized words so proportional-font variation and two-letter words no longer get split - Add changelog fragment documenting the stats database busy-timeout fix	2026-08-23 19:16:55 -07:00
sudacode	c4284d1dd4	fix(stats): avoid transient SQLite worker lock	2026-08-23 17:34:16 -07:00
sudacode	da2a212434	fix(subtitles): reset ASS fallback state on secondary disconnect - Clear activeSourceUsesAssSyntax when mpv disconnects so stale ASS sanitization doesn't leak into live fallback text after reconnect	2026-08-23 17:16:49 -07:00
sudacode	faab084588	fix(subtitles): only strip ASS control debris for ASS sources - Skip control-debris stripping for primary/secondary live text when cues or source aren't ASS/SSA, so SRT lines that merely resemble ASS override tags survive - Track active source's ASS-ness in the secondary controller and gate handleLiveText's cleanup on it	2026-08-23 16:54:43 -07:00
sudacode	c87dcd6239	fix(subtitles): recover positioned ASS word spacing and drop control deb - Recover Latin/romaji word spaces encoded only by positioned `\pos`/`\move` fragment gaps in ASS karaoke - Drop malformed ASS rotation-reset spacer lines and skip zero-duration metadata events - Dedupe duplicate lines across multiline primary/secondary cues, including full-width variants - Treat dense fragment-grid sign layouts as visual typesetting, not publishable text, during primary subtitle resolution	2026-08-23 16:34:36 -07:00
sudacodeandsudacode	ed7d3f4c3d	feat(release): track prerelease deltas and validate committed notes (#216 ) Co-authored-by: sudacode <claude@lmaoxd.lol>	2026-08-23 15:24:18 -07:00
sudacode	509dc5bf7f	fix(subtitles): improve secondary subtitle extraction and display (#215 )	2026-08-23 01:56:49 -07:00
sudacode	0a0aa3ec98	chore(release): prepare v0.19.4-beta.4	2026-08-23 01:23:16 -07:00
sudacode	b87cc3cfdd	chore(workflow): add release skill	2026-08-23 01:14:03 -07:00
sudacode	8cb3c8c90a	fix(macos): pin window helper deployment target to fix older systems - Build the Swift window-tracking helper with an explicit `-target ...-apple-macos12.0` instead of letting swiftc stamp the build machine's OS, so the overlay attaches to mpv on older macOS (e.g. Ventura) instead of crashing at load - Fold the standalone build-macos-helper.sh into prepare-build-assets.mjs and update docs/tests to match	2026-08-23 00:58:24 -07:00
sudacode	03ea903927	fix(subtitles): preserve authored spaces in fragmented ASS karaoke - Only trim indentation before slicing ASS event fields so a trailing authored space at a fragment's end is kept, preventing words from being joined together when fragmented karaoke lines are reconstructed - Add regression test covering event-boundary word spacing	2026-08-22 23:32:35 -07:00
sudacode	3aea42e6f8	chore(release): prepare v0.19.4-beta.3	2026-08-21 23:25:37 -07:00
sudacode	88bb3edfa4	fix(subtitles): preserve lyric selection and deduplicate secondary text - Seek sidebar selections past overlapping karaoke exit spans - Collapse duplicate long ASS lines and omit reconstructed sign grids	2026-08-21 01:28:00 -07:00
sudacode	9445aef004	fix(subtitles): navigate by sanitized cues across ASS animation - Route subtitle navigation through parsed cue boundaries - Treat explicit short seeks as subtitle priming events	2026-08-20 00:20:51 -07:00
sudacode	c01bcd9d0f	fix(subtitles): collapse layered ASS lyrics across startup and seeks - Reconstruct fragment-only karaoke while preserving canonical animated signs - Reprocess live subtitles after initial playback and seek updates - Add a development launcher for playable media files	2026-08-19 22:55:10 -07:00
sudacode	695613b1e7	chore(release): prepare v0.19.4-beta.2	2026-08-19 02:19:40 -07:00
sudacode	20797772f8	fix(character-dictionary): cache completed MeCab refreshes (#212 )	2026-08-19 01:49:15 -07:00
sudacode	72c312810a	docs: link README demo to GitHub video playback - Use GitHub-hosted video playback for the README demo - Document the animated fallback behavior	2026-08-19 01:02:05 -07:00
sudacode	b61f050e78	docs: update mining demo and scale video crops - Refresh mining demo assets and documentation references - Scale mpv crop coordinates for resized OBS recordings	2026-08-19 00:55:31 -07:00
sudacode	2a77ba9dd4	fix(launcher): restore Matroska thumbnails in Linux rofi picker (#210 )	2026-08-18 20:30:58 -07:00