chore(release): prepare v0.19.4

fix(subtitles): recover positioned ASS word spacing and drop control debris (#217 )
feat(release): track prerelease deltas and validate committed notes (#216 )
2026-08-25 12:15:26 -07:00 · 2026-08-25 02:43:48 -07:00 · 2026-08-25 02:22:21 -07:00 · 2026-08-23 15:24:18 -07:00 · 2026-08-23 01:56:49 -07:00
65 changed files with 4586 additions and 252 deletions
@@ -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
@@ -297,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

@@ -327,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
@@ -296,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

@@ -345,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:
@@ -421,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 \
@@ -433,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"
@@ -451,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
@@ -460,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
@@ -1,5 +1,33 @@
 # Changelog

+## v0.19.4 (2026-08-25)
+
+### Added
+- **Library Merge & Move**: Duplicate library cards for the same show can now be combined. Select cards in the library grid and use "Merge Selected" to pick which entry to keep and move every episode onto it, preserving sessions, mined cards, and watch time. Episodes can also be reassigned individually via the "→" button, useful when a file lands under a stray title; manual assignments survive later filename parsing, Jellyfin refreshes, and season repair. Exact AniList title matches with compatible seasons now merge automatically, while fuzzy matches surface as dismissible "Possible duplicate" reviews instead of merging silently.
+- **Duplicate Line Cleanup Tool**: The Vocabulary tab's new "Duplicates" button scans a chosen time window (7 days through all time) for old karaoke/typeset duplicate-line bursts, shows what it found, and collapses each run to one line once confirmed; `subminer stats cleanup --duplicate-lines` does the same from the terminal, with `--dry-run` and `--lookback-days <n>` options. Watch time and lines-seen totals are left unchanged.
+
+### Changed
+- **Prerelease Release Notes**: Prerelease notes now open with a "Changes since" section listing only what changed versus the previous beta/RC of the same version, above the cumulative highlights, and CI rejects prerelease tags whose committed notes were generated for a different beta/RC.
+
+### Fixed
+- **Subtitle & Karaoke Duplication**: Typeset ASS karaoke and animated signs no longer flood the overlay, subtitle sidebar, immersion history, mining, or stats with glyph fragments, per-frame color phases, or repeated animation events. Lines are reconstructed once from their authored text and shown only while actually sung, with original word spacing preserved. Decorative layers (highlight sweeps, glow/shadow copies, symbol-font decoration, particle swarms, hidden or zero-scaled text) stay out of published text, while ordinary repeated dialogue, positioned signs, wrapped lyric rows, and multi-row CC-style blocks still display correctly. Embedded subtitle tracks on network-mounted (SMB/NFS) media are extracted and parsed again instead of falling back to live-text-only, restoring karaoke reconstruction, sidebar cues, and mining for releases that only ship subtitles inside the container. Secondary subtitles now go through the same deduplication pipeline as primary subtitles and no longer clip display after about four lines. Event-heavy karaoke files that previously stalled subtitle loading for several seconds now parse in well under a second.
+- **Character Dictionary Reliability**: Character dictionary generation, merged rebuilds, and imports no longer freeze the app on large dictionaries. Snapshot I/O, archive building, and image/name lookup caches moved off the UI's critical path. Dictionaries are reused instead of regenerated when MeCab finds no name splits, and cached portraits now restore correctly after the portrait index finishes loading post-tokenization. Desktop progress notifications on Linux AppImage installs now update in place instead of flickering, fixing a bug where the AppImage's bundled libraries broke the system notification helper.
+- **Overlay Startup & Modals**: Fixed several causes of the overlay getting stuck on "Overlay loading": the macOS window-tracking helper now targets macOS 12.0+ instead of requiring the build machine's exact macOS version (previously crashed on older systems like Ventura), and mpv IPC connection attempts now time out and retry, showing an actionable error if content still isn't ready after 30 seconds. Dedicated overlay modals are also prewarmed on macOS and Windows so shortcuts open them promptly, and on macOS reused modals and the stats window now open above fullscreen mpv on its current Space instead of jumping to another desktop.
+- **Wayland File Drop**: Fixed native Wayland drag-and-drop from file managers such as Thunar, so subtitle and video files dropped on the visible overlay are resolved and forwarded to mpv.
+- **Windows Mouse Lag**: Fixed system-wide mouse lag on Windows while SubMiner is running, caused by the overlay's global mouse hook for click-through forwarding and by the mpv window tracker blocking the app on repeated PowerShell lookups.
+- **Sentence Mining Audio & Clips**: Sentence-audio generation no longer times out on slow network-mounted media with many subtitle/font streams (bounded FFmpeg probing, two-minute extraction budget, clearer error reporting), and mined audio/animated AVIF clips now capture the subtitle line that was actually mined by snapshotting the clip range at lookup time instead of reading live mpv state later.
+- **Stats Performance & Reliability**: Immersion stats storage now sets its SQLite busy timeout before WAL setup, avoiding transient lock errors under concurrent writes. Deletes in the stats dashboard no longer freeze the UI, run proportional to what's deleted instead of rebuilding full lifetime summaries, retry safely if the delete worker crashes, and no longer rescan the whole library when deleting very common words; a new index also makes large session deletes drop from minutes to milliseconds. Library merges, video moves, and AniList reassignments got the same lifetime-summary fix.
+- **Vocabulary Stats Accuracy**: Vocabulary totals and charts now count all tracked vocabulary instead of only the first page, new-word history uses corrected daily rollups (fixing legacy timestamp and time-zone issues), summary cards refresh automatically after edits to the exclusion list, and rapid exclusion edits no longer race each other.
+- **Rofi MKV Thumbnails**: Fixed missing MKV thumbnails in the Linux rofi picker when system thumbnailer registrations only advertise legacy Matroska MIME aliases.
+
+<details>
+<summary>Internal changes</summary>
+
+### Internal
+- Docs Site Indexing: Excluded the `/main/` and `/v/<version>/` docs trees from search indexing (self-referential canonical, `noindex,follow`, matching `X-Robots-Tag`) so crawlers focus on current docs instead of ~30 archived copies of every page, and restored `<lastmod>` dates in the docs sitemap that were silently dropped by production builds.
+
+</details>
+
 ## v0.19.3 (2026-08-13)

 ### Added
@@ -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 +0,0 @@
-type: fixed
-area: subtitles
-
- Typeset ASS karaoke and animated signs no longer flood the primary overlay, subtitle sidebar, immersion history, or sentence mining with repeated glyph fragments or full-line color phases. Matching timed comments and full-line boundary events recover the complete authored line without merging ordinary repeated dialogue or separately positioned signs, and dialogue spoken while a song's animation is on screen is kept intact instead of being replaced by the lyric. Entrance and exit frames that run past the authored line timing still resolve to the clean line during lyric transitions, and dialogue spoken while a song's animation is on screen enters immersion and subtitle history without the fragment lines beside it.
- The secondary subtitle overlay drops layered duplicate lines from animated tracks, so a short stack of repeated words collapses to its distinct lines even when the full karaoke heuristic does not apply.
@@ -1,4 +0,0 @@
-type: fixed
-area: Anki media
-
- Fixed sentence-audio generation timing out on slow network-mounted MKV files with many subtitle and font-attachment streams. Selected audio tracks now use bounded FFmpeg probing and a two-minute extraction budget, and missing output reports a clear FFmpeg error instead of raw `ENOENT`.
@@ -1,5 +0,0 @@
-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.
@@ -1,5 +0,0 @@
-type: fixed
-area: dictionary
-
- Character dictionary generation, merged rebuilds, and imports no longer freeze the app (and trigger the compositor's "application not responding" dialog) on large dictionaries; snapshot reads/writes, archive building, and the character image/name lookup caches now do their heavy work off the UI's critical path.
- Desktop progress notifications now update in place on Linux AppImage installs too: the AppImage's bundled libraries broke the system notify-send helper, which silently forced the flickering close-and-reopen notification fallback.
@@ -1,5 +0,0 @@
-type: internal
-area: docs
-
- Excluded the `/main/` and `/v/<version>/` docs trees from search indexing with a self-referential canonical, `noindex,follow`, and a matching `X-Robots-Tag` header, so crawlers spend their budget on the current docs instead of ~30 archived copies of every page.
- Restored `<lastmod>` dates in the docs sitemap, which were silently dropped because production builds render from an untracked release snapshot.
@@ -1,5 +0,0 @@
-type: fixed
-area: stats
-
- Typeset subtitles no longer flood the stats. Karaoke openings and animated signs are authored as one subtitle event per animation frame, and immersion tracking counted every frame, which was enough to put an OP lyric at the top of "Top Repeated Words" for good. Lines are now collapsed on the way in using the same rules the subtitle sidebar already applies: matching parsed timings record exactly the cues the sidebar shows, while shifted, changing, or unparsed sources use a strict fallback where identical, contiguous, sub-0.1s lines stop counting after a few frames. Ordinary repeated dialogue and rewatches are unaffected.
- Added a cleanup for stats already affected. The Vocabulary tab has a **Duplicates** button that scans a chosen window (7 days through all time), shows the bursts it found and the word and kanji counts they added, and collapses each run to one line once confirmed. `subminer stats cleanup --duplicate-lines` does the same from the terminal, with `--dry-run` and `--lookback-days <n>`. Only subtitle lines and the vocabulary counts they feed are touched; watch time and lines-seen totals are left as recorded.
@@ -1,5 +0,0 @@
-type: fixed
-area: overlay
-
- Dedicated overlay modals are prewarmed on macOS and Windows so shortcuts open them promptly on the first press. Windows now refreshes the hidden modal renderer between sessions to keep later modals interactive. On macOS, reused modals and the in-app stats window also open above fullscreen mpv on its current Space instead of appearing on another desktop or forcing a Space change.
- Updated subtitle ASS observation to mpv's current `sub-text/ass` property, removing its deprecation warning.
@@ -1,4 +0,0 @@
-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 +0,0 @@
-type: fixed
-area: overlay
-
- Fixed the overlay getting stuck on "Overlay loading" forever when startup stalls: mpv IPC connection attempts now time out and retry, switching sockets aborts obsolete attempts, and the plugin replaces its spinner with an actionable error if overlay content is still not ready after 30 seconds.
@@ -1,4 +0,0 @@
-type: fixed
-area: overlay
-
- Fixed native Wayland drag-and-drop from file managers such as Thunar so subtitle and video files dropped on the visible overlay are resolved and forwarded to mpv.
@@ -1,4 +0,0 @@
-type: fixed
-area: subtitles
-
- 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 +0,0 @@
-type: fixed
-area: overlay
-
- Secondary subtitles now parse the selected ASS/SRT/VTT source with the primary subtitle deduplication pipeline, preventing layered animation text from appearing several times in the overlay, mined cards, and statistics. Fragmented ASS karaoke keeps spaces authored at event boundaries instead of joining every word together. 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 one concatenated secondary line. Live mpv text remains the fallback for unreadable tracks and applies full-line duplicate filtering before display.
@@ -1,4 +0,0 @@
-type: fixed
-area: overlay
-
- Fixed system-wide mouse lag on Windows while SubMiner is running: the overlay no longer installs Electron's global mouse hook for click-through forwarding, and the mpv window tracker no longer blocks the app on repeated PowerShell command-line lookups.
@@ -1,6 +0,0 @@
-type: added
-area: stats
-
- Library: duplicate cards for the same show can now be combined. Press "Select" above the library grid, tick the cards, and use "Merge Selected"; the dialog picks which entry to keep and moves every episode onto it. Sessions, mined cards, and watch time are preserved, the emptied entries disappear, and remembered title aliases keep future episodes on the merged card.
- Library: episodes can be reassigned to another library entry from the "→" button on an episode row, which is the fix when one file lands under a stray title (e.g. an episode name parsed as the series). Manual assignments now survive later filename parsing, Jellyfin refreshes, and season repair. Local episodes in the same directory reuse a uniquely corrected destination unless they parse to a title that already has its own library entry, while conflicting seasons or manual destinations are not forced together. Emptying an entry this way removes it and returns to the grid.
- Library: exact AniList title matches with compatible seasons fold duplicate cards automatically. Fuzzy same-AniList matches appear as dismissible "Possible duplicate" reviews instead of changing the library without confirmation; conflicting explicit seasons are left alone.
@@ -1,4 +0,0 @@
-type: fixed
-area: notifications
-
- Character dictionary progress notifications on Linux now update in place instead of flickering off and reappearing on every status change.
@@ -1,4 +0,0 @@
-type: fixed
-area: anki
-
- Mined audio and animated AVIF clips now capture the subtitle line that was actually mined. The clip range is snapshotted once at Yomitan lookup time (and reused for both audio and image), instead of each generator reading the live mpv subtitle when it starts — which clipped whatever line was on screen after slow audio extraction finished, producing too-short or misaligned AVIF clips.
@@ -1,4 +0,0 @@
-type: fixed
-area: launcher
-
- Fixed missing MKV thumbnails in the Linux rofi picker when system thumbnailer registrations only advertise legacy Matroska MIME aliases.
@@ -1,9 +0,0 @@
-type: fixed
-area: stats
-
- Stats deletes no longer freeze the stats dashboard: the delete worker module now resolves when running from source, so deletes actually run off the serving thread instead of silently falling back to it.
- Deletes now subtract their exact contribution from lifetime summaries instead of rebuilding them from retained sessions, making delete cost proportional to what is deleted and preserving lifetime totals older than the session retention window.
- If the delete worker crashes, the delete now retries on the current thread instead of failing.
- Library merges, video moves, AniList reassignments, and `subminer stats cleanup -l` also stopped rebuilding lifetime summaries from retained sessions; they now recompute from per-episode history, so those operations are faster and no longer erase lifetime totals older than the session retention window.
- Deleting content that contains very common words no longer rescans every occurrence of those words across the whole library; first/last-seen dates are refreshed with index seeks instead.
- Session deletes on large databases dropped from minutes to milliseconds: an index on the subtitle-line event reference now prevents each deleted session event from scanning the whole subtitle-line table for foreign-key enforcement.
@@ -1,8 +0,0 @@
-type: fixed
-area: stats
-
- Fixed Vocabulary totals and charts counting only the first browsing page instead of all tracked vocabulary, without delaying the rest of the page.
- New-word history now uses permanent daily lexical rollups that apply the same vocabulary filters as the totals and normalize legacy second/millisecond timestamps; versioned background rebuilds repair existing history across legacy rollup-state schemas without dropping playback writes or clearing watch-time, activity, efficiency, and library charts.
- Calendar-day chart labels now preserve the recorded local date in time zones west of UTC.
- Vocabulary summary cards and charts refresh automatically after the word exclusion list changes, and failed or unfinished loads use bounded retries before showing an inline error with a Retry control.
- Rapid exclusion edits no longer race each other; writes are sent in order so a slower earlier save cannot overwrite a newer list.
@@ -1,5 +1,33 @@
 # Changelog

+## v0.19.4 (2026-08-25)
+
+**Added**
+- **Library Merge & Move**: Duplicate library cards for the same show can now be combined. Select cards in the library grid and use "Merge Selected" to pick which entry to keep and move every episode onto it, preserving sessions, mined cards, and watch time. Episodes can also be reassigned individually via the "→" button, useful when a file lands under a stray title; manual assignments survive later filename parsing, Jellyfin refreshes, and season repair. Exact AniList title matches with compatible seasons now merge automatically, while fuzzy matches surface as dismissible "Possible duplicate" reviews instead of merging silently.
+- **Duplicate Line Cleanup Tool**: The Vocabulary tab's new "Duplicates" button scans a chosen time window (7 days through all time) for old karaoke/typeset duplicate-line bursts, shows what it found, and collapses each run to one line once confirmed; `subminer stats cleanup --duplicate-lines` does the same from the terminal, with `--dry-run` and `--lookback-days <n>` options. Watch time and lines-seen totals are left unchanged.
+
+**Changed**
+- **Prerelease Release Notes**: Prerelease notes now open with a "Changes since" section listing only what changed versus the previous beta/RC of the same version, above the cumulative highlights, and CI rejects prerelease tags whose committed notes were generated for a different beta/RC.
+
+**Fixed**
+- **Subtitle & Karaoke Duplication**: Typeset ASS karaoke and animated signs no longer flood the overlay, subtitle sidebar, immersion history, mining, or stats with glyph fragments, per-frame color phases, or repeated animation events. Lines are reconstructed once from their authored text and shown only while actually sung, with original word spacing preserved. Decorative layers (highlight sweeps, glow/shadow copies, symbol-font decoration, particle swarms, hidden or zero-scaled text) stay out of published text, while ordinary repeated dialogue, positioned signs, wrapped lyric rows, and multi-row CC-style blocks still display correctly. Embedded subtitle tracks on network-mounted (SMB/NFS) media are extracted and parsed again instead of falling back to live-text-only, restoring karaoke reconstruction, sidebar cues, and mining for releases that only ship subtitles inside the container. Secondary subtitles now go through the same deduplication pipeline as primary subtitles and no longer clip display after about four lines. Event-heavy karaoke files that previously stalled subtitle loading for several seconds now parse in well under a second.
+- **Character Dictionary Reliability**: Character dictionary generation, merged rebuilds, and imports no longer freeze the app on large dictionaries. Snapshot I/O, archive building, and image/name lookup caches moved off the UI's critical path. Dictionaries are reused instead of regenerated when MeCab finds no name splits, and cached portraits now restore correctly after the portrait index finishes loading post-tokenization. Desktop progress notifications on Linux AppImage installs now update in place instead of flickering, fixing a bug where the AppImage's bundled libraries broke the system notification helper.
+- **Overlay Startup & Modals**: Fixed several causes of the overlay getting stuck on "Overlay loading": the macOS window-tracking helper now targets macOS 12.0+ instead of requiring the build machine's exact macOS version (previously crashed on older systems like Ventura), and mpv IPC connection attempts now time out and retry, showing an actionable error if content still isn't ready after 30 seconds. Dedicated overlay modals are also prewarmed on macOS and Windows so shortcuts open them promptly, and on macOS reused modals and the stats window now open above fullscreen mpv on its current Space instead of jumping to another desktop.
+- **Wayland File Drop**: Fixed native Wayland drag-and-drop from file managers such as Thunar, so subtitle and video files dropped on the visible overlay are resolved and forwarded to mpv.
+- **Windows Mouse Lag**: Fixed system-wide mouse lag on Windows while SubMiner is running, caused by the overlay's global mouse hook for click-through forwarding and by the mpv window tracker blocking the app on repeated PowerShell lookups.
+- **Sentence Mining Audio & Clips**: Sentence-audio generation no longer times out on slow network-mounted media with many subtitle/font streams (bounded FFmpeg probing, two-minute extraction budget, clearer error reporting), and mined audio/animated AVIF clips now capture the subtitle line that was actually mined by snapshotting the clip range at lookup time instead of reading live mpv state later.
+- **Stats Performance & Reliability**: Immersion stats storage now sets its SQLite busy timeout before WAL setup, avoiding transient lock errors under concurrent writes. Deletes in the stats dashboard no longer freeze the UI, run proportional to what's deleted instead of rebuilding full lifetime summaries, retry safely if the delete worker crashes, and no longer rescan the whole library when deleting very common words; a new index also makes large session deletes drop from minutes to milliseconds. Library merges, video moves, and AniList reassignments got the same lifetime-summary fix.
+- **Vocabulary Stats Accuracy**: Vocabulary totals and charts now count all tracked vocabulary instead of only the first page, new-word history uses corrected daily rollups (fixing legacy timestamp and time-zone issues), summary cards refresh automatically after edits to the exclusion list, and rapid exclusion edits no longer race each other.
+- **Rofi MKV Thumbnails**: Fixed missing MKV thumbnails in the Linux rofi picker when system thumbnailer registrations only advertise legacy Matroska MIME aliases.
+
+<details>
+<summary>Internal changes</summary>
+
+**Internal**
+- Docs Site Indexing: Excluded the `/main/` and `/v/<version>/` docs trees from search indexing (self-referential canonical, `noindex,follow`, matching `X-Robots-Tag`) so crawlers focus on current docs instead of ~30 archived copies of every page, and restored `<lastmod>` dates in the docs sitemap that were silently dropped by production builds.
+
+</details>
+
 ## v0.19.3 (2026-08-13)

 **Added**
@@ -108,9 +108,11 @@ 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. Long lines repeated as dialogue and positioned signs are treated as the same line 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. When SubMiner must use mpv's live text as a fallback, it still filters full-line duplicates while preserving short repeated dialogue.
+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

@@ -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.
@@ -87,7 +87,9 @@ interface SubtitleCue {

 ASS scripts can also redraw one complete lyric for two or more long color/highlight phases. Those flush-timed phases collapse separately from short animation frames when they share text, style, actor, and layer and carry direct animation evidence, such as temporal tags or changing non-spatial overrides. Spatial command changes do not prove a phase, so separately positioned signs remain distinct.

-**Canonical animation recovery.** Some ASS producers keep the readable lyric or sign as a timed `Comment:` and generate hundreds of `Dialogue:` frames containing repeated glyphs or changing clip regions. Others retain the complete line as brief `Dialogue:` events around the generated fragments. A complete event is promoted only when nearby dialogue from the same style and actor forms a proven animation cluster and reconstructs its entire text in source order. The generated frames are then replaced by one cue marked `source: 'canonical-ass'`. This source marker lets the live primary-subtitle path prefer the clean authored text and timing for display, sidebar history, immersion recording, and mining, while unmatched editor notes and alternative translations remain ignored.
+**Canonical animation recovery.** Some ASS producers keep the readable lyric or sign as a timed `Comment:` and generate hundreds of `Dialogue:` frames containing repeated glyphs or changing clip regions. Others retain the complete line as brief `Dialogue:` events around the generated fragments. A complete event is promoted only when nearby dialogue from the same style and actor forms a proven animation cluster and reconstructs its entire text in source order. The generated frames are then replaced by one cue marked `source: 'canonical-ass'`. This source marker lets the live primary-subtitle path prefer the clean authored text and timing for display, sidebar history, immersion recording, and mining, while unmatched editor notes and alternative translations remain ignored. Secondary selection advances to an entering canonical cue at its generated animation start when the preceding authored cue ends before the new authored span. Unrelated simultaneous cues that continue through the new span remain visible.
+
+**Font texture cleanup.** A clipped repeated-glyph run or frequent changes to secondary alpha marks a texture seed. Clipped runs do not need a font override because some signs build their masks from ordinary `l` glyphs. The parser removes short clipped pieces that share a no-font seed's style and timing, or pieces that share a font seed's style, timing, and font even when the actor changes. It also removes positioned text layers with at least `E0` global alpha when they overlap a seed in the same style. Opaque authored sign text stays publishable when the texture switches fonts or actors around it.

 #### Prefetch Service Lifecycle

@@ -97,20 +97,31 @@ 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.
- Parsed secondary text and the live fallback share a flattened-line identity for long lines. This
-  removes dialogue/sign repetitions that differ only in whitespace or terminal punctuation while
-  retaining short repeated lines that can represent authored dialogue without source metadata.
+- `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 positioned parts that span multiple vertical rows as a grid.
-  Secondary text omits those grids instead of flattening a translated table or schedule into one
-  synthetic line. Reconstructed single-line karaoke remains eligible for display.
+- 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.
@@ -119,10 +130,12 @@ coming and prefetching would otherwise idle for the rest of the cue.
 - 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, while scripts that discarded their word boundaries remain compact
-  instead of gaining false 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.
+  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.
@@ -2,7 +2,7 @@
  "name": "subminer",
  "productName": "SubMiner",
  "desktopName": "SubMiner.desktop",
-  "version": "0.19.4-beta.4",
+  "version": "0.19.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",
@@ -0,0 +1,78 @@
+## Highlights
+### Added
+- **Library Duplicate & Misfiled Episode Tools**
+  - Merge duplicate show cards from the Library grid: select cards and use "Merge Selected" to combine sessions, mined cards, and watch time onto one entry while keeping remembered title aliases.
+  - Reassign a misfiled episode to the correct show with the "→" button on an episode row; the fix survives later filename parsing, Jellyfin refreshes, and season repair.
+  - Exact AniList matches merge automatically, while likely (fuzzy) matches surface as a dismissible "Possible duplicate" suggestion instead of merging without confirmation.
+- **Stats Duplicate-Line Cleanup Tool**
+  - The Vocabulary tab's new Duplicates button scans a chosen time window for old karaoke/animation duplicate bursts and collapses each one to a single line after you confirm, without touching watch time or lines-seen totals.
+  - The same cleanup is available from the terminal via `subminer stats cleanup --duplicate-lines`, with `--dry-run` and `--lookback-days` options.
+
+### Changed
+- **Prerelease Notes "Changes Since" Section**
+  - Prerelease release notes now open with a "Changes since" section listing only what changed since the previous beta/RC of the same version, shown above the full cumulative highlights.
+
+### Fixed
+- **Subtitle Deduplication & Karaoke Reconstruction**
+  - Typeset ASS karaoke and animated signs are reconstructed into their authored line and shown once, instead of flooding the overlay, subtitle sidebar, immersion history, sentence mining, and stats with per-frame glyph fragments and repeated lyric bursts (a lyric could previously pin itself to the top of "Top Repeated Words").
+  - The same deduplication now applies consistently everywhere, including embedded subtitles extracted from network-mounted (SMB/NFS) media and the secondary subtitle overlay, while ordinary repeated dialogue, signs, and rewatches remain unaffected.
+  - Secondary subtitle overlays no longer clip long lines after about four rows, and no longer show scattered-letter or duplicated text while embedded subtitles are still being extracted.
+- **Character Dictionary Reliability & Notifications**
+  - Character dictionary generation, rebuilds, and imports no longer freeze the app or trigger "not responding" dialogs on large dictionaries; the heavy work now runs off the main UI thread.
+  - Dictionaries are reused instead of being regenerated on every launch when no name splits were found, and portraits reappear correctly once the cached portrait index finishes loading.
+  - Linux desktop progress notifications, including on AppImage installs, now update in place instead of flickering closed and reopening.
+- **Overlay Startup Reliability**
+  - The overlay no longer gets stuck on an endless "Overlay loading" screen when mpv's connection stalls at startup; connections now time out and retry, and a clear error appears if content still isn't ready after 30 seconds.
+- **Overlay Modal Windows (macOS & Windows)**
+  - Modal windows such as Settings prewarm so shortcuts open them promptly on first press.
+  - On Windows, the hidden modal renderer now refreshes between sessions so later modals stay interactive.
+  - On macOS, reused modals and the stats window open above fullscreen mpv on the correct Space instead of jumping to another desktop; the overlay-attach helper also now supports macOS 12.0+, fixing "Overlay loading" getting stuck on older macOS versions.
+- **Windows Mouse Lag**
+  - Fixed system-wide mouse lag while SubMiner is running: the overlay no longer installs a global mouse hook, and the mpv window tracker no longer blocks the app with repeated command-line lookups.
+- **Linux Overlay & Launcher Fixes**
+  - Native Wayland drag-and-drop from file managers such as Thunar now works, so subtitle and video files dropped on the overlay reach mpv.
+  - Fixed missing MKV thumbnails in the rofi file picker on systems that only advertise legacy Matroska MIME aliases.
+- **Sentence Mining Audio & Clip Accuracy**
+  - Sentence-audio generation no longer times out on slow network-mounted MKV files with many subtitle/font streams; probing is now bounded with a two-minute extraction budget and a clear error instead of a raw failure.
+  - Mined audio and animated clips now capture the exact subtitle line that was mined, instead of whatever line was on screen after audio extraction finished, fixing too-short or misaligned clips.
+- **Stats Reliability & Performance**
+  - Fixed transient database-lock errors when multiple stats workers wrote at once.
+  - Stats deletes, library merges, video moves, and AniList reassignments no longer freeze the dashboard or rebuild lifetime totals from scratch, so they're fast and preserve lifetime totals older than the recent session-retention window; session deletes on large databases dropped from minutes to milliseconds.
+- **Vocabulary Tab Accuracy**
+  - Vocabulary totals and charts now count all tracked vocabulary instead of only the first page, with new-word history rebuilt from corrected daily rollups to match.
+  - Calendar charts keep the correct local date in time zones west of UTC, and vocabulary cards/charts now refresh automatically and retry after the word exclusion list changes.
+
+## What's Changed
+
+- feat(stats): add library entry merge and episode move by @ksyasuda in #190
+- fix(stats): stop counting duplicate typeset subtitle lines by @ksyasuda in #191
+- fix(media): tolerate slow MKV audio extraction by @ksyasuda in #195
+- fix(stats): subtract lifetime totals incrementally on delete by @ksyasuda in #196
+- fix(anki): snapshot mining media clip timing by @ksyasuda in #197
+- fix(notifications): replace Linux progress updates in place by @ksyasuda in #198
+- fix(overlay): support native Wayland file drag-and-drop by @ksyasuda in #199
+- fix(overlay): keep macOS modal windows on fullscreen Spaces by @ksyasuda in #200
+- fix(overlay): prevent Windows mouse lag during click-through tracking by @ksyasuda in #201
+- 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
+- fix(subtitles): improve secondary subtitle extraction and display by @ksyasuda in #215
+- feat(release): track prerelease deltas and validate committed notes by @ksyasuda in #216
+- fix(subtitles): recover positioned ASS word spacing and drop control debris by @ksyasuda in #217
+
+## Installation
+
+See the README and docs/installation guide for full setup steps.
+
+## Assets
+
+- Linux: `SubMiner.AppImage`
+- macOS: `SubMiner-*.dmg` and `SubMiner-*.zip`
+- Windows: `SubMiner-*.exe` and `SubMiner-*-win.zip`
+- Optional extras: `subminer-assets.tar.gz` and the `subminer` launcher
+
+Note: the `subminer` wrapper script uses Bun (`#!/usr/bin/env bun`), so `bun` must be installed and on `PATH`.
@@ -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;
@@ -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}`);
 }

@@ -35,6 +35,12 @@ test('parseSrtCues handles multi-line subtitle text', () => {
  assert.equal(cues[0]!.text, 'これは\nテストです');
 });

+test('parseSrtCues preserves lines that only resemble malformed ASS controls', () => {
+  const content = ['1', '00:01:00,000 --> 00:01:05,000', '\\', '{\\fr0', ''].join('\n');
+
+  assert.equal(parseSrtCues(content)[0]?.text, '\\\n{\\fr0');
+});
+
 test('parseSrtCues strips HTML-like markup while preserving line breaks', () => {
  const content = [
    '1',
@@ -550,6 +556,29 @@ test('parseSubtitleCues recovers a full Dialogue line surrounding generated frag
  ]);
 });

+test('parseSubtitleCues replaces animated glyph copies of a static canonical Dialogue line', () => {
+  const content = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    'Dialogue: 1,0:00:01.00,0:00:04.00,OP - JP,,0,0,0,,重複字幕',
+    'Dialogue: 2,0:00:01.00,0:00:04.00,OP - JP,,0,0,0,,{\\pos(400,50)\\t(0,100,\\fry0)}重',
+    'Dialogue: 2,0:00:01.10,0:00:04.00,OP - JP,,0,0,0,,{\\pos(440,50)\\t(0,100,\\fry0)}複',
+    'Dialogue: 2,0:00:01.20,0:00:04.00,OP - JP,,0,0,0,,{\\pos(480,50)\\t(0,100,\\fry0)}字',
+    'Dialogue: 2,0:00:01.30,0:00:04.00,OP - JP,,0,0,0,,{\\pos(520,50)\\t(0,100,\\fry0)}幕',
+  ].join('\n');
+
+  assert.deepEqual(parseSubtitleCues(content, 'test.ass'), [
+    {
+      startTime: 1,
+      endTime: 4,
+      text: '重複字幕',
+      source: 'canonical-ass',
+      animationStartTime: 1,
+      animationEndTime: 4,
+    },
+  ]);
+});
+
 test('parseSubtitleCues does not promote a short animated fragment as a complete line', () => {
  const content = [
    '[Events]',
@@ -1021,3 +1050,950 @@ test('parseSubtitleCues detects subtitle formats from remote URLs', () => {
  assert.equal(cues.length, 1);
  assert.equal(cues[0]!.text, 'URLテスト');
 });
+
+test('parseSubtitleCues skips zero-duration ASS metadata events', () => {
+  const content = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    'Dialogue: 0,0:00:00.00,0:00:00.00,Default,,0,0,0,,[Script Info]',
+    'Dialogue: 0,0:00:01.00,0:00:02.00,Default,,0,0,0,,Real subtitle',
+  ].join('\n');
+
+  assert.deepEqual(parseSubtitleCues(content, 'test.ass'), [
+    { startTime: 1, endTime: 2, text: 'Real subtitle' },
+  ]);
+});
+
+test('parseSubtitleCues drops malformed ASS spacer reset debris', () => {
+  const content = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    'Dialogue: 0,0:00:01.00,0:00:02.00,Background,,0,0,0,,{\\pos(10,10)}\\h\\h\\h\\{\\fr0',
+    'Dialogue: 1,0:00:01.00,0:00:02.00,Default,,0,0,0,,Visible line',
+  ].join('\n');
+
+  assert.deepEqual(parseSubtitleCues(content, 'test.ass'), [
+    { startTime: 1, endTime: 2, text: 'Visible line' },
+  ]);
+});
+
+test('parseSubtitleCues recovers spaces encoded only by positioned Latin glyph gaps', () => {
+  const glyphs = [
+    ['T', 100],
+    ['h', 118],
+    ['e', 136],
+    ['s', 164],
+    ['t', 178],
+    ['a', 194],
+    ['r', 210],
+    ['s', 227],
+    ['I', 255],
+    ['s', 275],
+    ['e', 293],
+    ['e', 311],
+  ] as const;
+  const content = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    ...[0, 1].flatMap((layer) =>
+      glyphs.map(
+        ([glyph, x], index) =>
+          `Dialogue: ${layer},0:00:01.00,0:00:04.00,OP English,,0,0,0,,{\\pos(${x},110)\\t(${index * 2},${index * 2 + 100},\\fscx120)}${glyph}`,
+      ),
+    ),
+  ].join('\n');
+
+  assert.equal(parseSubtitleCues(content, 'test.ass')[0]?.text, 'The stars I see');
+});
+
+test('parseSubtitleCues does not split narrow letters inside positioned English words', () => {
+  const text = 'carryinghappiness';
+  const positions = [
+    323, 341, 356, 369, 383, 396, 410, 428, 456, 474, 493, 512, 526, 540, 558, 575, 590,
+  ];
+  const content = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    ...[0, 1].flatMap((layer) =>
+      [...text].map(
+        (glyph, index) =>
+          `Dialogue: ${layer},0:00:01.00,0:00:04.00,OP English,,0,0,0,,{\\pos(${positions[index]},110)\\t(${index * 2},${index * 2 + 100},\\fscx120)}${glyph}`,
+      ),
+    ),
+  ].join('\n');
+
+  assert.equal(parseSubtitleCues(content, 'test.ass')[0]?.text, 'carrying happiness');
+});
+
+test('parseSubtitleCues keeps proportional-font variation inside positioned English words', () => {
+  const text = 'sendsripplesacrossthestillnessofyourheart';
+  const positions = [
+    32, 46, 60, 78, 95, 121, 131, 144, 163, 177, 189, 203, 232, 248, 261, 274, 288, 302, 329, 346,
+    363, 390, 405, 416, 423, 432, 443, 457, 471, 485, 512, 525, 551, 564, 579, 593, 622, 639, 655,
+    670, 684,
+  ];
+  const content = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    ...[0, 1].flatMap((layer) =>
+      [...text].map(
+        (glyph, index) =>
+          `Dialogue: ${layer},0:00:01.00,0:00:04.00,Insert English,,0,0,0,,{\\pos(${positions[index]},110)\\t(${index * 2},${index * 2 + 100},\\fscx120)}${glyph}`,
+      ),
+    ),
+  ].join('\n');
+
+  assert.equal(
+    parseSubtitleCues(content, 'test.ass')[0]?.text,
+    'sends ripples across the stillness of your heart',
+  );
+});
+
+test('parseSubtitleCues keeps a short capitalized word when the following gap is larger', () => {
+  const text = 'IfIgrow';
+  const positions = [347, 365, 397, 430, 446, 463, 485];
+  const content = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    ...[0, 1].flatMap((layer) =>
+      [...text].map(
+        (glyph, index) =>
+          `Dialogue: ${layer},0:00:01.00,0:00:04.00,Insert English,,0,0,0,,{\\pos(${positions[index]},110)\\t(${index * 2},${index * 2 + 100},\\fscx120)}${glyph}`,
+      ),
+    ),
+  ].join('\n');
+
+  assert.equal(parseSubtitleCues(content, 'test.ass')[0]?.text, 'If I grow');
+});
+
+// Geometry taken from a real per-glyph ED line. The `waves within` gap crosses a wide
+// `w`, so the width-normalized ratio reads it as a common advance; only the constant
+// extra distance of the authored word space gives it away.
+test('parseSubtitleCues recovers a word gap measured across a wide glyph', () => {
+  const text = 'youcanhearthesoundofthewaveswithinmyheart';
+  const positions = [
+    202, 223, 244, 274, 296, 317, 346, 367, 389, 408, 433, 450, 470, 499, 517, 538, 557, 578, 609,
+    627, 651, 668, 688, 723, 748, 770, 792, 811, 843, 863, 875, 892, 907, 922, 957, 983, 1013, 1034,
+    1055, 1075, 1090,
+  ];
+  const content = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    ...[0, 1].flatMap((layer) =>
+      [...text].map(
+        (glyph, index) =>
+          `Dialogue: ${layer},0:00:01.00,0:00:04.00,ED English,,0,0,0,,{\\pos(${positions[index]},687)\\t(${index * 2},${index * 2 + 100},\\fscx120)}${glyph}`,
+      ),
+    ),
+  ].join('\n');
+
+  assert.equal(
+    parseSubtitleCues(content, 'test.ass')[0]?.text,
+    'you can hear the sound of the waves within my heart',
+  );
+});
+
+// A single short word gives too few gap samples to trust the excess rule: its narrow
+// glyphs skew the common advance low and `w e` would read as a word gap.
+test('parseSubtitleCues does not split a short single positioned word', () => {
+  const text = 'Swelling';
+  const positions = [592, 613, 635, 647, 655, 662, 673, 689];
+  const content = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    ...[0, 1].flatMap((layer) =>
+      [...text].map(
+        (glyph, index) =>
+          `Dialogue: ${layer},0:00:01.00,0:00:04.00,ED English,,0,0,0,,{\\pos(${positions[index]},682)\\t(${index * 2},${index * 2 + 100},\\fscx120)}${glyph}`,
+      ),
+    ),
+  ].join('\n');
+
+  assert.equal(parseSubtitleCues(content, 'test.ass')[0]?.text, 'Swelling');
+});
+
+// A capitalized word whose first letter sits before a wide glyph (`S|miles`) overruns
+// the width table; the excess rule must not split a capital from its lowercase run.
+test('parseSubtitleCues keeps a capitalized word intact under the excess rule', () => {
+  const text = 'Smilesarebudding';
+  const positions = [37, 63, 80, 88, 99, 113, 142, 157, 171, 201, 217, 235, 255, 269, 280, 295];
+  const content = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    ...[0, 1].flatMap((layer) =>
+      [...text].map(
+        (glyph, index) =>
+          `Dialogue: ${layer},0:00:01.00,0:00:04.00,ED English,,0,0,0,,{\\pos(${positions[index]},682)\\t(${index * 2},${index * 2 + 100},\\fscx120)}${glyph}`,
+      ),
+    ),
+  ].join('\n');
+
+  assert.equal(parseSubtitleCues(content, 'test.ass')[0]?.text, 'Smiles are budding');
+});
+
+// Mirrors a real ED: per-syllable romaji at y=34 overlaid with animated single letters
+// at y=29 rendered through `\fn` in a symbol font, where `a` draws as a sparkle. The
+// letters must neither join the reconstructed line nor survive as their own cues.
+test('parseSubtitleCues drops symbol-font glyph decoration from a reconstructed line', () => {
+  const syllables = [
+    ['so', 479],
+    ['t', 505],
+    ['to', 529],
+    ['mi', 577],
+    ['mi', 618],
+    ['ni', 663],
+    ['a', 699],
+    ['te', 728],
+    ['ru', 764],
+    ['to', 810],
+  ] as const;
+  const decoration = [
+    ['a', 479, '0:00:01.25'],
+    ['z', 577, '0:00:02.51'],
+    ['x', 618, '0:00:02.78'],
+    ['q', 505, '0:00:04.20'],
+  ] as const;
+  const content = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    ...[0, 1].flatMap((layer) =>
+      syllables.map(
+        ([syllable, x], index) =>
+          `Dialogue: ${layer},0:00:01.00,0:00:05.37,ED Romaji,,0,0,0,fx,{\\an5\\pos(${x},34)\\t(${index * 2},${index * 2 + 100},\\fscx120)}${syllable}`,
+      ),
+    ),
+    ...decoration.map(
+      ([glyph, x, start]) =>
+        `Dialogue: 0,${start},0:00:05.37,ED Romaji,,0,0,0,fx,{\\pos(${x},29)\\fnSplit splat splodge\\fs28\\t(3870,3970,\\fscx105)}${glyph}`,
+    ),
+  ].join('\n');
+
+  const cues = parseSubtitleCues(content, 'test.ass');
+  assert.equal(cues.length, 1);
+  assert.equal(cues[0]?.text, 'sotto mimi ni ateru to');
+});
+
+test('parseSubtitleCues drops clipped repeated-glyph texture text', () => {
+  const content = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    "Dialogue: 10,0:00:01.00,0:00:04.00,Default,,0,0,0,,I'm blocking them.",
+    'Dialogue: 2,0:00:01.00,0:00:04.00,MarySigns,,0,0,0,,{\\pos(960,80)\\fnSerangkaian Pattern Regular\\clip(800,20,1120,140)}LLLLLLLLLLLLLLLLLLLLLLLL',
+    'Dialogue: 3,0:00:01.00,0:00:04.00,MarySigns,,0,0,0,,{\\pos(960,150)\\fnSF Pro Display}Enter a message',
+  ].join('\n');
+
+  assert.deepEqual(
+    parseSubtitleCues(content, 'test.ass').map((cue) => cue.text),
+    ["I'm blocking them.", 'Enter a message'],
+  );
+});
+
+test('parseSubtitleCues preserves opaque same-font text beside texture fragments', () => {
+  const content = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    'Dialogue: 2,0:00:01.00,0:00:04.00,MarySigns,seed,0,0,0,,{\\pos(960,80)\\fnSerangkaian Pattern Regular\\clip(800,20,1120,140)}LLLLLLLLLLLLLLLLLLLLLLLL',
+    'Dialogue: 2,0:00:01.00,0:00:04.00,MarySigns,piece,0,0,0,,{\\pos(960,110)\\fnSerangkaian Pattern Regular\\clip(800,20,1120,140)}LLLL',
+    'Dialogue: 3,0:00:01.00,0:00:04.00,MarySigns,label,0,0,0,,{\\pos(960,150)\\fnSerangkaian Pattern Regular}Keep this label',
+  ].join('\n');
+
+  assert.deepEqual(
+    parseSubtitleCues(content, 'test.ass').map((cue) => cue.text),
+    ['Keep this label'],
+  );
+});
+
+test('parseSubtitleCues drops tiny alpha payloads from a proven texture font', () => {
+  const content = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    'Dialogue: 2,0:00:01.00,0:00:04.00,FrogSigns,,0,0,0,,{\\pos(580,95)\\fnGrain Medium\\clip(500,40,660,150)}LLLLLLLLLLLL',
+    "Dialogue: 1,0:00:06.00,0:00:09.00,FrogSigns,,0,0,0,,{\\pos(580,95)\\fnGrain\\fs10\\alpha&H70&}q26D'vrA;\\NE? GS\\NESLhlawEv",
+    'Dialogue: 3,0:00:06.00,0:00:09.00,FrogSigns,,0,0,0,,{\\pos(1040,620)\\fnSF Pro Display\\fs66}Waiting!',
+  ].join('\n');
+
+  assert.deepEqual(
+    parseSubtitleCues(content, 'test.ass').map((cue) => cue.text),
+    ['Waiting!'],
+  );
+});
+
+test('parseSubtitleCues preserves a small multiline translation using an unverified transparent font', () => {
+  const content = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    'Dialogue: 2,0:00:01.00,0:00:04.00,Transition,,0,0,0,,{\\pos(580,95)\\fnPhone UI\\fs60\\alpha&HF0&}Faded transition',
+    'Dialogue: 3,0:00:06.00,0:00:09.00,Phone,,0,0,0,,{\\pos(1040,620)\\fnPhone UI\\fs10\\alpha&H70&}Call me when you arrive.\\NI will still be awake.\\NDo not rush.',
+  ].join('\n');
+
+  assert.deepEqual(
+    parseSubtitleCues(content, 'test.ass').map((cue) => cue.text),
+    ['Faded transition', 'Call me when you arrive.\nI will still be awake.\nDo not rush.'],
+  );
+});
+
+test('parseSubtitleCues drops clipped repeated-glyph texture text without a font override', () => {
+  const content = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    'Dialogue: 0,0:00:01.00,0:00:04.00,FrogSigns,,0,0,0,,{\\an7\\pos(736.49,152.99)\\fscy150\\fs10\\bord3\\c&H657BC8&\\3c&H657BC8&\\blur3\\clip}lllllllllllll',
+    'Dialogue: 0,0:00:01.00,0:00:04.00,FrogSigns,,0,0,0,,{\\an7\\pos(769.9,106.18)\\fscy150\\fs12\\bord3\\c&H66729F&\\3c&H66729F&\\blur5\\clip}llll',
+    'Dialogue: 5,0:00:01.00,0:00:04.00,FrogSigns,,0,0,0,,{\\pos(893,311)}Read',
+  ].join('\n');
+
+  assert.deepEqual(
+    parseSubtitleCues(content, 'test.ass').map((cue) => cue.text),
+    ['Read'],
+  );
+});
+
+test('parseSubtitleCues drops per-character alpha texture text', () => {
+  const content = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    "Dialogue: 10,0:00:01.00,0:00:04.00,Default,Girl,0,0,0,,So Doloris was actually Uika-chan from sumimi! That's amazing!",
+    "Dialogue: 2,0:00:01.00,0:00:04.00,MarySigns,,0,0,0,,{\\pos(960,240)\\fnCinzel}Hanasakigawa Girl's School",
+    'Dialogue: 3,0:00:01.00,0:00:04.00,MarySigns,,0,0,0,,{\\pos(960,300)\\fnSplit splat splodge\\clip(800,200,1120,400)}d{\\2a1}s{\\2a0}h{\\2a1}f{\\2a0}k{\\2a1}h{\\2a0}f{\\2a1}s{\\2a0}d{\\2a1}f{\\2a0}e',
+    'Dialogue: 3,0:00:01.00,0:00:04.00,MarySigns,,0,0,0,,{\\pos(980,340)\\fnSplit splat splodge}f {\\2a1}a',
+    'Dialogue: 4,0:00:01.00,0:00:04.00,MarySigns,,0,0,0,,{\\pos(960,360)\\fnGrain SemiBold}5{\\2a1}X{\\2a0}N{\\2a1}T{\\2a0}f{\\2a1}I{\\2a0}g{\\2a1}F{\\2a0}B{\\2a1}?{\\2a0}k{\\2a1}u{\\2a0}C{\\2a1}m',
+  ].join('\n');
+
+  assert.deepEqual(
+    parseSubtitleCues(content, 'test.ass').map((cue) => cue.text),
+    [
+      "So Doloris was actually Uika-chan from sumimi! That's amazing!",
+      "Hanasakigawa Girl's School",
+    ],
+  );
+});
+
+test('parseSubtitleCues drops transparent texture payloads across an animated sign', () => {
+  const content = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    "Dialogue: 90,0:00:01.00,0:00:04.00,Alt,,0,0,0,,Even if you want to see her, she doesn't want to see you!",
+    'Dialogue: 0,0:00:01.00,0:00:01.08,FrogSigns,,0,0,0,,{\\pos(699,803)\\fnSerangkaian Pattern Regular\\clip(300,380,1130,1050)}L{\\2a1}L{\\2a0}L{\\2a1}L{\\2a0}L{\\2a0}L{\\2a0}L{\\2a1}L{\\2a0}L{\\2a1}L{\\2a0}L{\\2a1}L{\\2a0}L{\\2a1}L{\\2a0}L{\\\\\\\\\\\\\\\\\\\\\\',
+    'Dialogue: 3,0:00:01.00,0:00:01.08,FrogSigns,Street,0,0,0,,{\\pos(285,653)\\fnGrain\\alpha&HE0&}Street performance by Mortis from\\NMujica - Acting prodigy in action!',
+    'Dialogue: 5,0:00:01.00,0:00:01.08,FrogSigns,Street,0,0,0,,{\\pos(285,653)\\fnRoboto Medium\\alpha&H00&}Street performance by Mortis from\\NMujica - Acting prodigy in action!',
+    'Dialogue: 6,0:00:01.00,0:00:01.08,FrogSigns,Street,0,0,0,,{\\pos(285,653)\\fnGrain\\alpha&HE0&}H1.4igcAhGYHVWD"kHcVlG2W9eKEWj"!X\\N\'uNVaEVpTXMd9rk7dnRX\'P!RhsS"Wn90k6',
+    'Dialogue: 6,0:00:01.00,0:00:01.08,FrogSigns,18K,0,0,0,,{\\pos(284,821)\\fnGrain\\alpha&HE0&}ou:QepiiPqQ.4n.IYbFaGHtPzWyKI9CUSq:',
+    'Dialogue: 1,0:00:01.08,0:00:04.00,FrogSigns,,0,0,0,,{\\pos(581,921)\\fnSerangkaian Pattern Regular\\clip(195,495,986,1120)}L{\\2a1}L{\\2a0}L{\\2a1}L{\\2a0}L{\\2a1}L{\\2a0}L{\\2a1}L{\\2a0}L{\\2a1}L{\\2a0}L{\\2a1}L{\\2a0}L{',
+    'Dialogue: 3,0:00:01.08,0:00:04.00,FrogSigns,,0,0,0,,{\\pos(151,769)\\fnGrain\\alpha&HE0&}Street performance by Mortis from\\NMujica - Acting prodigy in action!',
+    'Dialogue: 5,0:00:01.08,0:00:04.00,FrogSigns,,0,0,0,,{\\pos(151,769)\\fnRoboto Medium\\alpha&H00&}Street performance by Mortis from\\NMujica - Acting prodigy in action!',
+    'Dialogue: 3,0:00:01.08,0:00:04.00,FrogSigns,,0,0,0,,{\\pos(151,769)\\fnGrain\\alpha&HF0&}9LF\'GpPCTlOkLxBLV:QN,8R8NUVM"ha.s\\NNUUPNTBdJih4jUthK34i,yYe;9EBgLXbET',
+    "Dialogue: 6,0:00:01.08,0:00:04.00,FrogSigns,,0,0,0,,{\\pos(150,936)\\fnGrain\\alpha&HE0&}JS7vl:lD;'PzkCb!bGT;.7TbA.KCkEH0LOk",
+  ].join('\n');
+
+  assert.deepEqual(
+    parseSubtitleCues(content, 'test.ass').map((cue) => cue.text),
+    [
+      'Street performance by Mortis from\nMujica - Acting prodigy in action!',
+      "Even if you want to see her, she doesn't want to see you!",
+      'Street performance by Mortis from\nMujica - Acting prodigy in action!',
+    ],
+  );
+});
+
+test('parseSubtitleCues does not reconstruct short texture pieces under another actor', () => {
+  const content = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    'Dialogue: 4,0:00:01.00,0:00:04.00,FrogSigns,bubble,0,0,0,,{\\pos(245,-102)\\fnSerangkaian Pattern Regular\\clip(224,-1,831,106)}L{\\2a1}L{\\2a0}L{\\2a1}L{\\2a0}L{\\2a1}L{\\2a0}L{\\2a1}L{\\2a0}L{\\2a1}L',
+    'Dialogue: 4,0:00:01.00,0:00:04.00,FrogSigns,read,0,0,0,,{\\pos(917,293)\\alpha&H20&\\fnSerangkaian Pattern Regular\\clip(904,289,1010,336)}L{\\2a0}L{\\2a1}L{\\2a0}L',
+    'Dialogue: 4,0:00:01.00,0:00:04.00,FrogSigns,read,0,0,0,,{\\pos(911,293)\\alpha&H58&\\fnSerangkaian Pattern Regular\\clip(904,289,1010,336)}L{\\2a0}L{\\2a1}L{\\2a0}L',
+    'Dialogue: 4,0:00:01.00,0:00:04.00,FrogSigns,read,0,0,0,,{\\pos(845,300)\\alpha&H00&\\fnSerangkaian Pattern Regular\\clip(904,289,1010,336)}L{\\2a0}L{\\2a1}L{\\2a0}L',
+    'Dialogue: 7,0:00:01.00,0:00:04.00,FrogSigns,read,0,0,0,,{\\pos(907,293)\\alpha&HD0&\\fnSerangkaian Pattern Regular\\clip(891,289,1010,338)}L{\\2a0}L{\\2a1}L{\\2a0}L',
+    'Dialogue: 7,0:00:01.00,0:00:04.00,FrogSigns,read,0,0,0,,{\\pos(911,293)\\alpha&HD0&\\fnSerangkaian Pattern Regular\\clip(891,289,1010,338)}L{\\2a0}L{\\2a1}L{\\2a0}L',
+    'Dialogue: 7,0:00:01.00,0:00:04.00,FrogSigns,read,0,0,0,,{\\pos(922,130)\\alpha&HD0&\\fnSerangkaian Pattern Regular\\clip(891,120,1010,173)}L{\\2a0}L{\\2a1}L{\\2a0}L',
+    'Dialogue: 5,0:00:01.00,0:00:04.00,FrogSigns,,0,0,0,,{\\pos(893,311)\\fnSFProDisplay-Regular-STR}Read 3',
+  ].join('\n');
+
+  assert.deepEqual(
+    parseSubtitleCues(content, 'test.ass').map((cue) => cue.text),
+    ['Read 3'],
+  );
+});
+
+test('parseSubtitleCues separates overlapping positioned English lyric sequences', () => {
+  const fragments = [
+    ['my', 642, '0:00:01.00', '0:00:04.05'],
+    ['song!', 713, '0:00:01.00', '0:00:04.05'],
+    ['I', 533, '0:00:01.67', '0:00:04.09'],
+    ['h', 557, '0:00:01.67', '0:00:04.09'],
+    ['u', 575, '0:00:01.67', '0:00:04.09'],
+    ['m', 597, '0:00:01.67', '0:00:04.09'],
+  ] as const;
+  const content = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    ...[0, 1].flatMap((layer) =>
+      fragments.map(
+        ([text, x, start, end], index) =>
+          `Dialogue: ${layer},${start},${end},OP English,,0,0,0,,{\\pos(${x},110)\\t(${index * 2},${index * 2 + 100},\\fscx120)}${text}`,
+      ),
+    ),
+  ].join('\n');
+
+  assert.equal(parseSubtitleCues(content, 'test.ass')[0]?.text, 'my song! I hum');
+});
+
+const eventsHeader = [
+  '[Events]',
+  'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+];
+
+test('parseSubtitleCues keeps 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 a staggered repeated token publishable', () => {
+  const fragments = [
+    ['dreams', 300, 115, '0:00:01.00'],
+    ['ju', 250, 39, '0:00:01.00'],
+    ['n', 280, 39, '0:00:01.00'],
+    ['jo', 300, 39, '0:00:01.00'],
+    ['u', 330, 39, '0:00:01.00'],
+    ['to', 360, 39, '0:00:01.00'],
+    ['jo', 395, 39, '0:00:01.02'],
+    ['u', 425, 39, '0:00:01.00'],
+    ['ne', 455, 39, '0:00:01.00'],
+    ['tsu!', 485, 39, '0:00:01.00'],
+  ] as const;
+  const content = [
+    ...eventsHeader,
+    ...[0, 1].flatMap((layer) =>
+      fragments.map(
+        ([text, x, y, start], index) =>
+          `Dialogue: ${layer},${start},0:00:04.00,ED Romaji,,0,0,0,,{\\pos(${x},${y})\\t(${index * 2},${index * 2 + 100},\\fscx120)}${text}`,
+      ),
+    ),
+  ].join('\n');
+
+  const cue = parseSubtitleCues(content, 'test.ass')[0];
+  assert.notEqual(cue?.assLayout?.kind, 'fragment-grid');
+});
+
+test('parseSubtitleCues adds a missing word space after positioned punctuation', () => {
+  const fragments = [
+    ['H', 100],
+    ['i,', 119],
+    ['t', 153],
+    ['h', 168],
+    ['e', 186],
+    ['r', 202],
+    ['e', 216],
+  ] as const;
+  const content = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    ...[0, 1].flatMap((layer) =>
+      fragments.map(
+        ([fragment, x], index) =>
+          `Dialogue: ${layer},0:00:01.00,0:00:04.00,OP English,,0,0,0,,{\\pos(${x},110)\\t(${index * 2},${index * 2 + 100},\\fscx120)}${fragment}`,
+      ),
+    ),
+  ].join('\n');
+
+  assert.equal(parseSubtitleCues(content, 'test.ass')[0]?.text, 'Hi, there');
+});
+
+test('parseSubtitleCues does not split a positioned thousands separator', () => {
+  const fragments = [
+    ['1,', 100],
+    ['000', 145],
+    ['0', 185],
+    ['0', 205],
+    ['0', 225],
+  ] as const;
+  const content = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    ...[0, 1].flatMap((layer) =>
+      fragments.map(
+        ([fragment, x], index) =>
+          `Dialogue: ${layer},0:00:01.00,0:00:04.00,OP English,,0,0,0,,{\\pos(${x},110)\\t(${index * 2},${index * 2 + 100},\\fscx120)}${fragment}`,
+      ),
+    ),
+  ].join('\n');
+
+  assert.equal(parseSubtitleCues(content, 'test.ass')[0]?.text, '1,000000');
+});
+
+test('parseSubtitleCues does not split a wide glyph from its punctuated suffix', () => {
+  const fragments = [
+    ['v', 904],
+    ['o', 924],
+    ['i', 939],
+    ['c', 955],
+    ['e', 976],
+    ['r', 1004],
+    ['e', 1021],
+    ['a', 1042],
+    ['c', 1063],
+    ['h', 1083],
+    ['e', 1104],
+    ['d', 1125],
+    ['m', 1161],
+    ['e,', 1193],
+  ] as const;
+  const content = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    ...[0, 1].flatMap((layer) =>
+      fragments.map(
+        ([fragment, x], index) =>
+          `Dialogue: ${layer},0:00:01.00,0:00:04.00,OP English,,0,0,0,,{\\pos(${x},110)\\t(${index * 2},${index * 2 + 100},\\fscx120)}${fragment}`,
+      ),
+    ),
+  ].join('\n');
+
+  assert.equal(parseSubtitleCues(content, 'test.ass')[0]?.text, 'voice reached me,');
+});
+
+test('parseSubtitleCues spaces positioned lyric fragments across authored rows', () => {
+  const fragments = [
+    ['My', 472, 39],
+    ['song!', 543, 39],
+    ['My', 507, 78],
+    ['song!', 578, 78],
+    ['ku', 643, 39],
+    ['chi', 683, 39],
+    ['zu', 722, 39],
+    ['sa', 757, 39],
+    ['n', 783, 39],
+    ['de', 811, 39],
+  ] as const;
+  const content = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    ...[0, 1].flatMap((layer) =>
+      fragments.map(
+        ([fragment, x, y], index) =>
+          `Dialogue: ${layer},0:00:01.00,0:00:04.00,OP Romaji,,0,0,0,,{\\pos(${x},${y})\\t(${index * 2},${index * 2 + 100},\\fscx120)}${fragment}`,
+      ),
+    ),
+  ].join('\n');
+
+  assert.equal(parseSubtitleCues(content, 'test.ass')[0]?.text, 'My song! My song! kuchizusande');
+});
+
+test('parseSubtitleCues recovers positioned word gaps between romaji fragments', () => {
+  const fragments = [
+    ['sa', 380],
+    ['ga', 421],
+    ['shi', 467],
+    ['te', 510],
+    ['ta', 545],
+    ['ha', 593],
+    ['ji', 624],
+    ['ke', 655],
+    ['ta', 693],
+    ['i', 726],
+    ['ro', 749],
+    ['no', 798],
+    ['yu', 849],
+    ['me', 895],
+  ] as const;
+  const content = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    ...[0, 1].flatMap((layer) =>
+      fragments.map(
+        ([fragment, x], index) =>
+          `Dialogue: ${layer},0:00:01.00,0:00:04.00,OP Romaji,,0,0,0,,{\\pos(${x},110)\\t(${index * 2},${index * 2 + 100},\\fscx120)}${fragment}`,
+      ),
+    ),
+  ].join('\n');
+
+  assert.equal(parseSubtitleCues(content, 'test.ass')[0]?.text, 'sagashiteta hajiketa iro no yume');
+});
+
+test('parseSubtitleCues recovers clear word gaps in a short romaji line', () => {
+  const fragments = [
+    ['bo', 542],
+    ['ku', 584],
+    ['wo', 640],
+    ['yo', 697],
+    ['bu', 738],
+  ] as const;
+  const content = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    ...[0, 1].flatMap((layer) =>
+      fragments.map(
+        ([fragment, x], index) =>
+          `Dialogue: ${layer},0:00:01.00,0:00:04.00,OP Romaji,,0,0,0,,{\\pos(${x},110)\\t(${index * 2},${index * 2 + 100},\\fscx120)}${fragment}`,
+      ),
+    ),
+  ].join('\n');
+
+  assert.equal(parseSubtitleCues(content, 'test.ass')[0]?.text, 'boku wo yobu');
+});
+
+test('parseSubtitleCues suppresses a karaoke highlight sweep without publishing it', () => {
+  // Main lyric: per-glyph fragments alive together for the whole line.
+  const lineFragments = [
+    ['to', 972],
+    ['so', 1051],
+    ['u', 1113],
+    ['o', 1166],
+    ['mo', 1204],
+  ] as const;
+  // Highlight sweep: one syllable at a time over the same lyric, each event ending
+  // exactly as the next begins, so no two syllables are ever on screen together.
+  const sweepFragments = [
+    ['to', 972, '0:00:01.00', '0:00:01.40'],
+    ['so', 1051, '0:00:01.40', '0:00:01.80'],
+    ['u', 1113, '0:00:01.80', '0:00:02.20'],
+    ['o', 1166, '0:00:02.20', '0:00:02.60'],
+    ['mo', 1204, '0:00:02.60', '0:00:03.00'],
+  ] as const;
+  const content = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    ...[0, 1].flatMap((layer) =>
+      lineFragments.map(
+        ([fragment, x], index) =>
+          `Dialogue: ${layer},0:00:01.00,0:00:04.00,ED Romaji,,0,0,0,fx,{\\pos(${x},60)\\t(${index * 2},${index * 2 + 100},\\fscx120)}${fragment}`,
+      ),
+    ),
+    ...sweepFragments.flatMap(([fragment, x, start, end]) =>
+      [
+        [40, x, 60],
+        [41, x + 4, 64],
+      ].map(
+        ([layer, copyX, copyY]) =>
+          `Dialogue: ${layer},${start},${end},ED Romaji2,,0,0,0,fx,{\\an5\\pos(${copyX},${copyY})\\t(150,290,\\1a&HFF&)}${fragment}`,
+      ),
+    ),
+    'Dialogue: 42,0:00:01.20,0:00:01.30,ED Romaji2,,0,0,0,fx,{\\fnWebdings\\pos(900,50)\\t(0,100,\\fscx120)}a',
+    'Dialogue: 42,0:00:04.00,0:00:04.20,ED Romaji2,,0,0,0,fx,{\\fnWebdings\\pos(900,50)\\t(0,100,\\fscx120)}z',
+  ].join('\n');
+
+  const cues = parseSubtitleCues(content, 'test.ass');
+  assert.equal(cues.length, 2);
+  assert.equal(cues[0]?.text.replace(/\s+/gu, ''), 'tosouomo');
+  assert.equal(cues[1]?.text, 'z');
+});
+
+test('parseSubtitleCues collapses drop-shadow layer copies offset by a few pixels', () => {
+  const fragments = [
+    ['me', 580],
+    ['no', 668],
+    ['mae', 770],
+    ['ni', 864],
+    ['no', 939],
+    ['bi', 996],
+    ['ru', 1049],
+  ] as const;
+  const content = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    ...fragments.flatMap(([fragment, x], index) => [
+      `Dialogue: 30,0:01:42.00,0:01:46.92,OP Romaji,,0,0,0,fx,{\\pos(${x},25)\\bord0\\t(${index * 2},${index * 2 + 120},\\blur0.5)}${fragment}`,
+      // Shadow copy sits 4px off the base glyph and must not read as a second syllable.
+      `Dialogue: 29,0:01:42.00,0:01:46.92,OP Romaji,,0,0,0,fx,{\\pos(${x + 4},29)\\c&HFFFFFF&\\t(${index * 2},${index * 2 + 120},\\blur9)}${fragment}`,
+      `Dialogue: 28,0:01:42.00,0:01:46.92,OP Romaji,,0,0,0,fx,{\\pos(${x},25)\\c&HFFFFFF&\\t(${index * 2},${index * 2 + 120},\\blur9)}${fragment}`,
+    ]),
+  ].join('\n');
+
+  const cues = parseSubtitleCues(content, 'test.ass');
+  assert.equal(cues.length, 1);
+  assert.equal(cues[0]?.text.replace(/\s+/gu, ''), 'menomaeninobiru');
+});
+
+test('parseSubtitleCues recovers positional word gaps beside an authored space', () => {
+  // Real ED line: every glyph is placed by `\move`, but the `star` fragment alone carries
+  // a literal leading space. The authored space must not disable positional recovery for
+  // the rest of the line.
+  const fragments = [
+    ['s', 633],
+    ['e', 665],
+    ['a', 697],
+    ['r', 723],
+    ['c', 747],
+    ['h', 774],
+    ['i', 793],
+    ['n', 813],
+    ['g', 838],
+    ['f', 884],
+    ['o', 911],
+    ['r', 937],
+    ['a', 986],
+    ['s', 1041],
+    ['h', 1070],
+    ['o', 1098],
+    ['o', 1128],
+    ['t', 1153],
+    ['i', 1169],
+    ['n', 1188],
+    ['g', 1214],
+    [' s', 1264],
+    ['t', 1290],
+    ['a', 1316],
+    ['r', 1342],
+  ] as const;
+  const content = [
+    ...eventsHeader,
+    ...[0, 1].flatMap((layer) =>
+      fragments.map(
+        ([fragment, x], index) =>
+          `Dialogue: ${layer},0:22:44.83,0:22:47.70,ED English,,0,0,0,fx,{\\move(${x},1020,${x},1020,0,300)\\t(${index * 2},${index * 2 + 300},\\fs90)}${fragment}`,
+      ),
+    ),
+  ].join('\n');
+
+  assert.equal(parseSubtitleCues(content, 'test.ass')[0]?.text, 'searching for a shooting star');
+});
+
+test('parseSubtitleCues splits chunked words whose gap only the excess rule catches', () => {
+  // `Choices|presumably` normalizes to just under the ratio threshold because both
+  // neighbors are wide three-letter chunks; its constant word-space excess still shows.
+  const fragments = [
+    ['Ch', 526],
+    ['oi', 584],
+    ['ces', 648],
+    ['pre', 747],
+    ['su', 819],
+    ['mab', 904],
+    ['ly', 981],
+    ['ma', 1059],
+    ['de', 1128],
+    ['by', 1203],
+    ['cha', 1295],
+    ['nce', 1385],
+  ] as const;
+  const content = [
+    ...eventsHeader,
+    ...[0, 1].flatMap((layer) =>
+      fragments.map(
+        ([fragment, x], index) =>
+          `Dialogue: ${layer},0:01:53.01,0:01:55.52,OP English,,0,0,0,fx,{\\pos(${x},1055)\\t(${index * 2},${index * 2 + 120},\\blur0.5)}${fragment}`,
+      ),
+    ),
+  ].join('\n');
+
+  assert.equal(
+    parseSubtitleCues(content, 'test.ass')[0]?.text,
+    'Choices presumably made by chance',
+  );
+});
+
+test('parseSubtitleCues rebuilds a line from per-glyph phase stacks with staggered timing', () => {
+  // Each glyph lives as four events anchored at one point: a transparent pre-echo until
+  // its syllable is sung, a short highlight, a rising exit ghost, and a steady hold.
+  // No timing window is shared across the phases, only the anchor ties them together.
+  const glyphs = [
+    ['エ', 559],
+    ['ネ', 601],
+    ['ル', 643],
+    ['ギ', 686],
+    ['ー', 728],
+  ] as const;
+  const timestamp = (seconds: number) => `0:00:${seconds.toFixed(2).padStart(5, '0')}`;
+  const content = [
+    ...eventsHeader,
+    ...glyphs.flatMap(([glyph, x], index) => {
+      const highlightStart = 20.9 + index * 0.4;
+      return [
+        `Dialogue: 3,${timestamp(20 + index * 0.03)},${timestamp(highlightStart)},OP - JP,,0,0,0,,{\\blur1.5\\bord2\\c&H404040&\\3c&HFFFFFF&\\an5\\pos(${x},50)\\fad(300,0)\\1a&HFF&}${glyph}`,
+        `Dialogue: 3,${timestamp(highlightStart)},${timestamp(highlightStart + 0.4)},OP - JP,,0,0,0,,{\\an5\\pos(${x},50)\\bord2\\c&H404040&\\3c&HFFFFFF&\\t(120,240,\\3c&H007A7A7A&\\blur0)\\fad(0,300)}${glyph}`,
+        `Dialogue: 3,${timestamp(highlightStart)},${timestamp(highlightStart + 2.4)},OP - JP,,0,0,0,,{\\an5\\move(${x},50,${x},0)\\bord0\\shad0\\t(\\c&HFFFFFF&\\blur5\\alpha&HFF&)}${glyph}`,
+        `Dialogue: 3,${timestamp(highlightStart + 0.4)},${timestamp(26.1 + index * 0.05)},OP - JP,,0,0,0,,{\\an5\\pos(${x},50)\\bord2\\c&H404040&\\3c&HFFFFFF&\\fad(0,300)}${glyph}`,
+      ];
+    }),
+  ].join('\n');
+
+  const cues = parseSubtitleCues(content, 'test.ass');
+  assert.equal(cues.length, 1);
+  assert.equal(cues[0]?.text, 'エネルギー');
+  assert.equal(cues[0]?.source, 'reconstructed-ass');
+  // Published from the first sung syllable to the end of the hold, so the transparent
+  // lead-in and the exit ghosts' fade tail never overlap the neighboring lines. The
+  // full generated span stays available as the animation window.
+  assert.equal(cues[0]?.startTime, 20.9);
+  assert.equal(cues[0]?.endTime, 26.3);
+  assert.equal(cues[0]?.animationStartTime, 20);
+  assert.equal(cues[0]?.animationEndTime, 26.3);
+});
+
+test('parseSubtitleCues drops transparent glow echoes and merges an exit replay', () => {
+  // The visible line sits at one row while transparent-fill glow copies duplicate every
+  // glyph on another row, and the exit shatters each glyph into copies launched from a
+  // shared anchor. Only the authored line may publish, as a single unbroken cue.
+  const glyphs = [
+    ['さ', 686],
+    ['あ', 728],
+    ['預', 770],
+    ['け', 812],
+    ['て', 854],
+  ] as const;
+  const content = [
+    ...eventsHeader,
+    ...glyphs.flatMap(([glyph, x]) => [
+      `Dialogue: 3,0:00:16.28,0:00:18.71,OP - JP,,0,0,0,,{\\an2\\pos(${x},85)\\fad(200,0)\\fry-90\\c&H404040&\\3c&HF4F4F4&\\bord2\\t(0,300,\\fry0)}${glyph}`,
+      ...[0, 1].map(
+        () =>
+          `Dialogue: 3,0:00:16.28,0:00:20.01,OP - JP,,0,0,0,,{\\pos(${x},15)\\blur5.8\\fry-90\\1a&HFF&\\fad(200,0)\\3c&H3F26AA&\\t(0,300,\\fry0)\\t(2596,3222,\\bord0\\3a&HFF&)}${glyph}`,
+      ),
+      ...[0, 1].map(
+        (copy) =>
+          `Dialogue: 3,0:00:18.71,0:00:20.89,OP - JP,,0,0,0,,{\\an5\\bord2\\fad(0,200)\\move(${x},50,${x + 25 + copy * 3},${17 - copy * 39},1605,2055)\\t(450,792,\\c&H3500DE&\\bord0)\\t(1605,2055,\\blur15\\fscx20\\fscy20\\1a&H50&\\3a&H50&)}${glyph}`,
+      ),
+    ]),
+  ].join('\n');
+
+  const cues = parseSubtitleCues(content, 'test.ass');
+  assert.equal(cues.length, 1);
+  assert.equal(cues[0]?.text, 'さあ預けて');
+  assert.equal(cues[0]?.startTime, 16.28);
+  assert.equal(cues[0]?.endTime, 20.89);
+});
+
+test('parseSubtitleCues does not double a line rendered whole beside its glyph swarm', () => {
+  // An assembly effect shows the authored line as one positioned event while dozens of
+  // per-glyph particle copies converge onto each glyph's anchor. The whole event and
+  // the swarm spell the same text and must publish as one line, once.
+  const glyphs = [
+    ['可', 854],
+    ['笑', 896],
+    ['し', 938],
+    ['い', 980],
+    ['わ', 1022],
+    ['ね', 1064],
+  ] as const;
+  const wholeLine = glyphs
+    .map(([glyph]) => `{\\an5\\fad(300,500)\\pos(960,50)}${glyph}`)
+    .join('');
+  const content = [
+    ...eventsHeader,
+    `Dialogue: 1,0:00:17.29,0:00:18.99,OP - JP,,0,0,0,,${wholeLine}`,
+    ...glyphs.flatMap(([glyph, x], index) =>
+      [0, 1, 2].map(
+        (copy) =>
+          `Dialogue: 2,0:00:17.${30 + index * 5 + copy},0:00:19.10,OP - JP,,0,0,0,,{\\bord4\\blur4\\an5\\fad(500,0)\\move(${x - 60 - copy * 17},${120 + copy * 6},${x},50,20,900)\\clip(${x - 70},80,${x - 66},84)\\t(20,900,\\clip(${x - 4},7,${x},11))}${glyph}`,
+      ),
+    ),
+  ].join('\n');
+
+  const cues = parseSubtitleCues(content, 'test.ass');
+  assert.equal(cues.length, 1);
+  assert.equal(cues[0]?.text, '可笑しいわね');
+});
+
+test('parseSubtitleCues drops a wall of near-invisible positioned texture strings', () => {
+  // An image drawn by \p1 vector events carries no texture seed, but its glyph payload
+  // is still dozens of near-transparent positioned strings sharing one window. A real
+  // faint translation is one or two events and stays published.
+  const content = [
+    ...eventsHeader,
+    'Dialogue: 90,0:00:12.66,0:00:14.91,Default,,0,0,0,,We\'ll play as a band, and then...',
+    ...Array.from(
+      { length: 12 },
+      (_, index) =>
+        `Dialogue: 9,0:00:12.66,0:00:14.91,MarySigns,,0,0,0,,{\\an7\\pos(${640 + index * 13},${4 + index * 40})\\fnGrain SemiBold\\c&H000000&\\alpha&HFD&}gtO${index}x!`,
+    ),
+    'Dialogue: 9,0:00:12.66,0:00:14.91,OtherSign,,0,0,0,,{\\pos(151,769)\\fnGrain\\alpha&HE0&}A faint but real translation',
+  ].join('\n');
+
+  assert.deepEqual(
+    parseSubtitleCues(content, 'test.ass').map((cue) => cue.text),
+    ["We'll play as a band, and then...", 'A faint but real translation'],
+  );
+});
+
+test('parseSubtitleCues drops zero-scaled zero-clipped hidden warning text', () => {
+  const content = [
+    ...eventsHeader,
+    'Dialogue: 99,0:00:00.00,0:00:15.16,Default,,0,0,0,,{\\org(0,0)\\fscx0\\fscy0\\clip(0,0,0,0)}Your media player does not support the subtitle format.',
+    'Dialogue: 0,0:00:01.00,0:00:04.00,Default,,0,0,0,,{\\fscx0\\t(0,300,\\fscx100)}見えるセリフ',
+  ].join('\n');
+
+  assert.deepEqual(
+    parseSubtitleCues(content, 'test.ass').map((cue) => cue.text),
+    ['見えるセリフ'],
+  );
+});
+
+test('parseSubtitleCues keeps hidden events hidden when a transform animates an unrelated tag', () => {
+  // `\t(...)` only reveals a zero-scaled or fully clipped event when it animates the
+  // scale or the clip itself. Animating an unrelated property -- at any nesting depth --
+  // leaves the event invisible, so its text must not reach the subtitles.
+  const content = [
+    ...eventsHeader,
+    'Dialogue: 0,0:00:01.00,0:00:04.00,Default,,0,0,0,,{\\fscx0\\fscy0\\clip(0,0,0,0)\\t(0,300,\\bord5)}hidden warning',
+    'Dialogue: 0,0:00:01.00,0:00:04.00,Default,,0,0,0,,{\\clip(0,0,0,0)\\t(0,600,\\t(0,300,\\blur4))}nested hidden warning',
+    'Dialogue: 0,0:00:05.00,0:00:08.00,Default,,0,0,0,,{\\fscx0\\t(0,300,\\fscx100)}grows into view',
+    'Dialogue: 0,0:00:09.00,0:00:12.00,Default,,0,0,0,,{\\clip(0,0,0,0)\\t(0,300,\\clip(0,0,500,500))}wipes into view',
+  ].join('\n');
+
+  assert.deepEqual(
+    parseSubtitleCues(content, 'test.ass').map((cue) => cue.text),
+    ['grows into view', 'wipes into view'],
+  );
+});
@@ -588,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';

@@ -2054,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),
 });

@@ -2086,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),
@@ -3962,6 +3965,7 @@ const {
      appState.yomitanSettingsWindow = null;
    },
    stopJellyfinRemoteSession: () => stopJellyfinRemoteSession(),
+    cleanupInternalSubtitleTrackCache: () => cachedInternalSubtitleTrackExtractor.clear(),
    cleanupYoutubeSubtitleTempDirs: () => youtubeFlowRuntime.cleanupSubtitleTempDirs(),
    cleanupYoutubeMediaCache: () => youtubeMediaCache.cleanup(),
    cleanupJellyfinSubtitleCache: () => cleanupJellyfinSubtitleCache(),
@@ -4522,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;
@@ -183,7 +183,10 @@ test('remote media keeps parsed cues when the active subtitle source cannot be r
  )?.groups?.body;

  assert.ok(actionBlock);
-  assert.match(actionBlock, /isYoutubeMediaPath\(videoPath\) \|\| isRemoteMediaPath\(videoPath\)/);
+  assert.match(
+    actionBlock,
+    /isYoutubeMediaPath\(videoPath\) \|\| \(await detectRemoteMediaPath\(videoPath\)\)/,
+  );
 });

 test('jellyfin subtitle preload seeds the tokenization prefetch directly', () => {
@@ -860,3 +863,19 @@ test('subtitle sidebar snapshot prefers cached YouTube parsed cues before active
      snapshotBlock.indexOf('resolveActiveSubtitleSidebarSourceHandler'),
  );
 });
+
+test('main process extracts internal subtitle tracks without a network-mount guard', () => {
+  const source = readMainSource();
+  const resolverWiring = source.match(
+    /const resolveActiveSubtitleSidebarSourceHandler = createResolveActiveSubtitleSidebarSourceHandler\(\{(?<body>[\s\S]*?)\n\}\);/,
+  )?.groups?.body;
+
+  assert.ok(resolverWiring);
+  // Network-mounted files are extracted like local ones; only remote URLs skip
+  // extraction, handled inside the resolver itself.
+  assert.doesNotMatch(resolverWiring, /isRemoteMediaPath/);
+  assert.match(
+    resolverWiring,
+    /extractInternalSubtitleTrack:[\s\S]*cachedInternalSubtitleTrackExtractor\.extract/,
+  );
+});
@@ -43,6 +43,7 @@ test('on will quit cleanup handler runs all cleanup steps', () => {
    destroyYomitanSettingsWindow: () => calls.push('destroy-yomitan-settings-window'),
    clearYomitanSettingsWindow: () => calls.push('clear-yomitan-settings-window'),
    stopJellyfinRemoteSession: () => calls.push('stop-jellyfin-remote'),
+    cleanupInternalSubtitleTrackCache: () => calls.push('cleanup-internal-subtitles'),
    cleanupYoutubeSubtitleTempDirs: () => calls.push('cleanup-youtube-subtitles'),
    cleanupYoutubeMediaCache: () => calls.push('cleanup-youtube-media'),
    cleanupJellyfinSubtitleCache: () => calls.push('cleanup-jellyfin-subtitles'),
@@ -50,10 +51,11 @@ test('on will quit cleanup handler runs all cleanup steps', () => {
  });

  cleanup();
-  assert.equal(calls.length, 34);
+  assert.equal(calls.length, 35);
  assert.equal(calls[0], 'destroy-tray');
  assert.equal(calls[calls.length - 1], 'stop-discord-presence');
  assert.ok(calls.includes('cleanup-jellyfin-subtitles'));
+  assert.ok(calls.includes('cleanup-internal-subtitles'));
  assert.ok(calls.includes('clear-windows-visible-overlay-poll'));
  assert.ok(calls.includes('clear-linux-mpv-fullscreen-overlay-refresh-timeouts'));
  assert.ok(calls.includes('cleanup-youtube-subtitles'));
@@ -97,6 +99,7 @@ test('on will quit cleanup handler cleans jellyfin subtitle cache when stopping
      calls.push('stop-jellyfin-remote');
      throw new Error('stop failed');
    },
+    cleanupInternalSubtitleTrackCache: () => calls.push('cleanup-internal-subtitles'),
    cleanupYoutubeSubtitleTempDirs: () => calls.push('cleanup-youtube-subtitles'),
    cleanupYoutubeMediaCache: () => calls.push('cleanup-youtube-media'),
    cleanupJellyfinSubtitleCache: () => calls.push('cleanup-jellyfin-subtitles'),
@@ -104,7 +107,11 @@ test('on will quit cleanup handler cleans jellyfin subtitle cache when stopping
  });

  assert.throws(() => cleanup(), /stop failed/);
-  assert.deepEqual(calls, ['stop-jellyfin-remote', 'cleanup-jellyfin-subtitles']);
+  assert.deepEqual(calls, [
+    'stop-jellyfin-remote',
+    'cleanup-jellyfin-subtitles',
+    'cleanup-internal-subtitles',
+  ]);
 });

 test('should restore windows on activate requires initialized runtime and no windows', () => {
@@ -29,6 +29,7 @@ export function createOnWillQuitCleanupHandler(deps: {
  destroyYomitanSettingsWindow: () => void;
  clearYomitanSettingsWindow: () => void;
  stopJellyfinRemoteSession: () => void;
+  cleanupInternalSubtitleTrackCache: () => void;
  cleanupYoutubeSubtitleTempDirs: () => void;
  cleanupYoutubeMediaCache: () => void;
  cleanupJellyfinSubtitleCache: () => void;
@@ -67,7 +68,11 @@ export function createOnWillQuitCleanupHandler(deps: {
    try {
      deps.stopJellyfinRemoteSession();
    } finally {
-      deps.cleanupJellyfinSubtitleCache();
+      try {
+        deps.cleanupJellyfinSubtitleCache();
+      } finally {
+        deps.cleanupInternalSubtitleTrackCache();
+      }
    }
    deps.cleanupYoutubeSubtitleTempDirs();
    deps.cleanupYoutubeMediaCache();
@@ -72,6 +72,7 @@ test('cleanup deps builder returns handlers that guard optional runtime objects'
    clearYomitanSettingsWindow: () => calls.push('clear-yomitan-settings-window'),

    stopJellyfinRemoteSession: () => calls.push('stop-jellyfin-remote'),
+    cleanupInternalSubtitleTrackCache: () => calls.push('cleanup-internal-subtitles'),
    cleanupYoutubeSubtitleTempDirs: () => calls.push('cleanup-youtube-subtitles'),
    cleanupYoutubeMediaCache: () => calls.push('cleanup-youtube-media'),
    cleanupJellyfinSubtitleCache: () => calls.push('cleanup-jellyfin-subtitles'),
@@ -95,6 +96,7 @@ test('cleanup deps builder returns handlers that guard optional runtime objects'
  assert.ok(calls.includes('destroy-first-run-window'));
  assert.ok(calls.includes('destroy-yomitan-settings-window'));
  assert.ok(calls.includes('stop-jellyfin-remote'));
+  assert.ok(calls.includes('cleanup-internal-subtitles'));
  assert.ok(calls.includes('cleanup-youtube-subtitles'));
  assert.ok(calls.includes('cleanup-youtube-media'));
  assert.ok(calls.includes('cleanup-jellyfin-subtitles'));
@@ -152,6 +154,7 @@ test('cleanup deps builder skips destroyed yomitan window', () => {
    getYomitanSettingsWindow: () => null,
    clearYomitanSettingsWindow: () => {},
    stopJellyfinRemoteSession: () => {},
+    cleanupInternalSubtitleTrackCache: () => {},
    cleanupYoutubeSubtitleTempDirs: () => {},
    cleanupYoutubeMediaCache: () => {},
    cleanupJellyfinSubtitleCache: () => {},
@@ -204,6 +207,7 @@ test('cleanup deps builder skips global shortcut cleanup before app ready', () =
    getYomitanSettingsWindow: () => null,
    clearYomitanSettingsWindow: () => {},
    stopJellyfinRemoteSession: () => {},
+    cleanupInternalSubtitleTrackCache: () => {},
    cleanupYoutubeSubtitleTempDirs: () => {},
    cleanupYoutubeMediaCache: () => {},
    cleanupJellyfinSubtitleCache: () => {},
@@ -58,6 +58,7 @@ export function createBuildOnWillQuitCleanupDepsHandler(deps: {
  clearYomitanSettingsWindow: () => void;

  stopJellyfinRemoteSession: () => void;
+  cleanupInternalSubtitleTrackCache: () => void;
  cleanupYoutubeSubtitleTempDirs: () => void;
  cleanupYoutubeMediaCache: () => void;
  cleanupJellyfinSubtitleCache: () => void;
@@ -144,6 +145,7 @@ export function createBuildOnWillQuitCleanupDepsHandler(deps: {
    },
    clearYomitanSettingsWindow: () => deps.clearYomitanSettingsWindow(),
    stopJellyfinRemoteSession: () => deps.stopJellyfinRemoteSession(),
+    cleanupInternalSubtitleTrackCache: () => deps.cleanupInternalSubtitleTrackCache(),
    cleanupYoutubeSubtitleTempDirs: () => deps.cleanupYoutubeSubtitleTempDirs(),
    cleanupYoutubeMediaCache: () => deps.cleanupYoutubeMediaCache(),
    cleanupJellyfinSubtitleCache: () => deps.cleanupJellyfinSubtitleCache(),
@@ -49,6 +49,7 @@ test('composeStartupLifecycleHandlers returns callable startup lifecycle handler
      getYomitanSettingsWindow: () => null,
      clearYomitanSettingsWindow: () => {},
      stopJellyfinRemoteSession: async () => {},
+      cleanupInternalSubtitleTrackCache: () => {},
      cleanupYoutubeSubtitleTempDirs: () => {},
      cleanupYoutubeMediaCache: () => {},
      cleanupJellyfinSubtitleCache: () => {},
@@ -6,6 +6,7 @@ import process from 'node:process';
 import test from 'node:test';
 import {
  buildFfmpegSubtitleExtractionArgs,
+  createCachedInternalSubtitleTrackExtractor,
  extractInternalSubtitleTrackToTempFile,
  parseTrackId,
 } from './internal-subtitle-extraction';
@@ -22,6 +23,65 @@ test('parseTrackId rejects negative track ids', () => {
  assert.equal(parseTrackId(' -2 '), null);
 });

+test('cached internal subtitle extraction shares concurrent and repeated track requests', async () => {
+  let extractionCalls = 0;
+  let cleanupCalls = 0;
+  let resolveExtraction:
+    | ((result: { path: string; cleanup: () => Promise<void> }) => void)
+    | undefined;
+  const firstExtraction = new Promise<{ path: string; cleanup: () => Promise<void> }>((resolve) => {
+    resolveExtraction = resolve;
+  });
+  const extractor = createCachedInternalSubtitleTrackExtractor({
+    extract: async () => {
+      extractionCalls += 1;
+      if (extractionCalls === 1) {
+        return firstExtraction;
+      }
+      return {
+        path: `/tmp/subtitle-${extractionCalls}.ass`,
+        cleanup: async () => {
+          cleanupCalls += 1;
+        },
+      };
+    },
+  });
+  const request = () =>
+    extractor.extract('ffmpeg', '/Volumes/media/episode.mkv', {
+      'ff-index': 3,
+      codec: 'ass',
+    });
+
+  const concurrent = Array.from({ length: 6 }, request);
+  assert.equal(extractionCalls, 1);
+  if (!resolveExtraction) {
+    throw new Error('extraction did not start');
+  }
+  resolveExtraction({
+    path: '/tmp/subtitle-1.ass',
+    cleanup: async () => {
+      cleanupCalls += 1;
+    },
+  });
+
+  const results = await Promise.all(concurrent);
+  assert.deepEqual(
+    results.map((result) => result?.path),
+    Array.from({ length: 6 }, () => '/tmp/subtitle-1.ass'),
+  );
+  await Promise.all(results.map((result) => result?.cleanup()));
+  assert.equal(cleanupCalls, 0);
+
+  assert.equal((await request())?.path, '/tmp/subtitle-1.ass');
+  assert.equal(extractionCalls, 1);
+
+  extractor.clear();
+  await new Promise((resolve) => setImmediate(resolve));
+  assert.equal(cleanupCalls, 1);
+  assert.equal((await request())?.path, '/tmp/subtitle-2.ass');
+  assert.equal(extractionCalls, 2);
+});
+
 test('extractInternalSubtitleTrackToTempFile times out stalled ffmpeg process', async () => {
  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'subminer-ffmpeg-timeout-'));
  const videoPath = path.join(root, 'video.mkv');
@@ -35,7 +35,21 @@ export type MpvSubtitleTrackLike = {
  'external-filename'?: unknown;
 };

-const DEFAULT_EXTRACTION_TIMEOUT_MS = 30_000;
+export type ExtractedInternalSubtitleTrack = {
+  path: string;
+  cleanup: () => Promise<void>;
+};
+
+export type InternalSubtitleTrackExtractor = (
+  ffmpegPath: string,
+  videoPath: string,
+  track: MpvSubtitleTrackLike,
+) => Promise<ExtractedInternalSubtitleTrack | null>;
+
+// Subtitle packets are interleaved through the container, so extraction reads the
+// entire file. Network mounts move ~100 MB/s on gigabit, so large Bluray remuxes
+// need well over 30 seconds.
+const DEFAULT_EXTRACTION_TIMEOUT_MS = 120_000;

 export function parseTrackId(value: unknown): number | null {
  if (typeof value === 'number' && Number.isInteger(value) && value >= 0) {
@@ -80,7 +94,7 @@ export async function extractInternalSubtitleTrackToTempFile(
  videoPath: string,
  track: MpvSubtitleTrackLike,
  options: { extractionTimeoutMs?: number; spawnArgsOverride?: string[] } = {},
-): Promise<{ path: string; cleanup: () => Promise<void> } | null> {
+): Promise<ExtractedInternalSubtitleTrack | null> {
  const ffIndex = parseTrackId(track['ff-index']);
  const codec = typeof track.codec === 'string' ? track.codec : null;
  const extension = codecToExtension(codec ?? undefined);
@@ -145,3 +159,69 @@ export async function extractInternalSubtitleTrackToTempFile(
    },
  };
 }
+
+type CachedExtraction = {
+  promise: Promise<ExtractedInternalSubtitleTrack | null>;
+};
+
+function buildCachedExtractionKey(
+  ffmpegPath: string,
+  videoPath: string,
+  track: MpvSubtitleTrackLike,
+): string {
+  const codec = typeof track.codec === 'string' ? track.codec : null;
+  return JSON.stringify([ffmpegPath, videoPath, parseTrackId(track['ff-index']), codec]);
+}
+
+const releaseCachedExtraction = async (): Promise<void> => {};
+
+/**
+ * Owns extracted subtitle files for the active media and shares one extraction between callers.
+ * Caller cleanup releases only its view; clear removes the owned files on media changes or quit.
+ */
+export function createCachedInternalSubtitleTrackExtractor(
+  deps: { extract?: InternalSubtitleTrackExtractor } = {},
+): {
+  extract: InternalSubtitleTrackExtractor;
+  clear: () => void;
+} {
+  const extractTrack = deps.extract ?? extractInternalSubtitleTrackToTempFile;
+  const extractions = new Map<string, CachedExtraction>();
+
+  const extract: InternalSubtitleTrackExtractor = async (ffmpegPath, videoPath, track) => {
+    const key = buildCachedExtractionKey(ffmpegPath, videoPath, track);
+    let cached = extractions.get(key);
+    if (!cached) {
+      const next: CachedExtraction = {
+        promise: extractTrack(ffmpegPath, videoPath, track),
+      };
+      cached = next;
+      extractions.set(key, next);
+      void next.promise.catch(() => {
+        if (extractions.get(key) === next) {
+          extractions.delete(key);
+        }
+      });
+    }
+
+    const result = await cached.promise;
+    if (extractions.get(key) !== cached || !result) {
+      return null;
+    }
+
+    return {
+      path: result.path,
+      cleanup: releaseCachedExtraction,
+    };
+  };
+
+  const clear = (): void => {
+    const staleExtractions = [...extractions.values()];
+    extractions.clear();
+    for (const extraction of staleExtractions) {
+      void extraction.promise.then((result) => result?.cleanup()).catch(() => undefined);
+    }
+  };
+
+  return { extract, clear };
+}
@@ -426,6 +426,13 @@ test('canonical ASS cues replace live glyph spam for display, history, and immer
          text: '飛び越えてみたくて',
          source: 'canonical-ass',
        },
+        {
+          startTime: 10,
+          endTime: 12,
+          text: 'MaidCafeMaidCafe',
+          source: 'reconstructed-ass',
+          assLayout: { kind: 'fragment-grid', sourceOrder: 2 },
+        },
      ],
      currentMediaPath: '/video.mkv',
      currentSubText: '',
@@ -503,6 +510,11 @@ test('canonical ASS cues replace live glyph spam for display, history, and immer
  handlers.recordSubtitleTiming('今', 0.8, 1.5);

  assert.deepEqual(timing.slice(4), [{ text: '今　手にある物差しでは', start: 1.2, end: 3.8 }]);
+
+  handlers.recordImmersionSubtitleLine('Maid\nCafe', 10, 12);
+  handlers.recordSubtitleTiming('Maid\nCafe', 10, 12);
+  assert.equal(immersion.length, 3);
+  assert.equal(timing.length, 5);
 });

 test('subtitle-track changes stop stale canonical cues from substituting immediately', () => {
@@ -218,6 +218,9 @@ export function createBuildBindMpvMainEventHandlersMainDepsHandler(deps: {
        return;
      }
      text = stripFragmentsForRecording(text, start);
+      if (!text.trim()) {
+        return;
+      }
      if (!immersionLineDedupGate.shouldRecord({ text, startSec: start, endSec: end })) {
        return;
      }
@@ -228,8 +231,12 @@ export function createBuildBindMpvMainEventHandlersMainDepsHandler(deps: {
      const secondaryText = deps.appState.mpvClient?.currentSecondarySubText || undefined;
      const canonical = resolveCanonicalSample(text, start);
      if (!canonical) {
+        const recordableText = stripFragmentsForRecording(text, start);
+        if (!recordableText.trim()) {
+          return;
+        }
        deps.appState.subtitleTimingTracker?.recordSubtitle?.(
-          stripFragmentsForRecording(text, start),
+          recordableText,
          start,
          end,
          secondaryText,
@@ -0,0 +1,64 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { createRemoteMediaPathDetector } from './network-media-path';
+
+test('remote media detector recognizes mounted network filesystems', async () => {
+  const detectRemoteMedia = createRemoteMediaPathDetector({
+    platform: 'darwin',
+    readMountOutput: async () =>
+      [
+        '/dev/disk3s5 on /System/Volumes/Data (apfs, local, journaled)',
+        '//viewer@media/jellyfin on /Volumes/jellyfin (smbfs, nodev, nosuid)',
+      ].join('\n'),
+  });
+
+  assert.equal(await detectRemoteMedia('/Volumes/jellyfin/movie.mkv'), true);
+  assert.equal(await detectRemoteMedia('/Volumes/jellyfin-another/movie.mkv'), false);
+  assert.equal(await detectRemoteMedia('/Users/viewer/movie.mkv'), false);
+});
+
+test('remote media detector recognizes Linux network mount output', async () => {
+  const detectRemoteMedia = createRemoteMediaPathDetector({
+    platform: 'linux',
+    readMountOutput: async () =>
+      '//media/jellyfin on /mnt/Jellyfin\\040Media type cifs (rw,relatime)',
+  });
+
+  assert.equal(await detectRemoteMedia('/mnt/Jellyfin Media/movie.mkv'), true);
+});
+
+test('remote media detector shares its mount lookup between concurrent callers', async () => {
+  let mountReads = 0;
+  const detectRemoteMedia = createRemoteMediaPathDetector({
+    platform: 'darwin',
+    readMountOutput: async () => {
+      mountReads += 1;
+      return '//viewer@media/jellyfin on /Volumes/jellyfin (smbfs, nodev, nosuid)';
+    },
+  });
+
+  const results = await Promise.all(
+    Array.from({ length: 6 }, () => detectRemoteMedia('/Volumes/jellyfin/movie.mkv')),
+  );
+
+  assert.deepEqual(
+    results,
+    Array.from({ length: 6 }, () => true),
+  );
+  assert.equal(mountReads, 1);
+});
+
+test('remote media detector recognizes URLs and Windows UNC paths without reading mounts', async () => {
+  let mountReads = 0;
+  const detectRemoteMedia = createRemoteMediaPathDetector({
+    platform: 'win32',
+    readMountOutput: async () => {
+      mountReads += 1;
+      return '';
+    },
+  });
+
+  assert.equal(await detectRemoteMedia('https://media.example/movie.mkv'), true);
+  assert.equal(await detectRemoteMedia('\\\\media-server\\jellyfin\\movie.mkv'), true);
+  assert.equal(mountReads, 0);
+});
@@ -0,0 +1,142 @@
+import { execFile } from 'node:child_process';
+import path from 'node:path';
+import process from 'node:process';
+import { resolveSubtitleSourcePath } from './subtitle-prefetch-source';
+
+const DEFAULT_MOUNT_CACHE_TTL_MS = 5_000;
+const NETWORK_FILESYSTEM_TYPES = new Set([
+  '9p',
+  'afpfs',
+  'cifs',
+  'davfs',
+  'davfs2',
+  'fuse.sshfs',
+  'nfs',
+  'nfs4',
+  'smbfs',
+  'sshfs',
+  'webdav',
+]);
+
+function isRemoteUrl(value: string): boolean {
+  try {
+    const url = new URL(value);
+    return url.protocol === 'http:' || url.protocol === 'https:';
+  } catch {
+    return false;
+  }
+}
+
+function decodeMountPath(value: string): string {
+  return value.replace(/\\([0-7]{3})/g, (_match, digits: string) =>
+    String.fromCharCode(Number.parseInt(digits, 8)),
+  );
+}
+
+function parseNetworkMountPaths(output: string): string[] {
+  const networkMountPaths: string[] = [];
+  for (const line of output.split('\n')) {
+    const optionsStart = line.lastIndexOf(' (');
+    if (optionsStart < 0) continue;
+
+    let mountDescription = line.slice(0, optionsStart);
+    const options = line.slice(optionsStart + 2, line.indexOf(')', optionsStart));
+    const linuxTypeSeparator = mountDescription.lastIndexOf(' type ');
+    const filesystemType = (
+      linuxTypeSeparator >= 0
+        ? mountDescription.slice(linuxTypeSeparator + ' type '.length)
+        : (options.split(',').at(0) ?? '')
+    )
+      .trim()
+      .toLowerCase();
+    if (!NETWORK_FILESYSTEM_TYPES.has(filesystemType)) continue;
+
+    if (linuxTypeSeparator >= 0) {
+      mountDescription = mountDescription.slice(0, linuxTypeSeparator);
+    }
+    const mountSeparator = mountDescription.indexOf(' on ');
+    if (mountSeparator < 0) continue;
+    networkMountPaths.push(
+      path.posix.normalize(decodeMountPath(mountDescription.slice(mountSeparator + 4).trim())),
+    );
+  }
+  return networkMountPaths;
+}
+
+function readMountOutput(platform: NodeJS.Platform): Promise<string> {
+  if (platform === 'win32') return Promise.resolve('');
+  const command = platform === 'darwin' ? '/sbin/mount' : 'mount';
+  return new Promise((resolve, reject) => {
+    execFile(
+      command,
+      [],
+      { encoding: 'utf8', timeout: 1_000, maxBuffer: 1024 * 1024 },
+      (error, stdout) => {
+        if (error) {
+          reject(error);
+          return;
+        }
+        resolve(stdout);
+      },
+    );
+  });
+}
+
+function isPathWithinMount(filePath: string, mountPath: string): boolean {
+  const relativePath = path.posix.relative(mountPath, filePath);
+  return (
+    relativePath === '' ||
+    (relativePath !== '..' &&
+      !relativePath.startsWith(`..${path.posix.sep}`) &&
+      !path.posix.isAbsolute(relativePath))
+  );
+}
+
+export type RemoteMediaPathDetector = (mediaPath: string) => Promise<boolean>;
+
+export function createRemoteMediaPathDetector(
+  deps: {
+    platform?: NodeJS.Platform;
+    readMountOutput?: () => Promise<string>;
+    now?: () => number;
+    mountCacheTtlMs?: number;
+  } = {},
+): RemoteMediaPathDetector {
+  const platform = deps.platform ?? process.platform;
+  const getMountOutput = deps.readMountOutput ?? (() => readMountOutput(platform));
+  const now = deps.now ?? Date.now;
+  const mountCacheTtlMs = deps.mountCacheTtlMs ?? DEFAULT_MOUNT_CACHE_TTL_MS;
+  let mountCache: { expiresAt: number; networkMountPaths: Promise<readonly string[]> } | undefined;
+
+  const getNetworkMountPaths = (): Promise<readonly string[]> => {
+    const currentTime = now();
+    if (mountCache && currentTime < mountCache.expiresAt) {
+      return mountCache.networkMountPaths;
+    }
+
+    const networkMountPaths = getMountOutput()
+      .then(parseNetworkMountPaths)
+      .catch(() => []);
+    mountCache = {
+      expiresAt: currentTime + mountCacheTtlMs,
+      networkMountPaths,
+    };
+    return networkMountPaths;
+  };
+
+  return async (mediaPath): Promise<boolean> => {
+    const source = mediaPath.trim();
+    if (!source) return false;
+    if (isRemoteUrl(source)) return true;
+
+    const filePath = resolveSubtitleSourcePath(source);
+    if (platform === 'win32') {
+      return filePath.startsWith('\\\\');
+    }
+    if (!path.posix.isAbsolute(filePath)) return false;
+
+    const networkMountPaths = await getNetworkMountPaths();
+    const normalizedPath = path.posix.normalize(filePath);
+    return networkMountPaths.some((mountPath) => isPathWithinMount(normalizedPath, mountPath));
+  };
+}
@@ -64,6 +64,34 @@ test('resolvePrimarySubtitleText combines unique simultaneous parsed cues', () =
  );
 });

+test('resolvePrimarySubtitleText removes duplicate lines across multiline parsed cues', () => {
+  assert.equal(
+    resolvePrimarySubtitleText({
+      liveText: 'First line\nSecond line\nFirst line',
+      currentTimeSec: 2,
+      cues: [
+        { startTime: 1, endTime: 3, text: 'First line\nSecond line' },
+        { startTime: 1, endTime: 3, text: 'First line' },
+      ],
+    }),
+    'First line\nSecond line',
+  );
+});
+
+test('resolvePrimarySubtitleText removes equivalent full-width duplicate lines', () => {
+  assert.equal(
+    resolvePrimarySubtitleText({
+      liveText: '２０分５３秒\n20分53秒',
+      currentTimeSec: 2,
+      cues: [
+        { startTime: 1, endTime: 3, text: '２０分５３秒' },
+        { startTime: 1, endTime: 3, text: '20分53秒' },
+      ],
+    }),
+    '２０分５３秒',
+  );
+});
+
 test('resolvePrimarySubtitleText collapses whitespace variants of one ASS lyric', () => {
  const ass = [
    '[Events]',
@@ -152,6 +180,73 @@ test('resolvePrimarySubtitleText keeps concurrent dialogue that is not part of t
  assert.equal(text, '普通のセリフ\n今\n手にある');
 });

+test('resolvePrimarySubtitleText combines parsed dialogue with a reconstructed lyric', () => {
+  const text = resolvePrimarySubtitleText({
+    liveText: '普通のセリフ\n今\n今\n手\n手\nにある\nにある',
+    currentTimeSec: 2,
+    cues: [
+      { startTime: 1, endTime: 3, text: '普通のセリフ' },
+      {
+        startTime: 1.2,
+        endTime: 3.8,
+        text: '今　手にある',
+        source: 'reconstructed-ass',
+      },
+    ],
+  });
+
+  assert.equal(text, '普通のセリフ\n今　手にある');
+});
+
+test('resolvePrimarySubtitleText uses fragment grids only to account for live sign pieces', () => {
+  const text = resolvePrimarySubtitleText({
+    liveText: 'Ordinary dialogue\nMaid\nCafe',
+    currentTimeSec: 2,
+    cues: [
+      { startTime: 1, endTime: 3, text: 'Ordinary dialogue' },
+      {
+        startTime: 1,
+        endTime: 3,
+        text: 'MaidCafeMaidCafe',
+        source: 'reconstructed-ass',
+        assLayout: { kind: 'fragment-grid', sourceOrder: 2 },
+      },
+    ],
+  });
+
+  assert.equal(text, 'Ordinary dialogue');
+});
+
+test('resolvePrimarySubtitleText drops malformed ASS control debris from live text', () => {
+  const cues = parseSubtitleCues(
+    [
+      '[Events]',
+      'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+      'Dialogue: 0,0:00:01.00,0:00:03.00,Default,,0,0,0,,Visible line',
+    ].join('\n'),
+    'test.ass',
+  );
+
+  assert.equal(
+    resolvePrimarySubtitleText({
+      liveText: 'Visible line\n\\\n{\\fr0',
+      currentTimeSec: 2,
+      cues,
+    }),
+    'Visible line',
+  );
+});
+
+test('resolvePrimarySubtitleText preserves SRT text that resembles ASS control debris', () => {
+  const liveText = 'Visible line\n\\\n{\\fr0';
+  const cues = parseSubtitleCues(
+    ['1', '00:00:01,000 --> 00:00:03,000', liveText].join('\n'),
+    'test.srt',
+  );
+
+  assert.equal(resolvePrimarySubtitleText({ liveText, currentTimeSec: 2, cues }), liveText);
+});
+
 test('resolvePrimarySubtitleText keeps a fresh line starting just after the animation ended', () => {
  const text = resolvePrimarySubtitleText({
    liveText: '次のセリフ',
@@ -382,3 +477,50 @@ test('resolveCanonicalPrimarySubtitle picks the cue its fragments spell, not the
    '今　手にある',
  );
 });
+
+test('resolvePrimarySubtitleText suppresses a live glyph wall when no cues are available', () => {
+  const wall = [...'wansdumretoikhI'].join('\n');
+  assert.equal(
+    resolvePrimarySubtitleText({ liveText: `${wall}\ntai`, currentTimeSec: 1355, cues: null }),
+    '',
+  );
+});
+
+test('stripCanonicalFragmentLines drops a live glyph wall with no nearby canonical cues', () => {
+  const wall = [...'wansdumretoikhI'].join('\n');
+  assert.equal(
+    stripCanonicalFragmentLines({
+      liveText: `${wall}\nそれよりも　ノート…`,
+      currentTimeSec: 1355,
+      cues: [],
+    }),
+    'それよりも　ノート…',
+  );
+});
+
+test('resolvePrimarySubtitleText drops a finished lyric whose exit ghosts outlive it beside a raw line', () => {
+  // The reconstructed lyric ended at 6.0 but its exit ghost glyphs stay in the live
+  // text until 7.0, while the next authored line is a plain raw event. The retired cue
+  // must explain the ghost fragments without re-surfacing next to the active line.
+  const cues = [
+    {
+      startTime: 1.0,
+      endTime: 6.0,
+      text: 'エネルギーはサイクル',
+      source: 'reconstructed-ass' as const,
+      animationStartTime: 0.5,
+      animationEndTime: 7.0,
+      assStyle: 'OP - JP',
+    },
+    { startTime: 6.0, endTime: 12.0, text: '象徴的なパレード' },
+  ];
+
+  assert.equal(
+    resolvePrimarySubtitleText({
+      liveText: 'エ\nネ\nル\nギ\nー\n象徴的なパレード',
+      currentTimeSec: 6.5,
+      cues,
+    }),
+    '象徴的なパレード',
+  );
+});
@@ -1,4 +1,8 @@
 import type { SubtitleCue } from '../../types';
+import {
+  removeAssControlDebrisLines,
+  removeLiveGlyphFragmentLines,
+} from '../../core/services/ass-text';

 // Slack on top of each cue's recorded animation envelope, for time-pos observation
 // staleness and small user sub-delay offsets. The envelope itself covers how far
@@ -13,6 +17,15 @@ export interface ResolvedPrimarySubtitle {
  cues: SubtitleCue[];
 }

+function cuesUseAssSyntax(cues: readonly SubtitleCue[] | null | undefined): boolean {
+  return (cues ?? []).some(
+    (cue) =>
+      cue.source === 'canonical-ass' ||
+      cue.source === 'reconstructed-ass' ||
+      cue.assLayout !== undefined,
+  );
+}
+
 function animationSpan(cue: SubtitleCue): { start: number; end: number } {
  return {
    start: cue.animationStartTime ?? cue.startTime,
@@ -23,9 +36,13 @@ function animationSpan(cue: SubtitleCue): { start: number; end: number } {
 function nearbyCanonicalCues(
  cues: readonly SubtitleCue[] | null | undefined,
  currentTimeSec: number,
+  includeFragmentGrids = false,
 ): SubtitleCue[] {
  return (cues ?? []).filter((cue) => {
-    if (cue.source !== 'canonical-ass' && cue.source !== 'reconstructed-ass') {
+    if (
+      (cue.source !== 'canonical-ass' && cue.source !== 'reconstructed-ass') ||
+      (!includeFragmentGrids && cue.assLayout?.kind === 'fragment-grid')
+    ) {
      return false;
    }
    const span = animationSpan(cue);
@@ -37,7 +54,7 @@ function nearbyCanonicalCues(
 }

 function compactWhitespace(text: string): string {
-  return text.replace(/\s+/gu, '');
+  return text.normalize('NFKC').replace(/\s+/gu, '');
 }

 // ASS layers can encode the same visible spacing with ordinary, hard, or
@@ -47,10 +64,12 @@ function uniqueCueTexts(cues: readonly SubtitleCue[]): string[] {
  const texts: string[] = [];
  const seen = new Set<string>();
  for (const cue of cues) {
-    const compactText = compactWhitespace(cue.text);
-    if (seen.has(compactText)) continue;
-    seen.add(compactText);
-    texts.push(cue.text);
+    for (const line of cue.text.split('\n')) {
+      const compactText = compactWhitespace(line);
+      if (!compactText || seen.has(compactText)) continue;
+      seen.add(compactText);
+      texts.push(line);
+    }
  }
  return texts;
 }
@@ -87,23 +106,54 @@ function resolveActiveParsedPrimarySubtitle(options: {
      return false;
    }
    const cueSegments = compactLineSegments(cue.text);
-    return cueSegments.length > 0 && cueSegments.every((segment) => liveSegmentSet.has(segment));
+    if (cueSegments.length === 0) return false;
+    if (cue.source === 'canonical-ass' || cue.source === 'reconstructed-ass') {
+      return liveSegments.some((segment) =>
+        cueSegments.some((cueSegment) => cueSegment.includes(segment)),
+      );
+    }
+    return cueSegments.every((segment) => liveSegmentSet.has(segment));
  });
  if (selected.length === 0) {
    return null;
  }

-  const parsedSegmentSet = new Set(selected.flatMap((cue) => compactLineSegments(cue.text)));
-  if (!liveSegments.every((segment) => parsedSegmentSet.has(segment))) {
+  const parsedSegments = selected.flatMap((cue) =>
+    compactLineSegments(cue.text).map((segment) => ({
+      segment,
+      recovered: cue.source === 'canonical-ass' || cue.source === 'reconstructed-ass',
+    })),
+  );
+  if (
+    !liveSegments.every((liveSegment) =>
+      parsedSegments.some(({ segment, recovered }) =>
+        recovered ? segment.includes(liveSegment) : segment === liveSegment,
+      ),
+    )
+  ) {
    return null;
  }

-  const texts = uniqueCueTexts(selected);
+  // A cue selected only through the edge tolerance has already ended (or not yet
+  // started) by its published timing: a finished lyric whose exit ghosts linger into
+  // the next line. It still explains those live fragments above, but while any cue is
+  // strictly active, only the active cues supply the displayed text. With no strictly
+  // active cue, the edge cues remain the display fallback for stale time-pos readings.
+  const strictlyActive = selected.filter(
+    (cue) => cue.startTime <= options.currentTimeSec && cue.endTime > options.currentTimeSec,
+  );
+  const displayCues = strictlyActive.length > 0 ? strictlyActive : selected;
+
+  // Dense sign grids still explain their raw mpv fragments, but are visual
+  // typesetting rather than a publishable subtitle line.
+  const texts = uniqueCueTexts(
+    displayCues.filter((cue) => cue.assLayout?.kind !== 'fragment-grid'),
+  );
  return {
    text: texts.join('\n'),
-    startTime: Math.min(...selected.map((cue) => cue.startTime)),
-    endTime: Math.max(...selected.map((cue) => cue.endTime)),
-    cues: selected,
+    startTime: Math.min(...displayCues.map((cue) => cue.startTime)),
+    endTime: Math.max(...displayCues.map((cue) => cue.endTime)),
+    cues: displayCues,
  };
 }

@@ -179,8 +229,9 @@ export function resolveCanonicalPrimarySubtitle(options: {
 /**
 * Live text with generated-animation fragment lines removed. Recording paths use this
 * when full canonical substitution declined -- concurrent dialogue during an insert
- * song: the dialogue is worth recording, the glyph fragments beside it are not. Returns
- * the input unchanged when no canonical cue is near or nothing non-fragment remains.
+ * song: the dialogue is worth recording, the glyph fragments beside it are not. An
+ * all-fragment visual grid becomes empty; other all-matched input remains unchanged as a
+ * defensive fallback.
 */
 export function stripCanonicalFragmentLines(options: {
  liveText: string;
@@ -188,18 +239,20 @@ export function stripCanonicalFragmentLines(options: {
  cues: readonly SubtitleCue[] | null | undefined;
 }): string {
  if (!Number.isFinite(options.currentTimeSec)) {
-    return options.liveText;
+    return removeLiveGlyphFragmentLines(options.liveText);
  }
-  const nearby = nearbyCanonicalCues(options.cues, options.currentTimeSec);
+  const nearby = nearbyCanonicalCues(options.cues, options.currentTimeSec, true);
  if (nearby.length === 0) {
-    return options.liveText;
+    return removeLiveGlyphFragmentLines(options.liveText);
  }
  const compactCues = nearby.map((cue) => compactWhitespace(cue.text));
  const kept = options.liveText.split('\n').filter((line) => {
    const compact = compactWhitespace(line);
    return compact && !compactCues.some((cueText) => cueText.includes(compact));
  });
-  return kept.length > 0 ? kept.join('\n') : options.liveText;
+  if (kept.length > 0) return removeLiveGlyphFragmentLines(kept.join('\n'));
+  if (nearby.some((cue) => cue.assLayout?.kind === 'fragment-grid')) return '';
+  return removeLiveGlyphFragmentLines(options.liveText);
 }

 export function resolvePrimarySubtitleText(options: {
@@ -207,16 +260,19 @@ export function resolvePrimarySubtitleText(options: {
  currentTimeSec: number;
  cues: readonly SubtitleCue[] | null | undefined;
 }): string {
-  if (!options.liveText.trim()) {
-    return options.liveText;
+  const liveText = cuesUseAssSyntax(options.cues)
+    ? removeAssControlDebrisLines(options.liveText)
+    : options.liveText;
+  if (!liveText.trim()) {
+    return liveText;
  }
  return (
    resolveCanonicalPrimarySubtitle({
-      liveText: options.liveText,
+      liveText,
      currentTimeSec: options.currentTimeSec,
      cues: options.cues,
    })?.text ??
-    resolveActiveParsedPrimarySubtitle(options)?.text ??
-    options.liveText
+    resolveActiveParsedPrimarySubtitle({ ...options, liveText })?.text ??
+    removeLiveGlyphFragmentLines(liveText)
  );
 }
@@ -20,6 +20,32 @@ test('findActiveSubtitleText combines unique simultaneous parsed cues', () => {
  );
 });

+test('findActiveSubtitleText removes duplicate lines across multiline cues', () => {
+  assert.equal(
+    findActiveSubtitleText(
+      [
+        { startTime: 1, endTime: 3, text: 'First line\nSecond line' },
+        { startTime: 1, endTime: 3, text: 'First line' },
+      ],
+      2,
+    ),
+    'First line\nSecond line',
+  );
+});
+
+test('findActiveSubtitleText removes equivalent full-width duplicate lines', () => {
+  assert.equal(
+    findActiveSubtitleText(
+      [
+        { startTime: 1, endTime: 3, text: '真白～' },
+        { startTime: 1, endTime: 3, text: '真白~' },
+      ],
+      2,
+    ),
+    '真白～',
+  );
+});
+
 test('findActiveSubtitleText collapses whitespace variants of one ASS lyric', () => {
  assert.equal(
    findActiveSubtitleText(
@@ -72,6 +98,22 @@ test('parsed secondary text drops a reconstructed grid of positioned sign fragme
  );
 });

+test('parsed secondary text keeps phone translations while dropping texture payloads', () => {
+  const ass = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    'Dialogue: 2,0:00:01.00,0:00:03.00,FrogSigns,,0,0,0,,{\\pos(580,95)\\fnGrain Medium\\clip(500,40,660,150)}LLLLLLLLLLLL',
+    'Dialogue: 90,0:00:01.00,0:00:03.00,Default,,0,0,0,,Why did you choose Hanajo instead?',
+    "Dialogue: 1,0:00:01.00,0:00:03.00,FrogSigns,,0,0,0,,{\\pos(580,95)\\fnGrain\\fs10\\alpha&H70&}q26D'vrA;\\NE? GS\\NESLhlawEv",
+    "Dialogue: 3,0:00:01.00,0:00:03.00,FrogSigns,,0,0,0,,{\\pos(582,180)\\fnSF Pro Display\\fs66}We're {\\2a0}running {\\2a1}out {\\2a0}of {\\2a1}time!\\N{\\2a0}Where {\\2a1}are {\\2a0}you {\\2a1}right {\\2a0}now?!",
+  ].join('\n');
+
+  assert.equal(
+    findActiveSubtitleText(parseSubtitleCues(ass, 'phone.ass'), 2),
+    "Why did you choose Hanajo instead?\nWe're running out of time!\nWhere are you right now?!",
+  );
+});
+
 test('parsed secondary lyrics keep explicit ASS vertical order when durations alternate', () => {
  const lyric = (options: { start: string; end: string; style: string; y: number; text: string }) =>
    `Dialogue: 0,0:00:${options.start},0:00:${options.end},${options.style},,0,0,0,fx,{\\move(100,${options.y},120,${options.y})\\t(0,200,\\fscx110)}${options.text}\\N{\\p1}m 0 0 l 0 5`;
@@ -144,6 +186,30 @@ test('findActiveSubtitleText keeps a canonical ASS cue for its generated animati
  assert.equal(findActiveSubtitleText([poof], 1111.59), '');
 });

+test('findActiveSubtitleText advances when the next canonical lyric animation starts', () => {
+  const cues = [
+    {
+      startTime: 121.73,
+      endTime: 124.1,
+      text: 'Torn at the seams, a sound pours out',
+      source: 'canonical-ass' as const,
+      animationStartTime: 121.4,
+      animationEndTime: 124.1,
+    },
+    {
+      startTime: 124.13,
+      endTime: 126.38,
+      text: 'It’s silent, yet spreads all around',
+      source: 'canonical-ass' as const,
+      animationStartTime: 123.8,
+      animationEndTime: 126.38,
+    },
+  ];
+
+  assert.equal(findActiveSubtitleText(cues, 123.79), cues[0]!.text);
+  assert.equal(findActiveSubtitleText(cues, 123.8), cues[1]!.text);
+});
+
 test('ASS fragment karaoke stays separated by style with authored word spacing', () => {
  const lineEvents = (
    style: string,
@@ -380,6 +446,125 @@ test('secondary track controller falls back to live mpv text without a readable
  assert.deepEqual(broadcasts, ['live fallback']);
 });

+test('secondary ASS live fallback drops malformed control debris', async () => {
+  const broadcasts: string[] = [];
+  const controller = createSecondarySubtitleTrackController({
+    getMpvClient: () => ({
+      connected: true,
+      requestProperty: async (name) => {
+        if (name === 'secondary-sid') return 2;
+        if (name === 'track-list') return [{ type: 'sub', id: 2 }];
+        if (name === 'path') return '/media/video.mkv';
+        return null;
+      },
+    }),
+    getCurrentTimePos: () => 2,
+    resolveSubtitleSource: async () => ({ path: '/subs/english.ass', sourceKey: 'english' }),
+    loadSubtitleSourceText: async () => '',
+    parseSubtitleCues: () => [],
+    setCurrentSecondaryText: () => {},
+    broadcastSecondaryText: (text) => broadcasts.push(text),
+  });
+
+  await controller.refresh();
+  broadcasts.length = 0;
+  controller.handleLiveText('Visible line\n\\\n{\\fr0');
+
+  assert.deepEqual(broadcasts, ['Visible line']);
+});
+
+test('secondary SRT live fallback preserves text that resembles ASS control debris', async () => {
+  const broadcasts: string[] = [];
+  const controller = createSecondarySubtitleTrackController({
+    getMpvClient: () => ({
+      connected: true,
+      requestProperty: async (name) => {
+        if (name === 'secondary-sid') return 2;
+        if (name === 'track-list') return [{ type: 'sub', id: 2 }];
+        if (name === 'path') return '/media/video.mkv';
+        return null;
+      },
+    }),
+    getCurrentTimePos: () => 2,
+    resolveSubtitleSource: async () => ({ path: '/subs/english.srt', sourceKey: 'english' }),
+    loadSubtitleSourceText: async () => '',
+    parseSubtitleCues: () => [],
+    setCurrentSecondaryText: () => {},
+    broadcastSecondaryText: (text) => broadcasts.push(text),
+  });
+
+  await controller.refresh();
+  broadcasts.length = 0;
+  controller.handleLiveText('Visible line\n\\\n{\\fr0');
+
+  assert.deepEqual(broadcasts, ['Visible line\n\\\n{\\fr0']);
+});
+
+test('secondary disconnect clears stale ASS fallback sanitization state', async () => {
+  let connected = true;
+  const broadcasts: string[] = [];
+  const controller = createSecondarySubtitleTrackController({
+    getMpvClient: () => ({
+      connected,
+      requestProperty: async (name) => {
+        if (name === 'secondary-sid') return 2;
+        if (name === 'track-list') return [{ type: 'sub', id: 2 }];
+        if (name === 'path') return '/media/video.mkv';
+        return null;
+      },
+    }),
+    getCurrentTimePos: () => 2,
+    resolveSubtitleSource: async () => ({ path: '/subs/english.ass', sourceKey: 'english' }),
+    loadSubtitleSourceText: async () => '',
+    parseSubtitleCues: () => [],
+    setCurrentSecondaryText: () => {},
+    broadcastSecondaryText: (text) => broadcasts.push(text),
+  });
+
+  await controller.refresh();
+  connected = false;
+  await controller.refresh();
+  broadcasts.length = 0;
+  controller.handleLiveText('Visible line\n\\\n{\\fr0');
+
+  assert.deepEqual(broadcasts, ['Visible line\n\\\n{\\fr0']);
+});
+
+test('secondary source refresh failure clears stale ASS fallback sanitization state', async () => {
+  let resolveCalls = 0;
+  const broadcasts: string[] = [];
+  const controller = createSecondarySubtitleTrackController({
+    getMpvClient: () => ({
+      connected: true,
+      requestProperty: async (name) => {
+        if (name === 'secondary-sid') return 2;
+        if (name === 'track-list') return [{ type: 'sub', id: 2 }];
+        if (name === 'path') return '/media/video.mkv';
+        return null;
+      },
+    }),
+    getCurrentTimePos: () => 2,
+    resolveSubtitleSource: async () => {
+      resolveCalls += 1;
+      if (resolveCalls === 1) {
+        return { path: '/subs/english.ass', sourceKey: 'english' };
+      }
+      throw new Error('source refresh failed');
+    },
+    loadSubtitleSourceText: async () => '',
+    parseSubtitleCues: () => [],
+    setCurrentSecondaryText: () => {},
+    broadcastSecondaryText: (text) => broadcasts.push(text),
+  });
+
+  await controller.refresh();
+  await controller.refresh();
+  broadcasts.length = 0;
+  controller.handleLiveText('Visible line\n\\\n{\\fr0');
+
+  assert.deepEqual(broadcasts, ['Visible line\n\\\n{\\fr0']);
+});
+
 test('secondary track controller reuses parsed cues for an unchanged embedded track', async () => {
  let resolveCalls = 0;
  let parseCalls = 0;
@@ -471,3 +656,36 @@ test('secondary track controller ignores and cleans up a refresh invalidated by
  assert.equal(parseCalls, 0);
  assert.equal(cleanupCalls, 1);
 });
+
+test('secondary live fallback suppresses a per-glyph typesetting wall', async () => {
+  let currentText = '';
+  const controller = createSecondarySubtitleTrackController({
+    getMpvClient: () => ({
+      connected: true,
+      requestProperty: async (name) => {
+        if (name === 'secondary-sid') return 2;
+        if (name === 'track-list') return [{ type: 'sub', id: 2 }];
+        if (name === 'path') return '/mnt/nas/video.mkv';
+        if (name === 'secondary-sub-delay') return 0;
+        return null;
+      },
+    }),
+    getCurrentTimePos: () => 1355,
+    // Network-mounted media: embedded extraction is skipped, so no parsed cues exist.
+    resolveSubtitleSource: async () => null,
+    loadSubtitleSourceText: async () => '',
+    parseSubtitleCues,
+    setCurrentSecondaryText: (text) => {
+      currentText = text;
+    },
+    broadcastSecondaryText: () => {},
+  });
+
+  await controller.refresh();
+  const wall = [...'wansdumretoikhI'].join('\n');
+  controller.handleLiveText(`${wall}\ntai`);
+  assert.equal(currentText, '');
+
+  controller.handleLiveText(`${wall}\nそれよりも　ノート…`);
+  assert.equal(currentText, 'それよりも　ノート…');
+});
@@ -1,5 +1,9 @@
 import type { SubtitleCue } from '../../types/subtitle';
 import { flattenedSecondarySubtitleLineIdentity } from '../../core/services/secondary-subtitle-line-identity';
+import {
+  removeAssControlDebrisLines,
+  removeLiveGlyphFragmentLines,
+} from '../../core/services/ass-text';

 type SecondarySubtitleMpvClient = {
  connected?: boolean;
@@ -23,6 +27,11 @@ type SecondarySubtitleSourceInput = {

 const DEFAULT_REFRESH_DELAY_MS = 500;

+function sourceUsesAssSyntax(source: string): boolean {
+  const sourceWithoutQuery = source.split(/[?#]/u, 1)[0] ?? '';
+  return /\.(?:ass|ssa)$/iu.test(sourceWithoutQuery);
+}
+
 function finiteNumber(value: unknown, fallback = 0): number {
  const number = typeof value === 'number' ? value : Number(value);
  return Number.isFinite(number) ? number : fallback;
@@ -82,7 +91,26 @@ export function findActiveSubtitleText(cues: readonly SubtitleCue[], timeSeconds
    (cue) =>
      cue.source === 'canonical-ass' && cue.startTime <= timeSeconds && cue.endTime > timeSeconds,
  );
-  const selectedCanonical = new Set<SubtitleCue>(authoredCanonical);
+  const enteringCanonical = cues.filter(
+    (cue) =>
+      cue.source === 'canonical-ass' &&
+      (cue.animationStartTime ?? cue.startTime) <= timeSeconds &&
+      cue.startTime > timeSeconds &&
+      (cue.animationEndTime ?? cue.endTime) > timeSeconds,
+  );
+  const nextAuthoredStart = enteringCanonical.reduce(
+    (earliest, cue) => Math.min(earliest, cue.startTime),
+    Infinity,
+  );
+  // Generated lyrics can begin drawing before their canonical Comment timing. Once that
+  // entrance starts, replace a preceding lyric that ends before the new authored span;
+  // genuinely concurrent subtitles that continue through the new span stay selected.
+  const selectedCanonical = new Set<SubtitleCue>([
+    ...authoredCanonical.filter(
+      (cue) => enteringCanonical.length === 0 || cue.endTime > nextAuthoredStart,
+    ),
+    ...enteringCanonical,
+  ]);
  if (selectedCanonical.size === 0) {
    const animatedCanonical = cues.filter(
      (cue) =>
@@ -153,15 +181,17 @@ export function findActiveSubtitleText(cues: readonly SubtitleCue[], timeSeconds
  activeCues.sort(compareAuthoredSubtitleOrder);

  for (const { cue } of activeCues) {
-    const text = cue.text.trim();
-    const compactText = text.replace(/\s+/gu, '');
-    if (!compactText || seenExact.has(compactText)) continue;
-    seenExact.add(compactText);
+    for (const line of cue.text.split('\n')) {
+      const text = line.trim();
+      const compactText = text.normalize('NFKC').replace(/\s+/gu, '');
+      if (!compactText || seenExact.has(compactText)) continue;
+      seenExact.add(compactText);

-    const flattenedIdentity = flattenedSecondarySubtitleLineIdentity(text);
-    if (flattenedIdentity && seenFlattened.has(flattenedIdentity)) continue;
-    if (flattenedIdentity) seenFlattened.add(flattenedIdentity);
-    activeText.push(text);
+      const flattenedIdentity = flattenedSecondarySubtitleLineIdentity(text);
+      if (flattenedIdentity && seenFlattened.has(flattenedIdentity)) continue;
+      if (flattenedIdentity) seenFlattened.add(flattenedIdentity);
+      activeText.push(text);
+    }
  }
  return activeText.join('\n');
 }
@@ -182,6 +212,7 @@ export function createSecondarySubtitleTrackController(deps: {
  let parsedCues: SubtitleCue[] | null = null;
  let parsedSourceKey: string | null = null;
  let parsedTrackIdentity: string | null = null;
+  let activeSourceUsesAssSyntax = false;
  let secondaryDelaySeconds = 0;
  let lastLiveText = '';
  let lastBroadcastText: string | null = null;
@@ -211,6 +242,7 @@ export function createSecondarySubtitleTrackController(deps: {
    const generation = ++refreshGeneration;
    const client = deps.getMpvClient();
    if (!client?.connected) {
+      activeSourceUsesAssSyntax = false;
      useLiveFallback();
      return;
    }
@@ -227,6 +259,7 @@ export function createSecondarySubtitleTrackController(deps: {

      const videoPath = typeof videoPathRaw === 'string' ? videoPathRaw.trim() : '';
      if (!videoPath || secondarySid === null || secondarySid === 'no') {
+        activeSourceUsesAssSyntax = false;
        useLiveFallback();
        return;
      }
@@ -248,11 +281,14 @@ export function createSecondarySubtitleTrackController(deps: {
      });
      if (generation !== refreshGeneration) return;
      if (!resolvedSource) {
+        activeSourceUsesAssSyntax = false;
        deps.logDebug?.('[secondary-subtitle-track] selected source is not readable');
        useLiveFallback();
        return;
      }

+      activeSourceUsesAssSyntax = sourceUsesAssSyntax(resolvedSource.path);
+
      if (resolvedSource.sourceKey === parsedSourceKey && parsedCues) {
        parsedTrackIdentity = selectedTrackIdentity;
        publish(resolveAtTime(deps.getCurrentTimePos()));
@@ -274,6 +310,7 @@ export function createSecondarySubtitleTrackController(deps: {
      publish(resolveAtTime(deps.getCurrentTimePos()));
    } catch (error) {
      if (generation !== refreshGeneration) return;
+      activeSourceUsesAssSyntax = false;
      deps.logWarn?.('[secondary-subtitle-track] failed to parse selected source', error);
      useLiveFallback();
    } finally {
@@ -296,6 +333,7 @@ export function createSecondarySubtitleTrackController(deps: {
    parsedCues = null;
    parsedSourceKey = null;
    parsedTrackIdentity = null;
+    activeSourceUsesAssSyntax = false;
    secondaryDelaySeconds = 0;
    lastLiveText = '';
    publish('');
@@ -305,7 +343,9 @@ export function createSecondarySubtitleTrackController(deps: {
    refresh,
    scheduleRefresh,
    handleLiveText(text: string): void {
-      lastLiveText = text;
+      lastLiveText = removeLiveGlyphFragmentLines(
+        activeSourceUsesAssSyntax ? removeAssControlDebrisLines(text) : text,
+      );
      publish(resolveAtTime(deps.getCurrentTimePos()));
    },
    handleTimePos(timeSeconds: number): void {
@@ -101,6 +101,32 @@ test('subtitle prefetch runtime preserves parsed cues when YouTube active track
  assert.deepEqual(calls, []);
 });

+test('subtitle prefetch runtime preserves parsed cues when a network mount source is unresolved', async () => {
+  const calls: string[] = [];
+  const refresh = createRefreshSubtitlePrefetchFromActiveTrackHandler({
+    getMpvClient: () => ({
+      connected: true,
+      requestProperty: async (name) => (name === 'path' ? '/Volumes/jellyfin/movie.mkv' : null),
+    }),
+    getLastObservedTimePos: () => 12,
+    subtitlePrefetchInitController: {
+      cancelPendingInit: () => {
+        calls.push('cancel');
+      },
+      initSubtitlePrefetch: async () => {
+        calls.push('init');
+      },
+    },
+    resolveActiveSubtitleSidebarSource: async () => null,
+    shouldKeepExistingCuesOnMissingSource: async (videoPath) =>
+      videoPath.startsWith('/Volumes/jellyfin/'),
+  });
+
+  await refresh();
+
+  assert.deepEqual(calls, []);
+});
+
 test('subtitle prefetch runtime does not extract internal subtitle tracks from remote media urls', async () => {
  let extracted = false;
  const resolveSource = createResolveActiveSubtitleSidebarSourceHandler({
@@ -131,6 +157,36 @@ test('subtitle prefetch runtime does not extract internal subtitle tracks from r
  assert.equal(extracted, false);
 });

+test('subtitle prefetch runtime extracts internal subtitle tracks from network-mounted media', async () => {
+  let extracted = false;
+  const resolveSource = createResolveActiveSubtitleSidebarSourceHandler({
+    getFfmpegPath: () => 'ffmpeg-custom',
+    extractInternalSubtitleTrack: async () => {
+      extracted = true;
+      return {
+        path: '/tmp/subminer-sidebar-123/track_7.ass',
+        cleanup: async () => {},
+      };
+    },
+  });
+
+  const resolved = await resolveSource({
+    currentExternalFilenameRaw: null,
+    currentTrackRaw: {
+      type: 'sub',
+      id: 3,
+      'ff-index': 7,
+      codec: 'ass',
+    },
+    trackListRaw: [],
+    sidRaw: 3,
+    videoPath: '/Volumes/jellyfin/movie.mkv',
+  });
+
+  assert.equal(resolved?.path, '/tmp/subminer-sidebar-123/track_7.ass');
+  assert.equal(extracted, true);
+});
+
 test('subtitle prefetch refresh logs a warning when source resolution throws', async () => {
  const warnings: string[] = [];
  const refresh = createRefreshSubtitlePrefetchFromActiveTrackHandler({
@@ -28,7 +28,7 @@ function parseTrackId(value: unknown): number | null {
  return null;
 }

-function isRemoteMediaPath(value: string): boolean {
+function isRemoteMediaUrl(value: string): boolean {
  try {
    const url = new URL(value);
    return url.protocol === 'http:' || url.protocol === 'https:';
@@ -126,7 +126,10 @@ export function createResolveActiveSubtitleSidebarSourceHandler(deps: {
      return { path: externalFilename, sourceKey: externalFilename };
    }

-    if (isRemoteMediaPath(input.videoPath)) {
+    // Network-mounted files extract like local ones: demuxing reads the whole
+    // container (~10s/GB on gigabit), which a LAN handles alongside playback.
+    // Only true remote URLs have no on-disk container to demux.
+    if (isRemoteMediaUrl(input.videoPath)) {
      deps.logDebug?.('[subtitle-prefetch] skipping internal subtitle extraction for remote media');
      return null;
    }
@@ -156,7 +159,7 @@ export function createRefreshSubtitlePrefetchFromActiveTrackHandler(deps: {
    requestProperty: (name: string) => Promise<unknown>;
  } | null;
  getLastObservedTimePos: () => number;
-  shouldKeepExistingCuesOnMissingSource?: (videoPath: string) => boolean;
+  shouldKeepExistingCuesOnMissingSource?: (videoPath: string) => boolean | Promise<boolean>;
  subtitlePrefetchInitController: SubtitlePrefetchInitController;
  resolveActiveSubtitleSidebarSource: (
    input: Parameters<ReturnType<typeof createResolveActiveSubtitleSidebarSourceHandler>>[0],
@@ -195,7 +198,7 @@ export function createRefreshSubtitlePrefetchFromActiveTrackHandler(deps: {
        videoPath,
      });
      if (!resolvedSource) {
-        if (deps.shouldKeepExistingCuesOnMissingSource?.(videoPath) === true) {
+        if ((await deps.shouldKeepExistingCuesOnMissingSource?.(videoPath)) === true) {
          deps.logDebug?.(
            '[subtitle-prefetch] no active subtitle source resolved; keeping existing cues',
          );
@@ -2,9 +2,17 @@ import test from 'node:test';
 import assert from 'node:assert/strict';
 import { readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
+import {
+  jobSteps,
+  readWorkflow,
+  stepRunsCommand,
+  stepsMissingEnvDeclaration,
+  templateExpressionsInRunBodies,
+} from './workflow-test-helpers';

 const prereleaseWorkflowPath = resolve(__dirname, '../.github/workflows/prerelease.yml');
 const prereleaseWorkflow = readFileSync(prereleaseWorkflowPath, 'utf8').replace(/\r\n/g, '\n');
+const parsedPrereleaseWorkflow = readWorkflow(prereleaseWorkflowPath);
 const packageJsonPath = resolve(__dirname, '../package.json');
 const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf8')) as {
  scripts: Record<string, string>;
@@ -122,3 +130,33 @@ test('prerelease workflow does not publish to AUR', () => {
  assert.doesNotMatch(prereleaseWorkflow, /AUR_SSH_PRIVATE_KEY/);
  assert.doesNotMatch(prereleaseWorkflow, /scripts\/update-aur-package\.sh/);
 });
+
+test('prerelease workflow rejects committed notes generated for a different beta or rc', () => {
+  assert.equal(
+    packageJson.scripts['changelog:check-prerelease-notes'],
+    'bun run scripts/build-changelog.ts check-prerelease-notes',
+  );
+
+  // Matched at command positions only, so commenting the check out or quoting it
+  // inside an echo fails the test rather than silently satisfying it.
+  const steps = jobSteps(parsedPrereleaseWorkflow, 'release');
+  const checkIndex = steps.findIndex((step) =>
+    stepRunsCommand(
+      step,
+      /^bun run changelog:check-prerelease-notes --version "\$RELEASE_VERSION"/,
+    ),
+  );
+  const publishIndex = steps.findIndex((step) =>
+    stepRunsCommand(step, /^gh release (create|edit)\b/),
+  );
+
+  assert.notEqual(checkIndex, -1);
+  assert.notEqual(publishIndex, -1);
+  // Stale notes are already published if the check runs after the release.
+  assert.ok(checkIndex < publishIndex);
+});
+
+test('prerelease workflow keeps tag-derived values out of shell bodies', () => {
+  assert.deepEqual(templateExpressionsInRunBodies(parsedPrereleaseWorkflow), []);
+  assert.deepEqual(stepsMissingEnvDeclaration(parsedPrereleaseWorkflow, 'RELEASE_VERSION'), []);
+});
@@ -2,11 +2,18 @@ import test from 'node:test';
 import assert from 'node:assert/strict';
 import { readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
+import {
+  readWorkflow,
+  stepsMissingEnvDeclaration,
+  templateExpressionsInRunBodies,
+} from './workflow-test-helpers';

 const releaseWorkflowPath = resolve(__dirname, '../.github/workflows/release.yml');
 const releaseWorkflow = readFileSync(releaseWorkflowPath, 'utf8');
 const docsPagesWorkflowPath = resolve(__dirname, '../.github/workflows/docs-pages.yml');
 const docsPagesWorkflow = readFileSync(docsPagesWorkflowPath, 'utf8');
+const parsedReleaseWorkflow = readWorkflow(releaseWorkflowPath);
+const parsedDocsPagesWorkflow = readWorkflow(docsPagesWorkflowPath);
 const makefilePath = resolve(__dirname, '../Makefile');
 const makefile = readFileSync(makefilePath, 'utf8');
 const packageJsonPath = resolve(__dirname, '../package.json');
@@ -249,7 +256,7 @@ test('release workflow publishes subminer-bin to AUR from tagged release artifac
    releaseWorkflow,
    /cp packaging\/aur\/subminer-bin\/\.SRCINFO aur-subminer-bin\/\.SRCINFO/,
  );
-  assert.match(releaseWorkflow, /version_no_v="\$\{\{ steps\.version\.outputs\.VERSION \}\}"/);
+  assert.match(releaseWorkflow, /version_no_v="\$RELEASE_VERSION"/);
  assert.match(releaseWorkflow, /SubMiner-\$\{version_no_v\}\.AppImage/);
  assert.doesNotMatch(
    releaseWorkflow,
@@ -278,3 +285,14 @@ test('Makefile uninstall targets remove bundled runtime plugin app-data copies',
  assert.match(makefile, /Removed:[\s\S]*\$\(LINUX_DATA_DIR\)\/plugin\/subminer/);
  assert.match(makefile, /Removed:[\s\S]*\$\(MACOS_DATA_DIR\)\/plugin\/subminer/);
 });
+
+test('release and docs workflows keep tag-derived values out of shell bodies', () => {
+  assert.deepEqual(templateExpressionsInRunBodies(parsedReleaseWorkflow), []);
+  assert.deepEqual(templateExpressionsInRunBodies(parsedDocsPagesWorkflow), []);
+  assert.deepEqual(stepsMissingEnvDeclaration(parsedReleaseWorkflow, 'RELEASE_VERSION'), []);
+  assert.deepEqual(stepsMissingEnvDeclaration(parsedDocsPagesWorkflow, 'TAG_NAME'), []);
+
+  // The docs tag guard must test the shell variable, not an interpolated value
+  // that would be substituted into the condition before the shell reads it.
+  assert.match(docsPagesWorkflow, /if \[\[ ! "\$TAG_NAME" =~/);
+});
@@ -1928,10 +1928,6 @@ body.layer-modal #overlay {
  text-align: center;
  font-size: 24px;
  line-height: 1.5;
-  /* Backstop: pathological tracks (karaoke typesetting, sign spam) must never grow
-     the hover-pause band beyond a top strip. ~4 lines at line-height 1.5. */
-  max-height: 6em;
-  overflow: hidden;
  color: #ffffff;
  -webkit-text-stroke: 0.45px rgba(0, 0, 0, 0.7);
  paint-order: stroke fill;
@@ -1424,11 +1424,8 @@ test('subtitle annotation CSS underlines JLPT tokens without changing token colo
  );
 });

-test('prepareSecondarySubtitleLines preserves short stacks without layer metadata', () => {
+test('prepareSecondarySubtitleLines collapses exact short copies in stacks', () => {
  assert.deepEqual(prepareSecondarySubtitleLines('Your\\NYour\\NYour\\NYour\\Nmosaic'), [
-    'Your',
-    'Your',
-    'Your',
    'Your',
    'mosaic',
  ]);
@@ -1438,6 +1435,15 @@ test('prepareSecondarySubtitleLines preserves short stacks without layer metadat
  ]);
 });

+test('prepareSecondarySubtitleLines collapses exact short sign copies beside dialogue', () => {
+  const liveText = "And for today's sports festival...\nEntrance\nEntrance";
+
+  assert.deepEqual(prepareSecondarySubtitleLines(liveText), [
+    "And for today's sports festival...",
+    'Entrance',
+  ]);
+});
+
 test('prepareSecondarySubtitleLines collapses karaoke syllable spam into one deduped line', () => {
  // Karaoke-typeset OP/ED: one ASS event per syllable, duplicated across layers,
  // joined with \N by mpv's secondary-sub-text.
@@ -1448,10 +1454,10 @@ test('prepareSecondarySubtitleLines collapses karaoke syllable spam into one ded
  assert.deepEqual(prepareSecondarySubtitleLines(karaoke), ['ya This no ma ups']);
 });

-test('prepareSecondarySubtitleLines preserves repeated short dialogue without layer metadata', () => {
+test('prepareSecondarySubtitleLines collapses exact repeated short lines', () => {
  const dialogue = ['Wait', 'Wait', 'Wait'];

-  assert.deepEqual(prepareSecondarySubtitleLines(dialogue.join('\\N')), dialogue);
+  assert.deepEqual(prepareSecondarySubtitleLines(dialogue.join('\\N')), ['Wait']);
 });

 test('prepareSecondarySubtitleLines collapses punctuation variants of a full-sentence fallback', () => {
@@ -1469,6 +1475,10 @@ test('prepareSecondarySubtitleLines preserves short simultaneous dialogue withou
  assert.deepEqual(prepareSecondarySubtitleLines(dialogue.join('\\N')), dialogue);
 });

+test('prepareSecondarySubtitleLines preserves distinct short lines with internal whitespace', () => {
+  assert.deepEqual(prepareSecondarySubtitleLines('AB\\NA B'), ['AB', 'A B']);
+});
+
 test('prepareSecondarySubtitleLines keeps normal dialogue lines intact', () => {
  const dialogue = ' I never expected this. \\N\\N But here we are. ';

@@ -1490,13 +1500,13 @@ test('prepareSecondarySubtitleLines strips ASS override tags and handles empty i
  assert.deepEqual(prepareSecondarySubtitleLines('{\\an8}'), []);
 });

-test('secondary subtitle root CSS caps height so hover-pause band stays a top strip', () => {
+test('secondary subtitle root CSS does not clip long subtitle stacks', () => {
  const srcCssPath = path.join(process.cwd(), 'src', 'renderer', 'style.css');
  const cssText = fs.readFileSync(srcCssPath, 'utf-8');

  const secondaryRootBlock = extractClassBlock(cssText, '#secondarySubRoot');
-  assert.match(secondaryRootBlock, /max-height:\s*6em;/);
-  assert.match(secondaryRootBlock, /overflow:\s*hidden;/);
+  assert.doesNotMatch(secondaryRootBlock, /max-height\s*:/);
+  assert.doesNotMatch(secondaryRootBlock, /overflow\s*:\s*hidden/);
 });

 test('applySubtitleStyle sets known-word maturity color variables', () => {
@@ -667,12 +667,17 @@ function isKaraokeLikeLineSet(lines: string[]): boolean {
 }

 function collapseFullLineFallbackCopies(lines: string[]): string[] {
-  const seen = new Set<string>();
+  const seenExact = new Set<string>();
+  const seenFlattened = new Set<string>();
  return lines.filter((line) => {
-    const identity = flattenedSecondarySubtitleLineIdentity(line);
-    if (!identity) return true;
-    if (seen.has(identity)) return false;
-    seen.add(identity);
+    const exactIdentity = line.normalize('NFKC');
+    if (seenExact.has(exactIdentity)) return false;
+    seenExact.add(exactIdentity);
+
+    const flattenedIdentity = flattenedSecondarySubtitleLineIdentity(line);
+    if (!flattenedIdentity) return true;
+    if (seenFlattened.has(flattenedIdentity)) return false;
+    seenFlattened.add(flattenedIdentity);
    return true;
  });
 }
@@ -0,0 +1,97 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  commandPositions,
+  executableRunLines,
+  stepRunsCommand,
+  stepsMissingEnvDeclaration,
+  templateExpressionsInRunBodies,
+} from './workflow-test-helpers';
+
+const runs = (run: string): boolean => stepRunsCommand({ run }, /^bun run verify --flag "\$VALUE"/);
+
+test('stepRunsCommand matches a command that actually executes', () => {
+  assert.equal(runs('bun run verify --flag "$VALUE"'), true);
+  assert.equal(runs('if ! bun run verify --flag "$VALUE"; then\nexit 1\nfi'), true);
+  assert.equal(runs('set -e && bun run verify --flag "$VALUE"'), true);
+  assert.equal(runs('  bun run verify --flag "$VALUE" || exit 1'), true);
+});
+
+test('stepRunsCommand rejects commands that are only mentioned, not run', () => {
+  assert.equal(runs('# bun run verify --flag "$VALUE"'), false);
+  assert.equal(runs('echo \'bun run verify --flag "$VALUE"\''), false);
+  assert.equal(runs("printf '%s\\n' 'bun run verify --flag \"$VALUE\"'"), false);
+  assert.equal(runs('echo "run: bun run verify --flag \\"$VALUE\\"" >> notes.txt'), false);
+  // A different argument list is a different command.
+  assert.equal(runs('bun run verify'), false);
+});
+
+test('stepRunsCommand ignores separators inside quotes and inline comments', () => {
+  assert.equal(runs('echo \'note; bun run verify --flag "$VALUE"\''), false);
+  assert.equal(runs('echo "note && bun run verify --flag \\"$VALUE\\""'), false);
+  assert.equal(runs("printf '%s\\n' 'a | bun run verify --flag \"$VALUE\"'"), false);
+  assert.equal(runs('if false; then # bun run verify --flag "$VALUE"'), false);
+  // A trailing comment does not hide the command in front of it.
+  assert.equal(runs('bun run verify --flag "$VALUE" # keep this'), true);
+  // A pipe is a real separator; a redirect is not.
+  assert.equal(runs('cat notes | bun run verify --flag "$VALUE"'), true);
+  assert.equal(stepRunsCommand({ run: 'gh release view "$V" 2>&1 | tee log' }, /^tee\b/), true);
+});
+
+test('stepRunsCommand treats backslash-escaped separators as literal text', () => {
+  assert.equal(runs(String.raw`echo foo \; bun run verify --flag "$VALUE"`), false);
+  assert.equal(runs(String.raw`echo foo \| bun run verify --flag "$VALUE"`), false);
+  assert.equal(runs(String.raw`find . -exec bun run verify --flag "$VALUE" \;`), false);
+  // An escape does not swallow a following real separator.
+  assert.equal(runs(String.raw`echo a\b; bun run verify --flag "$VALUE"`), true);
+});
+
+test('commandPositions splits on separators and strips control-flow prefixes', () => {
+  assert.deepEqual(
+    commandPositions({ run: 'if gh release view "$V"; then\ngh release edit "$V"\nfi' }),
+    ['gh release view "$V"', 'then', 'gh release edit "$V"', 'fi'],
+  );
+});
+
+test('executableRunLines drops blank and comment-only lines', () => {
+  assert.deepEqual(executableRunLines({ run: '\n# a comment\n  \nreal command\n' }), [
+    'real command',
+  ]);
+});
+
+test('templateExpressionsInRunBodies reports every expression spelling in a run body', () => {
+  const workflow = {
+    jobs: {
+      release: {
+        steps: [
+          { name: 'Safe', env: { V: '${{ steps.version.outputs.VERSION }}' }, run: 'echo "$V"' },
+          { name: 'Dotted', run: 'echo "${{ steps.version.outputs.VERSION }}"' },
+          { name: 'Bracketed', run: 'echo "${{ steps.version.outputs[\'VERSION\'] }}"' },
+          { name: 'Github', run: 'echo "${{ github[\'ref_name\'] }}"' },
+        ],
+      },
+    },
+  };
+
+  assert.deepEqual(templateExpressionsInRunBodies(workflow), [
+    'release/Dotted: ${{ steps.version.outputs.VERSION }}',
+    "release/Bracketed: ${{ steps.version.outputs['VERSION'] }}",
+    "release/Github: ${{ github['ref_name'] }}",
+  ]);
+});
+
+test('stepsMissingEnvDeclaration finds shell reads with no matching env entry', () => {
+  const workflow = {
+    jobs: {
+      release: {
+        steps: [
+          { name: 'Declared', env: { TAG: 'x' }, run: 'echo "$TAG"' },
+          { name: 'Undeclared', run: 'echo "${TAG}"' },
+          { name: 'Unrelated', run: 'echo "$TAGGED"' },
+        ],
+      },
+    },
+  };
+
+  assert.deepEqual(stepsMissingEnvDeclaration(workflow, 'TAG'), ['release/Undeclared']);
+});
@@ -0,0 +1,169 @@
+import { readFileSync } from 'node:fs';
+
+export type WorkflowStep = {
+  name?: string;
+  run?: string;
+  env?: Record<string, unknown>;
+};
+
+export type ParsedWorkflow = {
+  jobs?: Record<string, { steps?: WorkflowStep[] } | undefined>;
+};
+
+// Workflow tests only ever run under `bun test`, which parses YAML natively.
+function parseWorkflowYaml(source: string): ParsedWorkflow {
+  const bunRuntime = globalThis as typeof globalThis & {
+    Bun?: { YAML?: { parse?: (input: string) => unknown } };
+  };
+  const parse = bunRuntime.Bun?.YAML?.parse;
+  if (!parse) {
+    throw new Error('Bun.YAML.parse is unavailable; workflow tests must run under bun.');
+  }
+  return parse(source) as ParsedWorkflow;
+}
+
+export function readWorkflow(workflowPath: string): ParsedWorkflow {
+  return parseWorkflowYaml(readFileSync(workflowPath, 'utf8'));
+}
+
+// Steps of one job, in declaration order. Throws on an unknown job so a renamed
+// job fails loudly instead of silently emptying an ordering assertion.
+export function jobSteps(workflow: ParsedWorkflow, jobName: string): WorkflowStep[] {
+  const job = workflow.jobs?.[jobName];
+  if (!job) {
+    throw new Error(`Workflow has no job named ${jobName}.`);
+  }
+  return job.steps ?? [];
+}
+
+function allSteps(workflow: ParsedWorkflow): Array<{ job: string; step: WorkflowStep }> {
+  return Object.entries(workflow.jobs ?? {}).flatMap(([job, definition]) =>
+    (definition?.steps ?? []).map((step) => ({ job, step })),
+  );
+}
+
+// Lines of a step's shell body that actually execute. Comments are dropped so a
+// commented-out command cannot satisfy a "this step runs X" assertion.
+export function executableRunLines(step: WorkflowStep): string[] {
+  return (typeof step.run === 'string' ? step.run.split('\n') : [])
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0 && !line.startsWith('#'));
+}
+
+// Leading shell keywords and operators that can precede a real command.
+const COMMAND_PREFIX = /^(?:if|elif|while|until|then|else|do|!|&&|\|\||\(|\{)\s+/;
+
+// Splits one shell line on command separators, tracking quotes so a separator
+// inside a string is not treated as a command break, and stopping at an
+// unquoted inline comment.
+function splitCommandSeparators(line: string): string[] {
+  const segments: string[] = [];
+  let current = '';
+  let quote: "'" | '"' | null = null;
+
+  for (let index = 0; index < line.length; index += 1) {
+    const char = line[index]!;
+
+    if (quote) {
+      current += char;
+      if (char === '\\' && quote === '"' && index + 1 < line.length) {
+        current += line[index + 1]!;
+        index += 1;
+      } else if (char === quote) {
+        quote = null;
+      }
+      continue;
+    }
+
+    // An unquoted backslash escapes the next character, so `\;` is literal text
+    // rather than a separator. Checked before comments and separators.
+    if (char === '\\' && index + 1 < line.length) {
+      current += char + line[index + 1]!;
+      index += 1;
+      continue;
+    }
+
+    if (char === "'" || char === '"') {
+      quote = char;
+      current += char;
+      continue;
+    }
+
+    // An unquoted # starts a comment when it opens a word; the rest is inert.
+    if (char === '#' && (current === '' || /\s$/.test(current))) {
+      break;
+    }
+
+    const next = line[index + 1];
+    if (char === ';') {
+      segments.push(current);
+      current = '';
+      continue;
+    }
+    if ((char === '&' || char === '|') && next === char) {
+      segments.push(current);
+      current = '';
+      index += 1;
+      continue;
+    }
+    // A lone pipe separates commands; a redirect such as 2>&1 does not.
+    if (char === '|' && !/[0-9<>&]$/.test(current)) {
+      segments.push(current);
+      current = '';
+      continue;
+    }
+
+    current += char;
+  }
+
+  segments.push(current);
+  return segments;
+}
+
+// Command positions within a step's shell body: each line split on separators,
+// with control-flow prefixes stripped. A pattern anchored with ^ therefore
+// matches only where a command actually starts, so text quoted inside an
+// `echo`/`printf` argument is not mistaken for the command running.
+export function commandPositions(step: WorkflowStep): string[] {
+  return executableRunLines(step).flatMap((line) =>
+    splitCommandSeparators(line)
+      .map((segment) => {
+        let candidate = segment.trim();
+        let stripped = candidate.replace(COMMAND_PREFIX, '');
+        while (stripped !== candidate) {
+          candidate = stripped;
+          stripped = candidate.replace(COMMAND_PREFIX, '');
+        }
+        return candidate;
+      })
+      .filter(Boolean),
+  );
+}
+
+// Whether a step actually executes a command matching the pattern. Anchor the
+// pattern with ^ so it has to match at a command position.
+export function stepRunsCommand(step: WorkflowStep, pattern: RegExp): boolean {
+  return commandPositions(step).some((position) => pattern.test(position));
+}
+
+// GitHub substitutes ${{ }} into a run script before the shell parses it, so any
+// value used that way is executed as script rather than read as data. Reporting
+// every expression (rather than allow-listing known-safe ones) also covers
+// alternate spellings such as ${{ steps.version.outputs['VERSION'] }}.
+export function templateExpressionsInRunBodies(workflow: ParsedWorkflow): string[] {
+  return allSteps(workflow).flatMap(({ job, step }) =>
+    (typeof step.run === 'string' ? (step.run.match(/\$\{\{[\s\S]*?\}\}/g) ?? []) : []).map(
+      (expression) => `${job}/${step.name ?? '<unnamed>'}: ${expression}`,
+    ),
+  );
+}
+
+// Steps whose shell body reads $NAME without the step declaring it in env, which
+// would silently expand to an empty string at run time.
+export function stepsMissingEnvDeclaration(workflow: ParsedWorkflow, name: string): string[] {
+  const reference = new RegExp(`\\$${name}\\b|\\$\\{${name}\\b`);
+  return allSteps(workflow)
+    .filter(({ step }) => typeof step.run === 'string' && reference.test(step.run))
+    .filter(({ step }) => !Object.prototype.hasOwnProperty.call(step.env ?? {}, name))
+    .map(({ job, step }) => `${job}/${step.name ?? '<unnamed>'}`);
+}
Author	SHA1	Message	Date
sudacode	a98fb0fddf	chore(release): prepare v0.19.4	2026-08-25 02:43:48 -07:00
sudacode	e816b3b371	fix(subtitles): recover positioned ASS word spacing and drop control debris (#217 )	2026-08-25 02:22:21 -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