@uimaxbai/am-lyrics 1.5.4 → 1.5.6

package/dist/src/react.js

@@ -322,7 +322,7 @@ class GoogleService {
     }
 }
 
-const VERSION = '1.5.4';
+const VERSION = '1.5.6';
 const INSTRUMENTAL_THRESHOLD_MS = 7000; // Show dots for gaps >= 7s
 const FETCH_TIMEOUT_MS = 8000; // Timeout for all lyrics fetch requests
 const SEEK_THRESHOLD_MS = 500;
@@ -331,6 +331,15 @@ const GAP_PULSE_DURATION_MS = 4000;
 const GAP_PULSE_CYCLE_MS = GAP_PULSE_DURATION_MS * 2;
 const GAP_EXIT_LEAD_MS = 600;
 const GAP_MIN_SCALE = 0.85;
+const NEXT_WORD_PRE_WIPE_MAX_GAP_MS = 180;
+const NEXT_WORD_PRE_WIPE_MIN_DURATION_MS = 80;
+const NEXT_WORD_PRE_WIPE_MAX_DURATION_MS = 240;
+const BASE_WIPE_GRADIENT_EM = 0.75;
+const LONG_WORD_WIPE_EXTRA_EM = 0.45;
+const LONG_WORD_WIPE_EXTRA_RATIO = 0.35;
+const SHORT_WORD_DRAG_MIN_DURATION_MS = 760;
+const SHORT_WORD_GLOW_MIN_DURATION_MS = 1320;
+const WORD_PRE_WIPE_HANDOFF_LEAD_MS = 100;
 /**
  * Fetch with an automatic timeout via AbortSignal.
  * Rejects if the request takes longer than `timeoutMs`.
@@ -392,6 +401,7 @@ let AmLyrics$1 = class AmLyrics extends i {
         this.activeLineIds = new Set();
         this.currentPrimaryActiveLine = null;
         this.lastPrimaryActiveLine = null;
+        this.backgroundExpandedLine = null;
         // Scroll animation state
         this.scrollAnimationState = null;
         this.currentScrollOffset = 0;
@@ -489,11 +499,12 @@ let AmLyrics$1 = class AmLyrics extends i {
             this.preActiveLineElements = [];
             this.positionedLineElements = [];
             this.activeGapLineElements = [];
+            this.clearBackgroundExpandedLine();
             // Stop all running animations and clear highlights immediately
             if (this.lyricsContainer) {
-                const activeLines = this.lyricsContainer.querySelectorAll('.lyrics-line.active, .lyrics-line.pre-active, .lyrics-line.bg-expanded');
+                const activeLines = this.lyricsContainer.querySelectorAll('.lyrics-line.active, .lyrics-line.pre-active, .lyrics-line.bg-expanded, .lyrics-line.scroll-exiting');
                 activeLines.forEach(line => {
-                    line.classList.remove('active', 'pre-active', 'bg-expanded');
+                    line.classList.remove('active', 'pre-active', 'bg-expanded', 'scroll-exiting');
                     AmLyrics.resetSyllables(line);
                 });
                 const activeGaps = this.lyricsContainer.querySelectorAll('.lyrics-gap.active, .lyrics-gap.gap-exiting');
@@ -521,7 +532,7 @@ let AmLyrics$1 = class AmLyrics extends i {
             switchBtn.disabled = this.isFetchingAlternatives;
         }
         if (svgEl) {
-            svgEl.setAttribute('style', `margin-right: 4px; ${this.isFetchingAlternatives ? 'animation: spin 1s linear infinite;' : ''}`);
+            svgEl.classList.toggle('is-loading', this.isFetchingAlternatives);
         }
         if (labelEl) {
             labelEl.textContent = this.isFetchingAlternatives
@@ -694,6 +705,7 @@ let AmLyrics$1 = class AmLyrics extends i {
         this.preActiveLineElements = [];
         this.positionedLineElements = [];
         this.activeGapLineElements = [];
+        this.clearBackgroundExpandedLine();
         if (this.lyricsContainer) {
             this.isProgrammaticScroll = true;
             this.lyricsContainer.scrollTop = 0;
@@ -761,14 +773,23 @@ let AmLyrics$1 = class AmLyrics extends i {
             return 21;
         return 30;
     }
+    static getDisplaySourceLabel(sourceLabel) {
+        return sourceLabel.toLowerCase().includes('lyricsplus')
+            ? 'QQ'
+            : sourceLabel;
+    }
+    static getSourceKey(sourceLabel) {
+        const lower = (sourceLabel || '').trim().toLowerCase();
+        if (!lower)
+            return '';
+        if (lower.includes('lyricsplus') || lower === 'qq')
+            return 'qq';
+        return lower.replace(/\s+/g, ' ');
+    }
     static mergeAndSortSources(collectedSources) {
         const uniqueSourcesMap = new Map();
         for (const source of collectedSources) {
-            const normalizedSource = source.source
-                .toLowerCase()
-                .includes('lyricsplus')
-                ? 'QQ'
-                : source.source;
+            const normalizedSource = AmLyrics.getDisplaySourceLabel(source.source);
             if (!uniqueSourcesMap.has(normalizedSource)) {
                 uniqueSourcesMap.set(normalizedSource, {
                     ...source,
@@ -779,9 +800,43 @@ let AmLyrics$1 = class AmLyrics extends i {
         return Array.from(uniqueSourcesMap.values()).sort((a, b) => AmLyrics.getRankForCollected(a.source, a.lines) -
             AmLyrics.getRankForCollected(b.source, b.lines));
     }
+    findCurrentSourceIndex(sources = this.availableSources, sourceLabel = this.lyricsSource, lines = this.lyrics) {
+        const identityIndex = sources.findIndex(source => source.lines === lines);
+        if (identityIndex !== -1)
+            return identityIndex;
+        const sourceKey = AmLyrics.getSourceKey(sourceLabel);
+        if (!sourceKey)
+            return -1;
+        return sources.findIndex(source => AmLyrics.getSourceKey(source.source) === sourceKey);
+    }
+    static getNextSourceIndex(sources, currentIndex, currentSourceLabel, currentLines) {
+        if (sources.length <= 1)
+            return -1;
+        if (currentIndex !== -1) {
+            return (currentIndex + 1) % sources.length;
+        }
+        const currentKey = AmLyrics.getSourceKey(currentSourceLabel);
+        const fallbackIndex = sources.findIndex(source => source.lines !== currentLines &&
+            AmLyrics.getSourceKey(source.source) !== currentKey);
+        return fallbackIndex === -1 ? 0 : fallbackIndex;
+    }
+    async applySourceAtIndex(index) {
+        const sourceResult = this.availableSources[index];
+        if (!sourceResult)
+            return;
+        this.currentSourceIndex = index;
+        this.lyrics = sourceResult.lines;
+        this.lyricsSource = sourceResult.source;
+        if (sourceResult.songwriters) {
+            this.songwriters = sourceResult.songwriters;
+        }
+        await this.onLyricsLoaded();
+    }
     async switchSource() {
         if (this.isFetchingAlternatives)
             return;
+        const currentSourceLabel = this.lyricsSource;
+        const currentLines = this.lyrics;
         if (!this.hasFetchedAllProviders) {
             this.isFetchingAlternatives = true;
             this._updateFooter();
@@ -824,10 +879,9 @@ let AmLyrics$1 = class AmLyrics extends i {
                             ...this.availableSources,
                             ...newSources,
                         ]);
-                        // Re-sync current index since sorting might shift elements
-                        this.currentSourceIndex = this.availableSources.findIndex(s => s.source === this.lyricsSource);
-                        if (this.currentSourceIndex === -1)
-                            this.currentSourceIndex = 0;
+                        // Re-sync current index since sorting or label normalization can
+                        // shift the currently displayed source underneath the old index.
+                        this.currentSourceIndex = this.findCurrentSourceIndex(this.availableSources, currentSourceLabel, currentLines);
                     }
                 }
             }
@@ -838,15 +892,11 @@ let AmLyrics$1 = class AmLyrics extends i {
             }
         }
         if (this.availableSources.length > 1) {
-            this.currentSourceIndex =
-                (this.currentSourceIndex + 1) % this.availableSources.length;
-            const sourceResult = this.availableSources[this.currentSourceIndex];
-            this.lyrics = sourceResult.lines;
-            this.lyricsSource = sourceResult.source;
-            if (sourceResult.songwriters) {
-                this.songwriters = sourceResult.songwriters;
+            const currentIndex = this.findCurrentSourceIndex(this.availableSources, currentSourceLabel, currentLines);
+            const nextIndex = AmLyrics.getNextSourceIndex(this.availableSources, currentIndex, currentSourceLabel, currentLines);
+            if (nextIndex !== -1) {
+                await this.applySourceAtIndex(nextIndex);
             }
-            await this.onLyricsLoaded();
         }
     }
     async resolveSongMetadata() {
@@ -1898,13 +1948,15 @@ let AmLyrics$1 = class AmLyrics extends i {
                     if (!newActiveLines.includes(lineIndex)) {
                         const lineElement = this._getLineElement(lineIndex);
                         if (lineElement) {
-                            if (isSeek || this.isUserScrolling) {
+                            if (isSeek ||
+                                this.isUserScrolling ||
+                                AmLyrics.isLineSyncedLine(this.lyrics?.[lineIndex])) {
                                 AmLyrics.unfinishSyllables(lineElement);
                             }
                             else {
                                 AmLyrics.finishSyllablesUpToTime(lineElement, newTime);
                             }
-                            lineElement.classList.remove('active', 'bg-expanded');
+                            lineElement.classList.remove('active', 'bg-expanded', 'scroll-exiting');
                             if (lineElement.classList.contains('pre-active')) {
                                 lineElement.classList.remove('pre-active');
                             }
@@ -1914,13 +1966,14 @@ let AmLyrics$1 = class AmLyrics extends i {
                         }
                     }
                 }
-                // Add 'active' and 'bg-expanded' to newly active lines
+                // Add 'active' to newly active lines. Background expansion is driven
+                // separately by the current scroll target.
                 for (const lineIndex of newActiveLines) {
                     if (!oldActiveLines.includes(lineIndex)) {
                         const lineElement = this._getLineElement(lineIndex);
                         if (lineElement) {
-                            lineElement.classList.add('active', 'bg-expanded');
-                            lineElement.classList.remove('pre-active');
+                            lineElement.classList.add('active');
+                            lineElement.classList.remove('pre-active', 'scroll-exiting');
                             const preIdx = this.preActiveLineElements.indexOf(lineElement);
                             if (preIdx !== -1)
                                 this.preActiveLineElements.splice(preIdx, 1);
@@ -2125,7 +2178,11 @@ let AmLyrics$1 = class AmLyrics extends i {
         }
     }
     updated(changedProperties) {
-        if (changedProperties.has('lyrics')) {
+        const lyricsDomBecameRenderable = changedProperties.has('lyrics') ||
+            (changedProperties.has('isLoading') &&
+                !this.isLoading &&
+                Boolean(this.lyrics));
+        if (lyricsDomBecameRenderable) {
             this._invalidateCaches();
             this._ensureLineDataCache();
             this._updateCachedIsUnsynced();
@@ -2139,8 +2196,12 @@ let AmLyrics$1 = class AmLyrics extends i {
                 for (const lineIndex of activeLines) {
                     const lineEl = this._getLineElement(lineIndex);
                     if (lineEl)
-                        lineEl.classList.add('active', 'bg-expanded');
+                        lineEl.classList.add('active');
                 }
+                const primaryActiveLine = this.getPrimaryActiveLineIndex(activeLines);
+                this.setBackgroundExpandedLine(primaryActiveLine !== null
+                    ? this._getLineElement(primaryActiveLine)
+                    : null);
                 // Trigger a faux time-change so that updateSyllablesForLine fires
                 // to setup inline syllable CSS wipe animations for whatever the current time is
                 this._onTimeChanged(0, this.currentTime);
@@ -2179,6 +2240,7 @@ let AmLyrics$1 = class AmLyrics extends i {
             this.preActiveLineElements = [];
             this.positionedLineElements = [];
             this.activeGapLineElements = [];
+            this.clearBackgroundExpandedLine();
             this.setUserScrolling(false);
             // Cancel any running animations
             if (this.animationFrameId) {
@@ -2233,6 +2295,7 @@ let AmLyrics$1 = class AmLyrics extends i {
         // Don't override it with a scroll back to the last lyric.
         const footer = this.lyricsContainer.querySelector('.lyrics-footer');
         if (footer?.classList.contains('active')) {
+            this.setBackgroundExpandedLine(null);
             return;
         }
         // 1. Compute scroll lookahead based on gap to next line (YouLyPlus style)
@@ -2273,17 +2336,23 @@ let AmLyrics$1 = class AmLyrics extends i {
                 targetElement = this._getLineElement(targetLineIdx);
             }
         }
-        if (!targetElement)
+        if (!targetElement) {
+            this.setBackgroundExpandedLine(null);
             return;
-        // Unblur the upcoming target line early (pre-active) so background
-        // vocals start their max-height/opacity transition in sync with scroll.
+        }
+        const scrollDuration = scrollLookAheadMs;
+        if (targetElement !== this.currentPrimaryActiveLine || forceScroll) {
+            targetElement.style.setProperty('--scroll-duration', `${scrollDuration}ms`);
+        }
+        this.setBackgroundExpandedLine(targetElement);
+        // Unblur the upcoming target line early while the separate bg-expanded
+        // class starts background vocal height/opacity in sync with scroll.
         if (!targetElement.classList.contains('active')) {
             targetElement.classList.add('pre-active');
             if (!this.preActiveLineElements.includes(targetElement)) {
                 this.preActiveLineElements.push(targetElement);
             }
         }
-        const scrollDuration = scrollLookAheadMs;
         this.focusLine(targetElement, forceScroll, scrollDuration);
     }
     _getTextWidth(text, font) {
@@ -2356,6 +2425,7 @@ let AmLyrics$1 = class AmLyrics extends i {
         this.preActiveLineElements = [];
         this.positionedLineElements = [];
         this.activeGapLineElements = [];
+        this.clearBackgroundExpandedLine();
         this.visibilityObserver?.disconnect();
         this.visibilityObserver = undefined;
     }
@@ -2391,6 +2461,7 @@ let AmLyrics$1 = class AmLyrics extends i {
             const groupGrowable = new Array(wordGroups.length).fill(false);
             const groupGlowing = new Array(wordGroups.length).fill(false);
             const groupCharRise = new Array(wordGroups.length).fill(false);
+            const groupCharDrag = new Array(wordGroups.length).fill(false);
             const vwFullText = new Array(wordGroups.length).fill('');
             const vwFullDuration = new Array(wordGroups.length).fill(0);
             const vwCharOffset = new Array(wordGroups.length).fill(0);
@@ -2426,28 +2497,42 @@ let AmLyrics$1 = class AmLyrics extends i {
                 const isLineSynced = line.isWordSynced === false || line.text.some(s => s.lineSynced);
                 let isGrowableVW = canAnimateByChar && wordLen > 0 && wordLen <= 7;
                 if (isGrowableVW) {
-                    if (wordLen < 3) {
+                    if (wordLen <= 1) {
                         isGrowableVW =
                             combinedDuration >= 1050 && combinedDuration >= wordLen * 525;
                     }
+                    else if (wordLen <= 3) {
+                        isGrowableVW =
+                            combinedDuration >=
+                                SHORT_WORD_GLOW_MIN_DURATION_MS + (wordLen - 2) * 140;
+                    }
                     else {
                         isGrowableVW =
                             combinedDuration >= 850 && combinedDuration >= wordLen * 190;
                     }
                 }
                 const hasCharRiseDuration = combinedDuration >= Math.max(700, wordLen * 85);
+                const hasTinyWordDragDuration = wordLen >= 2 &&
+                    wordLen <= 3 &&
+                    combinedDuration >=
+                        Math.max(SHORT_WORD_DRAG_MIN_DURATION_MS, wordLen * 150);
                 const hasLongShortWordDuration = wordLen >= 4 && combinedDuration >= Math.max(1300, wordLen * 260);
                 const isCharRiseVW = canAnimateByChar &&
                     !isLineSynced &&
                     !isGrowableVW &&
                     ((wordLen >= 8 && hasCharRiseDuration) ||
                         (wordLen < 8 && hasLongShortWordDuration));
+                const isCharDragVW = canAnimateByChar &&
+                    !isLineSynced &&
+                    !isGrowableVW &&
+                    hasTinyWordDragDuration;
                 const isGlowingVW = isGrowableVW && !isLineSynced;
                 let charOff = 0;
                 for (let gi = vwStart; gi <= vwEnd; gi += 1) {
                     groupGrowable[gi] = isGrowableVW;
                     groupGlowing[gi] = isGlowingVW;
                     groupCharRise[gi] = isCharRiseVW;
+                    groupCharDrag[gi] = isCharDragVW;
                     vwFullText[gi] = combinedText;
                     vwFullDuration[gi] = combinedDuration;
                     vwCharOffset[gi] = charOff;
@@ -2463,6 +2548,7 @@ let AmLyrics$1 = class AmLyrics extends i {
                 groupGrowable,
                 groupGlowing,
                 groupCharRise,
+                groupCharDrag,
                 vwFullText,
                 vwFullDuration,
                 vwCharOffset,
@@ -2482,48 +2568,106 @@ let AmLyrics$1 = class AmLyrics extends i {
             return;
         const computedStyle = getComputedStyle(referenceSyllable);
         const { font } = computedStyle; // Full font string
-        const fontSize = parseFloat(computedStyle.fontSize);
-        const charTimedWords = this.shadowRoot.querySelectorAll('.lyrics-word.growable, .lyrics-word.char-rise');
-        if (!charTimedWords)
+        const fontSize = Number.parseFloat(computedStyle.fontSize) || 16;
+        const charTimedWords = Array.from(this.shadowRoot.querySelectorAll('.lyrics-word.growable, .lyrics-word.char-rise, .lyrics-word.char-drag'));
+        if (charTimedWords.length === 0)
             return;
-        charTimedWords.forEach((wordSpan) => {
-            const syllableWraps = wordSpan.querySelectorAll('.lyrics-syllable-wrap');
-            // Flatten syllables
+        const wordsByVirtualId = new Map();
+        charTimedWords.forEach((wordSpan, index) => {
+            const virtualWordId = wordSpan.dataset.virtualWordId || `word-${index}`;
+            const words = wordsByVirtualId.get(virtualWordId);
+            if (words) {
+                words.push(wordSpan);
+            }
+            else {
+                wordsByVirtualId.set(virtualWordId, [wordSpan]);
+            }
+        });
+        wordsByVirtualId.forEach(wordSpans => {
             const syllables = [];
-            syllableWraps.forEach((wrap) => {
-                const syl = wrap.querySelector('.lyrics-syllable');
-                if (syl)
-                    syllables.push(syl);
+            wordSpans.forEach(wordSpan => {
+                const syllableWraps = wordSpan.querySelectorAll('.lyrics-syllable-wrap');
+                syllableWraps.forEach(wrap => {
+                    const syl = wrap.querySelector('.lyrics-syllable');
+                    if (syl)
+                        syllables.push(syl);
+                });
             });
-            syllables.forEach(sylSpan => {
-                const charSpans = sylSpan.querySelectorAll('.char');
-                if (charSpans.length === 0)
-                    return;
-                // Logic from YouLyPlus renderCharWipes:
-                // Use textContent from spans to ensure we measure what is rendered
-                const chars = Array.from(charSpans).map(span => span.textContent || '');
-                const charWidths = chars.map(c => this._getTextWidth(c, font));
-                const totalSyllableWidth = charWidths.reduce((a, b) => a + b, 0);
-                const duration = parseFloat(sylSpan.dataset.duration || '0');
-                const velocityPxPerMs = duration > 0 ? totalSyllableWidth / duration : 0;
-                // Gradient width in pixels = 0.375 * fontSize
-                // This matches YouLyPlus visual gradient size
-                const gradientWidthPx = 0.375 * fontSize;
-                const gradientDurationMs = velocityPxPerMs > 0 ? gradientWidthPx / velocityPxPerMs : 100;
-                let cumulativeCharWidth = 0;
-                charSpans.forEach((spanArg, i) => {
-                    const charWidth = charWidths[i];
-                    const span = spanArg;
-                    if (totalSyllableWidth > 0) {
-                        const startPercent = cumulativeCharWidth / totalSyllableWidth;
-                        const durationPercent = charWidth / totalSyllableWidth;
-                        span.dataset.wipeStart = startPercent.toFixed(4);
-                        span.dataset.wipeDuration = durationPercent.toFixed(4);
-                        // The critical missing piece:
-                        span.dataset.preWipeArrival = (duration * startPercent).toFixed(2);
-                        span.dataset.preWipeDuration = gradientDurationMs.toFixed(2);
+            const charSpans = syllables.flatMap(syl => {
+                const spans = Array.from(syl.querySelectorAll('.char'));
+                const target = syl;
+                target._cachedCharSpans = spans;
+                return spans;
+            });
+            if (charSpans.length === 0)
+                return;
+            wordSpans.forEach(wordSpan => {
+                const target = wordSpan;
+                target._cachedVirtualWordElements = wordSpans;
+                target._cachedVirtualWordCharSpans = charSpans;
+            });
+            const syllableEntries = syllables.map(syl => {
+                const spans = syl._cachedCharSpans;
+                const charWidths = spans.map(span => this._getTextWidth(span.textContent || '', font));
+                const totalWidth = charWidths.reduce((a, b) => a + b, 0);
+                return {
+                    syl,
+                    spans,
+                    charWidths,
+                    totalWidth,
+                    start: parseFloat(syl.getAttribute('data-start-time') || ''),
+                    end: parseFloat(syl.getAttribute('data-end-time') || ''),
+                };
+            });
+            const totalWordWidth = syllableEntries.reduce((total, entry) => total + entry.totalWidth, 0);
+            if (totalWordWidth <= 0)
+                return;
+            const virtualWordStart = Math.min(...syllableEntries
+                .map(entry => entry.start)
+                .filter(start => Number.isFinite(start)));
+            const virtualWordEnd = Math.max(...syllableEntries
+                .map(entry => entry.end)
+                .filter(end => Number.isFinite(end)));
+            const virtualWordDuration = virtualWordEnd - virtualWordStart;
+            const hasTimedSyllables = Number.isFinite(virtualWordStart) &&
+                Number.isFinite(virtualWordEnd) &&
+                virtualWordDuration > 0;
+            const wordVelocityPxPerMs = hasTimedSyllables
+                ? totalWordWidth / virtualWordDuration
+                : 0;
+            const gradientLeadWidthPx = (BASE_WIPE_GRADIENT_EM * Math.max(1, fontSize)) / 2;
+            const measuredPreWipeDuration = wordVelocityPxPerMs > 0
+                ? gradientLeadWidthPx / wordVelocityPxPerMs
+                : 100;
+            let cumulativeCharWidth = 0;
+            syllableEntries.forEach(entry => {
+                let cumulativeSyllableWidth = 0;
+                const syllableDuration = entry.end - entry.start;
+                const useSyllableTiming = hasTimedSyllables &&
+                    Number.isFinite(entry.start) &&
+                    Number.isFinite(entry.end) &&
+                    syllableDuration > 0 &&
+                    entry.totalWidth > 0;
+                entry.spans.forEach((span, index) => {
+                    const charWidth = entry.charWidths[index];
+                    let startPercent = cumulativeCharWidth / totalWordWidth;
+                    let durationPercent = charWidth / totalWordWidth;
+                    if (useSyllableTiming) {
+                        const charStartMs = entry.start -
+                            virtualWordStart +
+                            (cumulativeSyllableWidth / entry.totalWidth) * syllableDuration;
+                        const charDurationMs = (charWidth / entry.totalWidth) * syllableDuration;
+                        startPercent = AmLyrics.clamp(charStartMs / virtualWordDuration, 0, 1);
+                        durationPercent = AmLyrics.clamp(charDurationMs / virtualWordDuration, 0, 1);
                     }
+                    const target = span;
+                    target.dataset.wipeStart = startPercent.toFixed(4);
+                    target.dataset.wipeDuration = durationPercent.toFixed(4);
+                    target.dataset.preWipeDuration = measuredPreWipeDuration.toFixed(2);
+                    target.style.setProperty('--word-wipe-width', `${totalWordWidth}px`);
+                    target.style.setProperty('--char-wipe-position', `${-cumulativeCharWidth}px`);
                     cumulativeCharWidth += charWidth;
+                    cumulativeSyllableWidth += charWidth;
                 });
             });
         });
@@ -2531,6 +2675,33 @@ let AmLyrics$1 = class AmLyrics extends i {
     static arraysEqual(a, b) {
         return a.length === b.length && a.every((val, i) => val === b[i]);
     }
+    static isLineSyncedLine(line) {
+        if (!line)
+            return false;
+        return line.isWordSynced === false || line.text.some(s => s.lineSynced);
+    }
+    getLineHighlightEndTime(index) {
+        if (!this.lyrics)
+            return 0;
+        const line = this.lyrics[index];
+        if (!line)
+            return 0;
+        const rawEnd = Math.max(line.endtime, line.timestamp);
+        const nextLine = this.lyrics[index + 1];
+        if (!nextLine || nextLine.timestamp <= line.timestamp) {
+            return rawEnd > line.timestamp ? rawEnd + 200 : rawEnd;
+        }
+        if (rawEnd > line.timestamp) {
+            if (nextLine.timestamp < rawEnd) {
+                return rawEnd;
+            }
+            const gapToNext = nextLine.timestamp - rawEnd;
+            if (gapToNext >= INSTRUMENTAL_THRESHOLD_MS) {
+                return rawEnd;
+            }
+        }
+        return nextLine.timestamp;
+    }
     static getLineIndexFromElement(lineElement) {
         if (!lineElement)
             return null;
@@ -2561,6 +2732,26 @@ let AmLyrics$1 = class AmLyrics extends i {
         }
         this.preActiveLineElements = keptLines;
     }
+    setBackgroundExpandedLine(lineElement) {
+        const target = lineElement &&
+            !lineElement.classList.contains('lyrics-gap') &&
+            lineElement.querySelector('.background-vocal-container')
+            ? lineElement
+            : null;
+        if (this.backgroundExpandedLine === target) {
+            if (target && !target.classList.contains('bg-expanded')) {
+                target.classList.add('bg-expanded');
+            }
+            return;
+        }
+        this.backgroundExpandedLine?.classList.remove('bg-expanded');
+        this.backgroundExpandedLine = target;
+        target?.classList.add('bg-expanded');
+    }
+    clearBackgroundExpandedLine() {
+        this.backgroundExpandedLine?.classList.remove('bg-expanded');
+        this.backgroundExpandedLine = null;
+    }
     getPrimaryActiveLineIndex(activeIndices) {
         if (activeIndices.length === 0)
             return null;
@@ -2637,7 +2828,12 @@ let AmLyrics$1 = class AmLyrics extends i {
             // effectiveEndTimes).  Lines stay active until their extended end,
             // so we no longer need to remove .active here.
             this.lastPrimaryActiveLine = this.currentPrimaryActiveLine;
+            if (this.lastPrimaryActiveLine) {
+                this.lastPrimaryActiveLine.style.setProperty('--scroll-duration', `${scrollDuration ?? SCROLL_ANIMATION_DURATION_MS}ms`);
+                this.lastPrimaryActiveLine.classList.add('scroll-exiting');
+            }
             this.currentPrimaryActiveLine = lineElement;
+            this.currentPrimaryActiveLine.classList.remove('scroll-exiting');
             const lineIndex = AmLyrics.getLineIndexFromElement(lineElement);
             if (lineIndex !== null) {
                 this.lastActiveIndex = lineIndex;
@@ -2750,9 +2946,10 @@ let AmLyrics$1 = class AmLyrics extends i {
         const activeLines = [];
         for (let i = 0; i < this.lyrics.length; i += 1) {
             const line = this.lyrics[i];
+            const highlightEndTime = this.getLineHighlightEndTime(i);
             if (line.timestamp > time)
                 break;
-            if (time >= line.timestamp && time < line.endtime) {
+            if (time >= line.timestamp && time < highlightEndTime) {
                 activeLines.push(i);
             }
         }
@@ -2949,7 +3146,7 @@ let AmLyrics$1 = class AmLyrics extends i {
             allLines.forEach(lineEl => {
                 AmLyrics.resetSyllables(lineEl);
                 // Remove scroll-animate class and properties to stop any scroll animations
-                lineEl.classList.remove('scroll-animate');
+                lineEl.classList.remove('scroll-animate', 'scroll-exiting');
                 lineEl.style.removeProperty('--scroll-delta');
                 lineEl.style.removeProperty('--lyrics-line-delay');
             });
@@ -2977,6 +3174,7 @@ let AmLyrics$1 = class AmLyrics extends i {
         this.lastPrimaryActiveLine = null;
         this.activeLineIds.clear();
         this.animatingLines = [];
+        this.setBackgroundExpandedLine(null);
         // Find the clicked line element and scroll to it with forceScroll (like YouLyPlus)
         // Timestamps are already in milliseconds — match the data-start-time attribute directly
         const clickedLineElement = this.lyricsContainer?.querySelector(`.lyrics-line[data-start-time="${line.text[0]?.timestamp || 0}"]`);
@@ -2993,6 +3191,7 @@ let AmLyrics$1 = class AmLyrics extends i {
                 this.isClickSeeking = false;
             }, 800);
             this.scrollToActiveLineYouLy(clickedLineElement, true);
+            this.setBackgroundExpandedLine(clickedLineElement);
         }
         const event = new CustomEvent('line-click', {
             detail: {
@@ -3170,26 +3369,30 @@ let AmLyrics$1 = class AmLyrics extends i {
             return;
         const duration = Math.min(450, scrollDuration ?? SCROLL_ANIMATION_DURATION_MS);
         const delayIncrement = duration * 0.1;
+        const maxStaggerSteps = 4;
         const lookAhead = 20;
         const len = lineArray.length;
         const start = Math.max(0, referenceIndex - lookAhead);
         const end = Math.min(len, referenceIndex + lookAhead);
         let maxAnimationDuration = 0;
         const newAnimatingLines = [];
+        const lineDelays = new Map();
         const scrollingDown = delta >= 0;
         if (scrollingDown) {
             let delayCounter = 0;
             for (let i = start; i < end; i += 1) {
                 const line = lineArray[i];
-                const delay = i >= referenceIndex ? delayCounter * delayIncrement : 0;
+                const delay = i >= referenceIndex
+                    ? Math.min(delayCounter, maxStaggerSteps) * delayIncrement
+                    : 0;
                 if (i >= referenceIndex && !line.classList.contains('lyrics-gap')) {
                     delayCounter += 1;
                 }
                 line.style.setProperty('--scroll-delta', `${delta}px`);
                 line.style.setProperty('--lyrics-line-delay', `${delay}ms`);
-                line.style.setProperty('--scroll-duration', `${duration + 100}ms`);
+                lineDelays.set(line, delay);
                 newAnimatingLines.push(line);
-                const lineDuration = duration + delay;
+                const lineDuration = duration + 100 + delay;
                 if (lineDuration > maxAnimationDuration) {
                     maxAnimationDuration = lineDuration;
                 }
@@ -3199,20 +3402,28 @@ let AmLyrics$1 = class AmLyrics extends i {
             let delayCounter = 0;
             for (let i = end - 1; i >= start; i -= 1) {
                 const line = lineArray[i];
-                const delay = i <= referenceIndex ? delayCounter * delayIncrement : 0;
+                const delay = i <= referenceIndex
+                    ? Math.min(delayCounter, maxStaggerSteps) * delayIncrement
+                    : 0;
                 if (i <= referenceIndex && !line.classList.contains('lyrics-gap')) {
                     delayCounter += 1;
                 }
                 line.style.setProperty('--scroll-delta', `${delta}px`);
                 line.style.setProperty('--lyrics-line-delay', `${delay}ms`);
-                line.style.setProperty('--scroll-duration', `${duration + 100}ms`);
+                lineDelays.set(line, delay);
                 newAnimatingLines.push(line);
-                const lineDuration = duration + delay;
+                const lineDuration = duration + 100 + delay;
                 if (lineDuration > maxAnimationDuration) {
                     maxAnimationDuration = lineDuration;
                 }
             }
         }
+        /* Preserve the staggered starts, but make every line settle together.
+           This keeps the selected line from drifting after its neighbours. */
+        for (const line of newAnimatingLines) {
+            const delay = lineDelays.get(line) ?? 0;
+            line.style.setProperty('--scroll-duration', `${Math.max(100, maxAnimationDuration - delay)}ms`);
+        }
         // --- Step 3: Force reflow so the browser sees the class removal ---
         // Use offsetHeight which is cheaper than getBoundingClientRect
         // eslint-disable-next-line no-void
@@ -3338,30 +3549,255 @@ let AmLyrics$1 = class AmLyrics extends i {
     }
     /**
      * Update syllable highlight animation - apply CSS wipe animation
-     * (Exact copy from YouLyPlus _updateSyllableAnimation)
      */
+    static clamp(value, min, max) {
+        return Math.min(max, Math.max(min, value));
+    }
+    static getVisibleCharacterCount(element) {
+        const attrLength = parseFloat(element.getAttribute('data-word-length') || '');
+        if (Number.isFinite(attrLength) && attrLength > 0)
+            return attrLength;
+        return (element.textContent || '').replace(/\s/g, '').length;
+    }
+    static getLongWordWipeScale(charCount) {
+        if (charCount <= 6)
+            return 1;
+        return (1 +
+            AmLyrics.clamp((charCount - 6) / 10, 0, 1) * LONG_WORD_WIPE_EXTRA_RATIO);
+    }
+    static applyWipeShape(element, charCount) {
+        const extra = AmLyrics.clamp((charCount - 6) / 10, 0, 1) * LONG_WORD_WIPE_EXTRA_EM;
+        const width = BASE_WIPE_GRADIENT_EM + extra;
+        element.style.setProperty('--wipe-gradient-width', `${width.toFixed(3)}em`);
+        element.style.setProperty('--wipe-gradient-half', `${(width / 2).toFixed(3)}em`);
+    }
+    static ensureWordWipeGeometry(charSpans, charCount) {
+        if (charSpans.length === 0)
+            return;
+        const approxWidthCh = Math.max(1, charCount || charSpans.length);
+        charSpans.forEach((span, index) => {
+            if (!span.style.getPropertyValue('--word-wipe-width')) {
+                span.style.setProperty('--word-wipe-width', `${approxWidthCh}ch`);
+            }
+            if (!span.style.getPropertyValue('--char-wipe-position')) {
+                const startPct = Number.parseFloat(span.dataset.wipeStart || `${index / Math.max(1, charSpans.length)}`);
+                span.style.setProperty('--char-wipe-position', `${-(AmLyrics.clamp(startPct, 0, 1) * approxWidthCh)}ch`);
+            }
+        });
+    }
+    static clearPreHighlight(syllable) {
+        const target = syllable;
+        target.classList.remove('pre-highlight');
+        target.style.removeProperty('--pre-wipe-duration');
+        target.style.removeProperty('--pre-wipe-delay');
+        target.style.animation = '';
+        target
+            .querySelectorAll('.pre-wipe-lead')
+            .forEach(element => AmLyrics.clearPreWipeLead(element));
+    }
+    static clearPreWipeLead(element) {
+        element.classList.remove('pre-wipe-lead');
+        element.style.removeProperty('--pre-wipe-duration');
+        element.style.removeProperty('--pre-wipe-delay');
+    }
+    static hasTextBoundaryAfter(syllable) {
+        return /\s$/.test(syllable.textContent || '');
+    }
+    static getSyllableWordIndex(syllable) {
+        const wordElement = AmLyrics.getWordElementForSyllable(syllable);
+        const virtualWordId = wordElement?.dataset.virtualWordId;
+        if (virtualWordId) {
+            return `virtual:${virtualWordId}`;
+        }
+        const virtualWordStart = wordElement?.dataset.virtualWordStart;
+        const virtualWordEnd = wordElement?.dataset.virtualWordEnd;
+        if (virtualWordStart || virtualWordEnd) {
+            return `virtual:${virtualWordStart || ''}:${virtualWordEnd || ''}`;
+        }
+        return (syllable.getAttribute('data-word-index') ||
+            syllable.getAttribute('data-syllable-index') ||
+            '');
+    }
+    static getNextWordSyllable(syllables, index) {
+        const current = syllables[index];
+        const currentWordIndex = AmLyrics.getSyllableWordIndex(current);
+        const previousSyllable = current;
+        for (let i = index + 1; i < syllables.length; i += 1) {
+            const candidate = syllables[i];
+            if (candidate.classList.contains('transliteration')) {
+                // eslint-disable-next-line no-continue
+                continue;
+            }
+            const candidateWordIndex = AmLyrics.getSyllableWordIndex(candidate);
+            if (candidateWordIndex === currentWordIndex ||
+                !AmLyrics.hasTextBoundaryAfter(previousSyllable)) {
+                return null;
+            }
+            return candidate;
+        }
+        return null;
+    }
+    static getPreviousNonTransliterationSyllable(syllables, index) {
+        for (let i = index - 1; i >= 0; i -= 1) {
+            const candidate = syllables[i];
+            if (!candidate.classList.contains('transliteration')) {
+                return candidate;
+            }
+        }
+        return null;
+    }
+    static getRenderedWordSyllables(syllable) {
+        const wordElement = AmLyrics.getWordElementForSyllable(syllable);
+        const wordElements = AmLyrics.getCachedVirtualWordElements(wordElement);
+        const wordSyllables = wordElements.flatMap(element => Array.from(element.querySelectorAll('.lyrics-syllable')));
+        return wordSyllables.filter(wordSyllable => !wordSyllable.classList.contains('transliteration'));
+    }
+    static getWordElementForSyllable(syllable) {
+        return syllable.parentElement?.parentElement;
+    }
+    static getWordPreWipeKey(syllable) {
+        const wordElement = AmLyrics.getWordElementForSyllable(syllable);
+        return (wordElement?.dataset.virtualWordId ||
+            `${syllable.getAttribute('data-start-time') || ''}:${AmLyrics.getSyllableWordIndex(syllable)}`);
+    }
+    static isPreWipeArmed(syllable) {
+        const wordElement = AmLyrics.getWordElementForSyllable(syllable);
+        const target = wordElement;
+        return Boolean(target?._wordPreWipeKey === AmLyrics.getWordPreWipeKey(syllable));
+    }
+    static applyWordPreWipe(nextSyllable, wordSyllables, currentTimeMs, preWipeStartMs, preWipeDurationMs) {
+        if (AmLyrics.isPreWipeArmed(nextSyllable))
+            return;
+        const wordElement = AmLyrics.getWordElementForSyllable(nextSyllable);
+        const wordElements = AmLyrics.getCachedVirtualWordElements(wordElement);
+        const charSpans = AmLyrics.getCachedVirtualWordCharSpans(wordElement, []);
+        const elapsedPreWipe = currentTimeMs - preWipeStartMs;
+        const charCount = charSpans.length ||
+            wordSyllables.reduce((total, wordSyllable) => total + AmLyrics.getVisibleCharacterCount(wordSyllable), 0) ||
+            AmLyrics.getVisibleCharacterCount(nextSyllable);
+        AmLyrics.ensureWordWipeGeometry(charSpans, charCount);
+        const leadChar = charSpans[0];
+        const leadCharSyllable = leadChar?.closest('.lyrics-syllable');
+        const preWipeSyllable = leadCharSyllable || wordSyllables[0] || nextSyllable;
+        AmLyrics.applyWipeShape(preWipeSyllable, charCount);
+        preWipeSyllable.style.setProperty('--pre-wipe-duration', `${preWipeDurationMs}ms`);
+        preWipeSyllable.style.setProperty('--pre-wipe-delay', `${-elapsedPreWipe}ms`);
+        preWipeSyllable.classList.add('pre-highlight');
+        // Character-animated words still need a single word-leading gradient.
+        // Giving every glyph this state creates one gradient per character and
+        // makes the whole word enter the pre-wipe continuation simultaneously.
+        if (leadChar) {
+            AmLyrics.applyWipeShape(leadChar, charCount);
+            leadChar.style.setProperty('--pre-wipe-duration', `${preWipeDurationMs}ms`);
+            leadChar.style.setProperty('--pre-wipe-delay', `${-elapsedPreWipe}ms`);
+            leadChar.classList.add('pre-wipe-lead');
+        }
+        wordElements.forEach(element => {
+            const target = element;
+            target._wordPreWipeKey = AmLyrics.getWordPreWipeKey(nextSyllable);
+        });
+    }
+    static maybePreWipeNextWord(syllables, index, currentTimeMs, currentEndTimeMs) {
+        const syllable = syllables[index];
+        if (syllable.classList.contains('line-synced') ||
+            syllable.classList.contains('transliteration') ||
+            syllable.closest('.lyrics-gap')) {
+            return;
+        }
+        const currentWordReady = syllable.classList.contains('finished') ||
+            currentTimeMs >= currentEndTimeMs - WORD_PRE_WIPE_HANDOFF_LEAD_MS;
+        if (!currentWordReady) {
+            return;
+        }
+        const nextSyllable = AmLyrics.getNextWordSyllable(syllables, index);
+        if (!nextSyllable ||
+            nextSyllable.classList.contains('line-synced') ||
+            nextSyllable.classList.contains('transliteration') ||
+            nextSyllable.closest('.lyrics-gap') ||
+            nextSyllable.classList.contains('highlight') ||
+            nextSyllable.classList.contains('finished')) {
+            return;
+        }
+        const nextStartTimeMs = nextSyllable._cachedStartTime;
+        if (!Number.isFinite(nextStartTimeMs))
+            return;
+        const gapMs = nextStartTimeMs - currentEndTimeMs;
+        if (gapMs > NEXT_WORD_PRE_WIPE_MAX_GAP_MS || gapMs < -50) {
+            return;
+        }
+        const nextWordSyllables = AmLyrics.getRenderedWordSyllables(nextSyllable);
+        const preWipeSyllables = nextWordSyllables.length > 0 ? nextWordSyllables : [nextSyllable];
+        const wordElement = AmLyrics.getWordElementForSyllable(nextSyllable);
+        const wordCharSpans = AmLyrics.getCachedVirtualWordCharSpans(wordElement, []);
+        const charCount = wordCharSpans.length ||
+            preWipeSyllables.reduce((total, wordSyllable) => total + AmLyrics.getVisibleCharacterCount(wordSyllable), 0);
+        if (charCount <= 0)
+            return;
+        const preWipeDuration = AmLyrics.clamp(64 + charCount * 9, NEXT_WORD_PRE_WIPE_MIN_DURATION_MS, NEXT_WORD_PRE_WIPE_MAX_DURATION_MS);
+        const preWipeStart = Math.max(nextStartTimeMs - preWipeDuration, currentEndTimeMs - WORD_PRE_WIPE_HANDOFF_LEAD_MS);
+        if (currentTimeMs < preWipeStart || currentTimeMs >= nextStartTimeMs) {
+            return;
+        }
+        AmLyrics.applyWordPreWipe(nextSyllable, preWipeSyllables, currentTimeMs, preWipeStart, preWipeDuration);
+    }
+    static getCachedCharSpans(element) {
+        const cacheTarget = element;
+        if (!cacheTarget._cachedCharSpans) {
+            cacheTarget._cachedCharSpans = Array.from(element.querySelectorAll('span.char'));
+        }
+        return cacheTarget._cachedCharSpans;
+    }
+    static getCachedVirtualWordElements(wordElement) {
+        if (!wordElement)
+            return [];
+        const cacheTarget = wordElement;
+        if (cacheTarget._cachedVirtualWordElements) {
+            return cacheTarget._cachedVirtualWordElements;
+        }
+        const { virtualWordId } = wordElement.dataset;
+        let wordElements = [wordElement];
+        if (virtualWordId && wordElement.parentElement) {
+            wordElements = Array.from(wordElement.parentElement.querySelectorAll('.lyrics-word')).filter(el => el.dataset.virtualWordId === virtualWordId);
+        }
+        wordElements.forEach(element => {
+            const target = element;
+            target._cachedVirtualWordElements = wordElements;
+        });
+        return wordElements;
+    }
+    static getCachedVirtualWordCharSpans(wordElement, fallbackCharSpans) {
+        if (!wordElement)
+            return fallbackCharSpans;
+        const cacheTarget = wordElement;
+        if (cacheTarget._cachedVirtualWordCharSpans) {
+            return cacheTarget._cachedVirtualWordCharSpans;
+        }
+        const wordElements = AmLyrics.getCachedVirtualWordElements(wordElement);
+        const charSpans = wordElements.flatMap(word => Array.from(word.querySelectorAll('span.char')));
+        const result = charSpans.length > 0 ? charSpans : fallbackCharSpans;
+        wordElements.forEach(element => {
+            const target = element;
+            target._cachedVirtualWordCharSpans = result;
+        });
+        return result;
+    }
     static updateSyllableAnimation(syllable, elapsedTimeMs = 0) {
         if (syllable.classList.contains('highlight'))
             return;
         const { classList } = syllable;
+        const hadPreHighlight = classList.contains('pre-highlight');
         const isRTL = classList.contains('rtl-text');
-        const charSpans = Array.from(syllable.querySelectorAll('span.char'));
+        const charSpans = AmLyrics.getCachedCharSpans(syllable);
         const wordElement = syllable.parentElement?.parentElement; // syllable-wrap -> word
-        const virtualWordId = wordElement?.dataset
-            .virtualWordId;
-        let wordElements = [];
-        if (virtualWordId && wordElement?.parentElement) {
-            wordElements = Array.from(wordElement.parentElement.querySelectorAll('.lyrics-word')).filter(el => el.dataset.virtualWordId === virtualWordId);
-        }
-        else if (wordElement) {
-            wordElements = [wordElement];
-        }
-        const allWordCharSpans = wordElements.flatMap(word => Array.from(word.querySelectorAll('span.char')));
-        const isGrowable = wordElement?.classList.contains('growable');
-        const isCharRise = wordElement?.classList.contains('char-rise');
+        const typedWordElement = wordElement;
+        const allWordElements = AmLyrics.getCachedVirtualWordElements(typedWordElement);
+        const allWordCharSpans = AmLyrics.getCachedVirtualWordCharSpans(typedWordElement, charSpans);
+        const isGrowable = typedWordElement?.classList.contains('growable');
+        const isCharRise = typedWordElement?.classList.contains('char-rise');
+        const isCharDrag = typedWordElement?.classList.contains('char-drag');
         const isFirstSyllable = syllable.getAttribute('data-syllable-index') === '0';
         const syllableStartMs = parseFloat(syllable.getAttribute('data-start-time') || '0');
-        const virtualWordStartMs = parseFloat(wordElement?.dataset.virtualWordStart || '');
+        const virtualWordStartMs = parseFloat(typedWordElement?.dataset.virtualWordStart || '');
         const isFirstInVirtualWord = isFirstSyllable &&
             (!Number.isFinite(virtualWordStartMs) ||
                 Math.abs(syllableStartMs - virtualWordStartMs) < 0.5);
@@ -3372,7 +3808,10 @@ let AmLyrics$1 = class AmLyrics extends i {
         const wordDurationMs = parseFloat(syllable.getAttribute('data-word-duration') ||
             syllable.getAttribute('data-duration') ||
             '0') || syllableDurationMs;
-        // Use a Map to collect animations like YouLyPlus
+        const wordElapsedTimeMs = Number.isFinite(virtualWordStartMs)
+            ? elapsedTimeMs + (syllableStartMs - virtualWordStartMs)
+            : elapsedTimeMs;
+        const charWipeDurationMs = Math.max(wordDurationMs, syllableDurationMs);
         const charAnimationsMap = new Map();
         const styleUpdates = [];
         // Step 1: Grow Pass
@@ -3420,41 +3859,81 @@ let AmLyrics$1 = class AmLyrics extends i {
                 charAnimationsMap.set(span, `rise-char ${riseDurationMs}ms ease-in-out ${riseDelay}ms forwards`);
             });
         }
+        if (isCharDrag && isFirstInVirtualWord && allWordCharSpans.length > 0) {
+            const finalDuration = Math.max(wordDurationMs, syllableDurationMs);
+            const baseDelayPerChar = AmLyrics.clamp(finalDuration * 0.15, 64, 118);
+            const dragDurationMs = AmLyrics.clamp(finalDuration * 0.82, 560, 900);
+            allWordCharSpans.forEach(span => {
+                const charIndex = parseFloat(span.dataset.syllableCharIndex || '0');
+                const dragDelay = baseDelayPerChar * charIndex;
+                charAnimationsMap.set(span, `drag-char ${dragDurationMs}ms ease ${dragDelay}ms forwards`);
+            });
+        }
         // Step 2: Wipe Pass
         if (charSpans.length > 0) {
-            charSpans.forEach((span, charIndex) => {
+            const wipeCharCount = allWordCharSpans.length ||
+                charSpans.length ||
+                AmLyrics.getVisibleCharacterCount(syllable);
+            const wipeScale = AmLyrics.getLongWordWipeScale(wipeCharCount);
+            AmLyrics.applyWipeShape(syllable, wipeCharCount);
+            AmLyrics.ensureWordWipeGeometry(allWordCharSpans, wipeCharCount);
+            allWordCharSpans.forEach(span => AmLyrics.applyWipeShape(span, wipeCharCount));
+            const hasWordLevelWipe = !isFirstInVirtualWord &&
+                (Boolean(typedWordElement?._wordWipeStarted) ||
+                    allWordCharSpans.some(span => span.style.animation.includes('wipe')));
+            let charSpansToAnimate = charSpans;
+            if (isFirstInVirtualWord) {
+                charSpansToAnimate = allWordCharSpans;
+            }
+            else if (hasWordLevelWipe) {
+                charSpansToAnimate = [];
+            }
+            if (charSpansToAnimate.length > 0 && allWordElements.length > 0) {
+                allWordElements.forEach(element => {
+                    const target = element;
+                    target._wordWipeStarted = true;
+                    target._wordPreWipeKey = undefined;
+                });
+            }
+            charSpansToAnimate.forEach((span, charIndex) => {
                 const startPct = parseFloat(span.dataset.wipeStart || '0');
                 const durationPct = parseFloat(span.dataset.wipeDuration || '0');
-                const wipeDelay = syllableDurationMs * startPct - elapsedTimeMs;
-                const wipeDuration = syllableDurationMs * durationPct;
-                const useStartAnimation = isFirstInContainer && charIndex === 0;
-                let charWipeAnimation = 'wipe';
-                if (useStartAnimation) {
-                    charWipeAnimation = isRTL ? 'start-wipe-rtl' : 'start-wipe';
+                const globalCharIndex = parseFloat(span.dataset.syllableCharIndex || `${charIndex}`);
+                const hadCharPreWipe = span.classList.contains('pre-wipe-lead') ||
+                    (hadPreHighlight && globalCharIndex === 0);
+                const charStartMs = charWipeDurationMs * startPct;
+                const remainingWordWipeMs = Math.max(0, charWipeDurationMs - charStartMs);
+                const wipeDelay = charStartMs - wordElapsedTimeMs;
+                const wipeDuration = Math.min(charWipeDurationMs * durationPct * wipeScale, remainingWordWipeMs);
+                const useStartAnimation = isFirstInContainer && globalCharIndex === 0 && !hadCharPreWipe;
+                let charWipeAnimation = 'char-wipe';
+                if (hadCharPreWipe) {
+                    charWipeAnimation = 'char-wipe';
                 }
-                else {
-                    charWipeAnimation = isRTL ? 'wipe-rtl' : 'wipe';
+                else if (useStartAnimation) {
+                    charWipeAnimation = 'char-start-wipe';
                 }
                 const existingAnimation = charAnimationsMap.get(span) || span.style.animation || '';
                 const animationParts = [];
                 if (existingAnimation &&
                     (existingAnimation.includes('grow-dynamic') ||
-                        existingAnimation.includes('rise-char'))) {
+                        existingAnimation.includes('rise-char') ||
+                        existingAnimation.includes('drag-char'))) {
                     animationParts.push(existingAnimation.split(',')[0].trim());
                 }
-                if (charIndex > 0 && wipeDelay > 0 && wipeDuration > 0) {
-                    const arrivalTime = (span.dataset.preWipeArrival
-                        ? parseFloat(span.dataset.preWipeArrival)
-                        : syllableDurationMs * startPct) - elapsedTimeMs;
-                    const measuredPreWipeDuration = parseFloat(span.dataset.preWipeDuration || '100');
-                    const preWipeDuration = Math.min(measuredPreWipeDuration, wipeDuration * 0.9, syllableDurationMs * 0.08, arrivalTime);
-                    const animDelay = arrivalTime - preWipeDuration;
+                if (globalCharIndex > 0 &&
+                    !hadCharPreWipe &&
+                    wipeDelay > 0 &&
+                    wipeDuration > 0) {
+                    const measuredDuration = Number.parseFloat(span.dataset.preWipeDuration || '100');
+                    const preWipeDuration = Math.min(measuredDuration, wipeDuration * 0.9, charWipeDurationMs * 0.08, wipeDelay);
                     if (preWipeDuration >= 16) {
-                        animationParts.push(`pre-wipe-char ${preWipeDuration}ms linear ${animDelay}ms none`);
+                        animationParts.push(`char-pre-wipe ${preWipeDuration}ms linear ${wipeDelay - preWipeDuration}ms none`);
                     }
                 }
                 if (wipeDuration > 0) {
-                    animationParts.push(`${charWipeAnimation} ${wipeDuration}ms linear ${wipeDelay}ms forwards`);
+                    const wipeFillMode = hadCharPreWipe ? 'both' : 'forwards';
+                    animationParts.push(`${charWipeAnimation} ${wipeDuration}ms linear ${wipeDelay}ms ${wipeFillMode}`);
                 }
                 if (animationParts.length > 0) {
                     charAnimationsMap.set(span, animationParts.join(', '));
@@ -3464,9 +3943,15 @@ let AmLyrics$1 = class AmLyrics extends i {
         else {
             // Syllable-level wipe for regular (non-growable) words without chars
             const wipeRatio = parseFloat(syllable.getAttribute('data-wipe-ratio') || '1');
-            const visualDuration = syllableDurationMs * wipeRatio;
+            const wipeCharCount = AmLyrics.getVisibleCharacterCount(syllable);
+            const wipeScale = AmLyrics.getLongWordWipeScale(wipeCharCount);
+            const visualDuration = syllableDurationMs * wipeRatio * wipeScale;
+            AmLyrics.applyWipeShape(syllable, wipeCharCount);
             let wipeAnimation = 'wipe';
-            if (isFirstInContainer) {
+            if (hadPreHighlight) {
+                wipeAnimation = isRTL ? 'wipe-from-pre-rtl' : 'wipe-from-pre';
+            }
+            else if (isFirstInContainer) {
                 wipeAnimation = isRTL ? 'start-wipe-rtl' : 'start-wipe';
             }
             else {
@@ -3479,16 +3964,25 @@ let AmLyrics$1 = class AmLyrics extends i {
             syllable.style.animation = `${currentWipeAnimation} ${visualDuration}ms ${isGap ? 'ease-out' : 'linear'} ${-elapsedTimeMs}ms forwards`;
         }
         // --- WRITE PHASE ---
+        if (allWordElements.length > 0) {
+            allWordElements.forEach(element => {
+                const target = element;
+                target._wordPreWipeKey = undefined;
+            });
+        }
         classList.remove('pre-highlight');
         classList.add('highlight');
+        allWordCharSpans.forEach(span => AmLyrics.clearPreWipeLead(span));
+        // Apply keyframe variables before assigning animation strings so the
+        // first painted frame never uses fallback transform values.
+        for (const update of styleUpdates) {
+            update.element.style.setProperty(update.property, update.value);
+        }
         for (const [span, animationString] of charAnimationsMap.entries()) {
             span.style.willChange = 'transform';
+            span.style.removeProperty('background-color');
             span.style.animation = animationString;
         }
-        // Apply style updates
-        for (const update of styleUpdates) {
-            update.element.style.setProperty(update.property, update.value);
-        }
     }
     /**
      * Reset syllable animation state
@@ -3512,10 +4006,19 @@ let AmLyrics$1 = class AmLyrics extends i {
             el.style.animation = '';
             el.style.transition = 'none';
             el.style.backgroundColor = 'var(--lyplus-text-secondary)';
+            AmLyrics.clearPreWipeLead(el);
         }
         // Immediately remove all state classes
         syllable.classList.remove('highlight', 'finished', 'pre-highlight', 'cleanup');
     }
+    static resetWordAnimationState(line) {
+        const wordElements = line.querySelectorAll('.lyrics-word');
+        wordElements.forEach(wordElement => {
+            const target = wordElement;
+            target._wordPreWipeKey = undefined;
+            target._wordWipeStarted = false;
+        });
+    }
     /**
      * Reset all syllables in a line — batches deferred cleanup into a single rAF
      */
@@ -3523,6 +4026,7 @@ let AmLyrics$1 = class AmLyrics extends i {
         if (!line)
             return;
         line.classList.remove('persist-highlight');
+        AmLyrics.resetWordAnimationState(line);
         // eslint-disable-next-line no-param-reassign
         line._cachedSyllableElements = null;
         const syllables = line.getElementsByClassName('lyrics-syllable');
@@ -3554,6 +4058,7 @@ let AmLyrics$1 = class AmLyrics extends i {
         if (!line)
             return;
         line.classList.remove('persist-highlight');
+        AmLyrics.resetWordAnimationState(line);
         const syllables = line.getElementsByClassName('lyrics-syllable');
         for (let i = 0; i < syllables.length; i += 1) {
             const s = syllables[i];
@@ -3571,6 +4076,7 @@ let AmLyrics$1 = class AmLyrics extends i {
                 el.style.removeProperty('background-color');
                 el.style.removeProperty('transition');
                 el.style.removeProperty('filter');
+                AmLyrics.clearPreWipeLead(el);
             }
         }
     }
@@ -3607,19 +4113,26 @@ let AmLyrics$1 = class AmLyrics extends i {
                 syllable.style.animation = '';
                 syllable.style.removeProperty('--pre-wipe-duration');
                 syllable.style.removeProperty('--pre-wipe-delay');
+                syllable.style.removeProperty('background-color');
+                AmLyrics.applyWipeShape(syllable, AmLyrics.getVisibleCharacterCount(syllable));
                 const chars = syllable.querySelectorAll('span.char');
                 for (let ci = 0; ci < chars.length; ci += 1) {
                     const charEl = chars[ci];
                     const currentAnim = charEl.style.animation || '';
                     if (currentAnim.includes('grow-dynamic') ||
-                        currentAnim.includes('rise-char')) {
+                        currentAnim.includes('rise-char') ||
+                        currentAnim.includes('drag-char')) {
                         const parts = currentAnim.split(',').map(p => p.trim());
-                        const transformAnim = parts.find(p => p.includes('grow-dynamic') || p.includes('rise-char'));
+                        const transformAnim = parts.find(p => p.includes('grow-dynamic') ||
+                            p.includes('rise-char') ||
+                            p.includes('drag-char'));
                         charEl.style.animation = transformAnim || '';
                     }
                     else {
                         charEl.style.animation = '';
                     }
+                    charEl.style.backgroundColor = 'var(--lyplus-text-primary)';
+                    AmLyrics.clearPreWipeLead(charEl);
                 }
             }
         }
@@ -3660,14 +4173,16 @@ let AmLyrics$1 = class AmLyrics extends i {
                 // Early exit check
                 if (!(currentTimeMs < startTime - 1000 && !hasActiveState)) {
                     let preHighlightReset = false;
-                    // Pre-highlight reset logic
-                    if (hasPreHighlight && i > 0) {
-                        const prevSyllable = syllables[i - 1];
-                        if (!prevSyllable.classList.contains('highlight')) {
-                            classList.remove('pre-highlight');
-                            syllable.style.removeProperty('--pre-wipe-duration');
-                            syllable.style.removeProperty('--pre-wipe-delay');
-                            syllable.style.animation = '';
+                    // Before the syllable starts, pre-highlight only belongs beside a
+                    // previous active word. Once the syllable starts, updateSyllableAnimation
+                    // consumes the class so the actual wipe can continue from the pre-wipe
+                    // pose instead of restarting from the beginning.
+                    if (hasPreHighlight && currentTimeMs < startTime) {
+                        const prevSyllable = AmLyrics.getPreviousNonTransliterationSyllable(syllables, i);
+                        const previousCarriesHighlight = prevSyllable?.classList.contains('highlight') ||
+                            prevSyllable?.classList.contains('finished');
+                        if (!previousCarriesHighlight) {
+                            AmLyrics.clearPreHighlight(syllable);
                             preHighlightReset = true;
                         }
                     }
@@ -3695,6 +4210,7 @@ let AmLyrics$1 = class AmLyrics extends i {
                             // Not yet started
                             AmLyrics.resetSyllable(syllable);
                         }
+                        AmLyrics.maybePreWipeNextWord(syllables, i, currentTimeMs, endTime);
                     }
                 }
             }
@@ -4004,6 +4520,9 @@ let AmLyrics$1 = class AmLyrics extends i {
                         data-end-time="${endTimeMs}"
                         data-duration="${durationMs}"
                         data-syllable-index="${syllableIndex}"
+                        data-word-index="${syllableIndex}"
+                        data-word-length="${syllable.text.replace(/\s/g, '')
+                            .length}"
                         data-wipe-ratio="1"
                         >${syllable.text}</span
                       >${bgRomanizedText}</span
@@ -4025,13 +4544,13 @@ let AmLyrics$1 = class AmLyrics extends i {
                 const groupGrowable = lineData?.groupGrowable ?? [];
                 const groupGlowing = lineData?.groupGlowing ?? [];
                 const groupCharRise = lineData?.groupCharRise ?? [];
+                const groupCharDrag = lineData?.groupCharDrag ?? [];
                 const vwFullText = lineData?.vwFullText ?? [];
                 const vwFullDuration = lineData?.vwFullDuration ?? [];
                 const vwCharOffset = lineData?.vwCharOffset ?? [];
                 const vwStartMs = lineData?.vwStartMs ?? [];
                 const vwEndMs = lineData?.vwEndMs ?? [];
                 const lineIsRTL = lineData?.lineIsRTL ?? false;
-                // Create main vocals using YouLyPlus syllable structure
                 const mainVocalElement = b `<p
           class="main-vocal-container ${lineIsRTL ? 'rtl-text' : ''}"
         >
@@ -4039,25 +4558,23 @@ let AmLyrics$1 = class AmLyrics extends i {
                     const isGrowable = groupGrowable[groupIdx];
                     const isGlowing = groupGlowing[groupIdx];
                     const isCharRise = groupCharRise[groupIdx];
-                    const isAnimatedByChar = isGrowable || isCharRise;
+                    const isCharDrag = groupCharDrag[groupIdx];
+                    const isAnimatedByChar = isGrowable || isCharRise || isCharDrag;
                     const groupLineSynced = group.some(s => s.lineSynced);
                     const wordText = isAnimatedByChar ? vwFullText[groupIdx] : '';
                     const wordDuration = isAnimatedByChar
                         ? vwFullDuration[groupIdx]
                         : 0;
-                    const wordNumChars = wordText.length;
+                    const wordNumChars = wordText.replace(/\s/g, '').length;
                     const groupCharOffset = isAnimatedByChar
                         ? vwCharOffset[groupIdx]
                         : 0;
-                    const virtualWordId = isAnimatedByChar
-                        ? `${lineIndex}:${vwStartMs[groupIdx]}:${vwEndMs[groupIdx]}`
-                        : '';
-                    const virtualWordStart = isAnimatedByChar
-                        ? vwStartMs[groupIdx]
-                        : '';
-                    const virtualWordEnd = isAnimatedByChar ? vwEndMs[groupIdx] : '';
+                    const virtualWordId = `${lineIndex}:${vwStartMs[groupIdx]}:${vwEndMs[groupIdx]}`;
+                    const virtualWordStart = vwStartMs[groupIdx];
+                    const virtualWordEnd = vwEndMs[groupIdx];
                     let sylCharAccumulator = 0;
                     const groupText = group.map(s => s.text).join('');
+                    const visibleWordLength = groupText.replace(/\s/g, '').length;
                     const shouldAllowBreak = groupText.trim().length >= 16 ||
                         /[\u4e00-\u9fff\u3040-\u309f\u30a0-\u30ff\uac00-\ud7af]/.test(groupText);
                     // Calculate dynamic rise duration based on the audio duration of the word
@@ -4069,9 +4586,9 @@ let AmLyrics$1 = class AmLyrics extends i {
                     return b `<span
               class="lyrics-word${isGrowable ? ' growable' : ''}${isCharRise
                         ? ' char-rise'
-                        : ''}${isGlowing ? ' glowing' : ''}${shouldAllowBreak
-                        ? ' allow-break'
-                        : ''}"
+                        : ''}${isCharDrag ? ' char-drag' : ''}${isGlowing
+                        ? ' glowing'
+                        : ''}${shouldAllowBreak ? ' allow-break' : ''}"
               data-virtual-word-id="${virtualWordId}"
               data-virtual-word-start="${virtualWordStart}"
               data-virtual-word-end="${virtualWordEnd}"
@@ -4098,13 +4615,26 @@ let AmLyrics$1 = class AmLyrics extends i {
                             : '';
                         let syllableContent = text;
                         if (isAnimatedByChar) {
-                            let charIndexInsideSyllable = 0;
                             const numCharsInSyllable = text.replace(/\s/g, '').length || 1;
+                            const hasVirtualTiming = wordDuration > 0 && Number.isFinite(virtualWordStart);
+                            const syllableStartRatio = hasVirtualTiming
+                                ? AmLyrics.clamp((startTimeMs - virtualWordStart) / wordDuration, 0, 1)
+                                : 0;
+                            const syllableDurationRatio = hasVirtualTiming
+                                ? AmLyrics.clamp(durationMs / wordDuration, 0, 1)
+                                : 1;
+                            let charIndexInsideSyllable = 0;
                             syllableContent = b `${text.split('').map(char => {
                                 if (char === ' ')
                                     return ' ';
                                 const charIndexInsideWord = groupCharOffset + sylCharAccumulator;
-                                const charStartPercentVal = charIndexInsideSyllable / numCharsInSyllable;
+                                const localCharIndex = charIndexInsideSyllable;
+                                const visibleWordChars = Math.max(1, wordNumChars);
+                                const charStartPercentVal = AmLyrics.clamp(syllableStartRatio +
+                                    (localCharIndex / numCharsInSyllable) *
+                                        syllableDurationRatio, 0, 1);
+                                const charDurationPercentVal = syllableDurationRatio / numCharsInSyllable ||
+                                    1 / visibleWordChars;
                                 sylCharAccumulator += 1;
                                 charIndexInsideSyllable += 1;
                                 const minDuration = 400;
@@ -4151,21 +4681,37 @@ let AmLyrics$1 = class AmLyrics extends i {
                                 const normalizedGrowth = (charMaxScale - 1.0) / 0.1;
                                 const effectiveDuration = (wordDuration + durationMs * 2) / 3;
                                 const peakMultiplier = Math.min(1, Math.max(0.3, effectiveDuration / 2000));
-                                const charTranslateYPeak = -normalizedGrowth * (2 * peakMultiplier); // Further dampened lift peak
+                                const baseTranslateYPeak = -normalizedGrowth * (2 * peakMultiplier); // Further dampened lift peak
                                 const position = (charIndexInsideWord + 0.5) / wordNumChars;
                                 const horizontalOffset = (position - 0.5) * 2 * ((charMaxScale - 1.0) * 25);
+                                const isDragMotion = isCharDrag;
+                                let charTranslateYPeak = baseTranslateYPeak;
+                                if (isCharRise) {
+                                    charTranslateYPeak = 0;
+                                }
+                                else if (isDragMotion) {
+                                    charTranslateYPeak = -0.78;
+                                }
+                                let motionHorizontalOffset = horizontalOffset;
+                                if (isCharRise) {
+                                    motionHorizontalOffset = 0;
+                                }
+                                else if (isDragMotion) {
+                                    motionHorizontalOffset = 0;
+                                }
                                 return b `<span
                       class="char"
                       data-char-index="${charIndexInsideWord}"
                       data-syllable-char-index="${charIndexInsideWord}"
                       data-wipe-start="${charStartPercentVal.toFixed(4)}"
-                      data-wipe-duration="${(1 / numCharsInSyllable).toFixed(4)}"
+                      data-wipe-duration="${charDurationPercentVal.toFixed(4)}"
                       data-horizontal-offset="${horizontalOffset.toFixed(2)}"
                       data-max-scale="${charMaxScale.toFixed(3)}"
                       data-matrix-scale="${(charMaxScale * 0.98).toFixed(3)}"
-                      data-char-offset-x="${(horizontalOffset * 0.98).toFixed(2)}"
+                      data-char-offset-x="${(motionHorizontalOffset * 0.98).toFixed(2)}"
                       data-shadow-intensity="${charShadowIntensity.toFixed(3)}"
                       data-translate-y-peak="${charTranslateYPeak.toFixed(3)}"
+                      style="--word-wipe-width: ${visibleWordChars}ch; --char-wipe-position: -${charIndexInsideWord}ch"
                       >${char}</span
                     >`;
                             })}`;
@@ -4183,6 +4729,8 @@ let AmLyrics$1 = class AmLyrics extends i {
                     data-duration="${durationMs}"
                     data-word-duration="${wordDuration}"
                     data-syllable-index="${sylIdx}"
+                    data-word-index="${groupIdx}"
+                    data-word-length="${visibleWordLength}"
                     data-wipe-ratio="1"
                     >${syllableContent}</span
                   >${romanizedText}</span
@@ -4415,13 +4963,14 @@ let AmLyrics$1 = class AmLyrics extends i {
                           <button
                             class="download-button source-switch-btn"
                             title="Switch Lyrics Source"
-                            style="font-family: inherit; font-size: 11px; padding: 2px 6px; border-radius: 4px; border: 1px solid rgba(255, 255, 255, 0.2); background: transparent; cursor: pointer; color: #aaa; display: inline-flex; align-items: center;"
                             @click=${this.switchSource}
                             ?disabled=${this.isFetchingAlternatives}
                           >
                             <svg
-                              class="source-switch-svg lucide lucide-arrow-down-up-icon lucide-arrow-down-up"
-                              style="margin-right: 4px;"
+                              class="source-switch-svg lucide lucide-arrow-down-up-icon lucide-arrow-down-up ${this
+                    .isFetchingAlternatives
+                    ? 'is-loading'
+                    : ''}"
                               xmlns="http://www.w3.org/2000/svg"
                               width="12"
                               height="12"
@@ -4479,9 +5028,6 @@ let AmLyrics$1 = class AmLyrics extends i {
     }
 };
 AmLyrics$1.styles = i$3 `
-    /* ==========================================================================
-       YOULYPLUS-INSPIRED STYLING - Design Tokens & Variables
-       ========================================================================== */
     :host {
       --lyplus-lyrics-palette: var(
         --am-lyrics-highlight-color,
@@ -4510,6 +5056,8 @@ AmLyrics$1.styles = i$3 `
       --lyplus-blur-amount: 0.07em;
       --lyplus-blur-amount-near: 0.035em;
       --lyplus-fade-gap-timing-function: ease-out;
+      --wipe-gradient-width: 0.75em;
+      --wipe-gradient-half: 0.375em;
 
       --lyrics-scroll-padding-top: 25%;
 
@@ -4537,6 +5085,9 @@ AmLyrics$1.styles = i$3 `
       max-height: 100vh;
       overflow-y: auto;
       -webkit-overflow-scrolling: touch;
+      -webkit-touch-callout: none;
+      -webkit-user-select: none;
+      user-select: none;
       box-sizing: border-box;
       scrollbar-width: none;
       overflow-anchor: none;
@@ -4666,7 +5217,7 @@ AmLyrics$1.styles = i$3 `
     .lyrics-line.bg-expanded .background-vocal-container {
       max-height: 4em;
       opacity: 1;
-      will-change: max-height, opacity;
+      will-change: opacity;
     }
 
     .lyrics-line.bg-expanded .background-vocal-wrap {
@@ -4683,6 +5234,18 @@ AmLyrics$1.styles = i$3 `
       opacity: 1;
     }
 
+    /* Predictive scrolling begins before the next timestamp. Start dimming
+       the outgoing line at the same moment so it settles with the scroll. */
+    .lyrics-line.scroll-exiting {
+      opacity: 0.8;
+      color: var(--lyplus-text-secondary);
+      transition:
+        opacity var(--scroll-duration, 400ms) cubic-bezier(0.41, 0, 0.12, 0.99),
+        transform var(--scroll-duration, 400ms)
+          cubic-bezier(0.41, 0, 0.12, 0.99) var(--lyrics-line-delay, 0ms),
+        filter var(--scroll-duration, 400ms) ease;
+    }
+
     .lyrics-line.persist-highlight {
       filter: none !important;
       opacity: 1;
@@ -4818,11 +5381,22 @@ AmLyrics$1.styles = i$3 `
       white-space: nowrap;
     }
 
+    .lyrics-word.char-drag {
+      display: inline-block;
+      vertical-align: baseline;
+      white-space: nowrap;
+    }
+
     .lyrics-word.char-rise.allow-break {
       display: inline;
       white-space: normal;
     }
 
+    .lyrics-word.char-drag.allow-break {
+      display: inline;
+      white-space: normal;
+    }
+
     .lyrics-syllable-wrap {
       display: inline;
     }
@@ -4877,44 +5451,30 @@ AmLyrics$1.styles = i$3 `
     .lyrics-line.active:not(.lyrics-gap)
       .lyrics-syllable.pre-highlight.no-chars {
       background-repeat: no-repeat;
-      background-image:
-        linear-gradient(
-          90deg,
-          #ffffff00 0%,
-          var(--lyplus-text-primary, #fff) 50%,
-          #0000 100%
-        ),
-        linear-gradient(
-          90deg,
-          var(--lyplus-text-primary, #fff) 100%,
-          #0000 100%
-        );
-      background-size:
-        0.5em 100%,
-        0% 100%;
-      background-position:
-        -0.5em 0%,
-        -0.25em 0%;
+      background-image: linear-gradient(
+        90deg,
+        var(--lyplus-text-primary, #fff) 0%,
+        var(--lyplus-text-primary, #fff)
+          calc(100% - var(--wipe-gradient-width, 0.75em)),
+        #0000 100%
+      );
+      background-size: 0% 100%;
+      background-position: left;
     }
 
     .lyrics-line.active:not(.lyrics-gap) .lyrics-syllable.highlight.rtl-text,
     .lyrics-line.active:not(.lyrics-gap)
       .lyrics-syllable.pre-highlight.rtl-text {
       direction: rtl;
-      background-image:
-        linear-gradient(
-          -90deg,
-          var(--lyplus-text-primary) 0%,
-          transparent 100%
-        ),
-        linear-gradient(
-          -90deg,
-          var(--lyplus-text-primary) 100%,
-          transparent 100%
-        );
-      background-position:
-        calc(100% + 0.5em) 0%,
-        right 0%;
+      background-image: linear-gradient(
+        -90deg,
+        var(--lyplus-text-primary) 0%,
+        var(--lyplus-text-primary)
+          calc(100% - var(--wipe-gradient-width, 0.75em)),
+        transparent 100%
+      );
+      background-size: 0% 100%;
+      background-position: right 0%;
     }
 
     /* Background vocals: muted gray wipe instead of white.
@@ -4931,18 +5491,13 @@ AmLyrics$1.styles = i$3 `
     .lyrics-line.pre-active
       .background-vocal-container
       .lyrics-syllable.pre-highlight.no-chars {
-      background-image:
-        linear-gradient(
-          90deg,
-          #ffffff00 0%,
-          color-mix(in srgb, var(--lyplus-text-primary, #fff) 50%, #888888) 50%,
-          #0000 100%
-        ),
-        linear-gradient(
-          90deg,
-          color-mix(in srgb, var(--lyplus-text-primary, #fff) 50%, #888888) 100%,
-          #0000 100%
-        );
+      background-image: linear-gradient(
+        90deg,
+        color-mix(in srgb, var(--lyplus-text-primary, #fff) 50%, #888888) 0%,
+        color-mix(in srgb, var(--lyplus-text-primary, #fff) 50%, #888888)
+          calc(100% - var(--wipe-gradient-width, 0.75em)),
+        #0000 100%
+      );
     }
 
     .lyrics-line.active
@@ -4957,17 +5512,13 @@ AmLyrics$1.styles = i$3 `
     .lyrics-line.pre-active
       .background-vocal-container
       .lyrics-syllable.pre-highlight.rtl-text {
-      background-image:
-        linear-gradient(
-          -90deg,
-          color-mix(in srgb, var(--lyplus-text-primary) 50%, #888888) 0%,
-          transparent 100%
-        ),
-        linear-gradient(
-          -90deg,
-          color-mix(in srgb, var(--lyplus-text-primary) 50%, #888888) 100%,
-          transparent 100%
-        );
+      background-image: linear-gradient(
+        -90deg,
+        color-mix(in srgb, var(--lyplus-text-primary) 50%, #888888) 0%,
+        color-mix(in srgb, var(--lyplus-text-primary) 50%, #888888)
+          calc(100% - var(--wipe-gradient-width, 0.75em)),
+        transparent 100%
+      );
     }
 
     /* Non-growable words float up with a gentle curve */
@@ -4991,6 +5542,10 @@ AmLyrics$1.styles = i$3 `
       transform: translate3d(0, var(--char-rise-y, -1.12px), 0);
     }
 
+    .lyrics-word.char-drag .lyrics-syllable.cleanup .char {
+      transform: translate3d(0, var(--char-rise-y, -1.12px), 0);
+    }
+
     .lyrics-line.persist-highlight
       .lyrics-word.growable
       .lyrics-syllable.finished
@@ -4998,6 +5553,10 @@ AmLyrics$1.styles = i$3 `
     .lyrics-line.persist-highlight
       .lyrics-word.char-rise
       .lyrics-syllable.finished
+      .char,
+    .lyrics-line.persist-highlight
+      .lyrics-word.char-drag
+      .lyrics-syllable.finished
       .char {
       transform: translate3d(0, var(--char-rise-y, -1.12px), 0);
     }
@@ -5108,6 +5667,10 @@ AmLyrics$1.styles = i$3 `
         transform 0.7s ease;
     }
 
+    .lyrics-word.char-drag span.char {
+      transition: color 0.18s;
+    }
+
     /* Active char spans: structural only, wipe animation sets gradient */
     .lyrics-line.active .lyrics-syllable span.char {
       background-clip: text;
@@ -5126,52 +5689,34 @@ AmLyrics$1.styles = i$3 `
           #0000 100%
         );
       background-size:
-        0.5em 100%,
+        var(--wipe-gradient-width, 0.75em) 100%,
         0% 100%;
       background-position:
-        -0.5em 0%,
-        -0.25em 0%;
+        calc(-1 * var(--wipe-gradient-width, 0.75em)) 0%,
+        left;
       transition:
         transform 0.7s ease,
         color 0.18s;
     }
 
     .lyrics-line.active .lyrics-syllable span.char.highlight {
-      background-image:
-        linear-gradient(
-          -90deg,
-          var(--lyplus-text-primary, #fff) 0%,
-          #0000 100%
-        ),
-        linear-gradient(
-          -90deg,
-          var(--lyplus-text-primary, #fff) 100%,
-          #0000 100%
-        );
-      background-position:
-        calc(100% + 0.5em) 0%,
-        calc(100% + 0.25em) 0%;
+      background-image: linear-gradient(
+        -90deg,
+        var(--lyplus-text-primary, #fff) 0%,
+        var(--lyplus-text-primary, #fff)
+          calc(100% - var(--wipe-gradient-width, 0.75em)),
+        #0000 100%
+      );
+      background-size: 0% 100%;
+      background-position: right 0%;
     }
 
-    .lyrics-line.active .lyrics-syllable.pre-highlight span.char {
-      background-image:
-        linear-gradient(
-          90deg,
-          #ffffff00 0%,
-          var(--lyplus-text-primary, #fff) 50%,
-          #0000 100%
-        ),
-        linear-gradient(
-          90deg,
-          var(--lyplus-text-primary, #fff) 100%,
-          #0000 100%
-        );
-      background-size:
-        0.75em 100%,
-        0% 100%;
-      background-position:
-        -0.85em 0%,
-        -0.25em 0%;
+    .lyrics-line.active .lyrics-syllable span.char.pre-wipe-lead {
+      animation-name: char-pre-wipe;
+      animation-duration: var(--pre-wipe-duration);
+      animation-delay: var(--pre-wipe-delay);
+      animation-timing-function: linear;
+      animation-fill-mode: forwards;
     }
 
     /* ==========================================================================
@@ -5248,13 +5793,7 @@ AmLyrics$1.styles = i$3 `
       color: var(--lyplus-text-primary) !important;
     }
 
-    .lyrics-line.pre-active .lyrics-syllable.line-synced {
-      animation: fade-in-line 0.14s ease-out forwards !important;
-      color: var(--lyplus-text-primary) !important;
-    }
-
-    .lyrics-line.active .lyrics-syllable.line-synced span.char,
-    .lyrics-line.pre-active .lyrics-syllable.line-synced span.char {
+    .lyrics-line.active .lyrics-syllable.line-synced span.char {
       background-image: none !important;
       background-color: var(--lyplus-text-primary) !important;
       transition: background-color 120ms ease-out !important;
@@ -5427,6 +5966,49 @@ AmLyrics$1.styles = i$3 `
       gap: 4px;
     }
 
+    .source-switch-btn {
+      position: relative;
+      display: inline-flex;
+      align-items: center;
+      padding: 2px 8px;
+      border: 1px solid rgba(255, 255, 255, 0.2);
+      min-height: 28px;
+      background: transparent;
+      border-radius: 6px;
+      color: #aaa;
+      cursor: pointer;
+      font-family: inherit;
+      font-size: 11px;
+      transition:
+        color 0.2s ease,
+        border-color 0.2s ease,
+        background-color 0.2s ease,
+        transform 0.12s ease;
+    }
+
+    .source-switch-btn::before {
+      content: '';
+      position: absolute;
+      inset: -6px;
+    }
+
+    .source-switch-btn:active:not(:disabled) {
+      transform: scale(0.96);
+    }
+
+    .source-switch-btn:disabled {
+      cursor: default;
+      opacity: 0.7;
+    }
+
+    .source-switch-svg {
+      margin-right: 4px;
+    }
+
+    .source-switch-svg.is-loading {
+      animation: source-switch-spin 1s linear infinite;
+    }
+
     .control-button {
       background: transparent;
       border: 1px solid rgba(255, 255, 255, 0.3);
@@ -5435,7 +6017,10 @@ AmLyrics$1.styles = i$3 `
       font-size: 0.8em;
       color: rgba(255, 255, 255, 0.6);
       cursor: pointer;
-      transition: all 0.2s;
+      transition:
+        color 0.2s,
+        border-color 0.2s,
+        background-color 0.2s;
       font-weight: normal;
     }
 
@@ -5573,136 +6158,157 @@ AmLyrics$1.styles = i$3 `
        KEYFRAME ANIMATIONS
        ========================================================================== */
 
+    @keyframes source-switch-spin {
+      to {
+        transform: rotate(360deg);
+      }
+    }
+
     /* Wipe animation for syllables */
     @keyframes wipe {
       from {
-        background-size:
-          0.75em 100%,
-          0% 100%;
-        background-position:
-          -0.375em 0%,
-          left;
+        background-size: 0% 100%;
+        background-position: left;
       }
       to {
-        background-size:
-          0.75em 100%,
-          100% 100%;
-        background-position:
-          calc(100% + 0.375em) 0%,
-          left;
+        background-size: calc(100% + var(--wipe-gradient-width, 0.75em)) 100%;
+        background-position: left;
+      }
+    }
+
+    @keyframes wipe-from-pre {
+      from {
+        background-size: var(--wipe-gradient-width, 0.75em) 100%;
+        background-position: left;
+      }
+      to {
+        background-size: calc(100% + var(--wipe-gradient-width, 0.75em)) 100%;
+        background-position: left;
       }
     }
 
     @keyframes start-wipe {
       0% {
-        background-size:
-          0.75em 100%,
-          0% 100%;
-        background-position:
-          -0.75em 0%,
-          -0.375em 0%;
+        background-size: 0% 100%;
+        background-position: left;
       }
       100% {
-        background-size:
-          0.75em 100%,
-          100% 100%;
-        background-position:
-          calc(100% + 0.375em) 0%,
-          left;
+        background-size: calc(100% + var(--wipe-gradient-width, 0.75em)) 100%;
+        background-position: left;
       }
     }
 
     @keyframes wipe-rtl {
       from {
-        background-size:
-          0.75em 100%,
-          0% 100%;
-        background-position:
-          calc(100% + 0.375em) 0%,
-          calc(100% + 0.36em) 0%;
+        background-size: 0% 100%;
+        background-position: right 0%;
       }
       to {
-        background-size:
-          0.75em 100%,
-          100% 100%;
-        background-position:
-          -0.75em 0%,
-          right 0%;
+        background-size: calc(100% + var(--wipe-gradient-width, 0.75em)) 100%;
+        background-position: right 0%;
+      }
+    }
+
+    @keyframes wipe-from-pre-rtl {
+      from {
+        background-size: var(--wipe-gradient-width, 0.75em) 100%;
+        background-position: right 0%;
+      }
+      to {
+        background-size: calc(100% + var(--wipe-gradient-width, 0.75em)) 100%;
+        background-position: right 0%;
       }
     }
 
     @keyframes start-wipe-rtl {
       0% {
-        background-size:
-          0.75em 100%,
-          0% 100%;
-        background-position:
-          calc(100% + 0.75em) 0%,
-          calc(100% + 0.5em) 0%;
+        background-size: 0% 100%;
+        background-position: right 0%;
       }
       100% {
-        background-size:
-          0.75em 100%,
-          100% 100%;
-        background-position:
-          -0.75em 0%,
-          right 0%;
+        background-size: calc(100% + var(--wipe-gradient-width, 0.75em)) 100%;
+        background-position: right 0%;
       }
     }
 
     @keyframes pre-wipe-universal {
+      from {
+        background-size: 0% 100%;
+        background-position: left;
+      }
+      to {
+        background-size: var(--wipe-gradient-width, 0.75em) 100%;
+        background-position: left;
+      }
+    }
+
+    @keyframes pre-wipe-universal-rtl {
+      from {
+        background-size: 0% 100%;
+        background-position: right 0%;
+      }
+      to {
+        background-size: var(--wipe-gradient-width, 0.75em) 100%;
+        background-position: right 0%;
+      }
+    }
+
+    /* Character-rendered words use a separate moving gradient in front of
+       their solid fill. This makes the individual glyph wipes read as one
+       continuous word-level wipe. */
+    @keyframes char-pre-wipe {
       from {
         background-size:
-          0.75em 100%,
+          var(--wipe-gradient-width, 0.75em) 100%,
           0% 100%;
         background-position:
-          -0.75em 0%,
+          calc(-1 * var(--wipe-gradient-width, 0.75em)) 0%,
           left;
       }
       to {
         background-size:
-          0.75em 100%,
+          var(--wipe-gradient-width, 0.75em) 100%,
           0% 100%;
         background-position:
-          -0.375em 0%,
+          calc(-1 * var(--wipe-gradient-half, 0.375em)) 0%,
           left;
       }
     }
 
-    @keyframes pre-wipe-universal-rtl {
+    @keyframes char-start-wipe {
       from {
         background-size:
-          0.75em 100%,
+          var(--wipe-gradient-width, 0.75em) 100%,
           0% 100%;
         background-position:
-          calc(100% + 0.75em) 0%,
-          right 0%;
+          calc(-1 * var(--wipe-gradient-width, 0.75em)) 0%,
+          left;
       }
       to {
         background-size:
-          0.75em 100%,
-          0% 100%;
+          var(--wipe-gradient-width, 0.75em) 100%,
+          100% 100%;
         background-position:
-          calc(100% + 0.375em) 0%,
-          right 0%;
+          calc(100% + var(--wipe-gradient-half, 0.375em)) 0%,
+          left;
       }
     }
 
-    @keyframes pre-wipe-char {
+    @keyframes char-wipe {
       from {
         background-size:
-          0.75em 100%,
+          var(--wipe-gradient-width, 0.75em) 100%,
           0% 100%;
         background-position:
-          -0.75em 0%,
+          calc(-1 * var(--wipe-gradient-half, 0.375em)) 0%,
           left;
       }
       to {
         background-size:
-          0.75em 100%,
-          0% 100%;
+          var(--wipe-gradient-width, 0.75em) 100%,
+          100% 100%;
         background-position:
-          -0.375em 0%,
+          calc(100% + var(--wipe-gradient-half, 0.375em)) 0%,
           left;
       }
     }
@@ -5797,6 +6403,15 @@ AmLyrics$1.styles = i$3 `
       }
     }
 
+    @keyframes drag-char {
+      0% {
+        transform: translate3d(0, 0, 0);
+      }
+      100% {
+        transform: translate3d(0, var(--char-rise-y, -1.12px), 0);
+      }
+    }
+
     @keyframes grow-static {
       0%,
       100% {