@uimaxbai/am-lyrics 1.1.7 → 1.2.0

package/dist/src/am-lyrics.js

@@ -85,6 +85,7 @@ const CONFIG = {
     GOOGLE: {
         MAX_RETRIES: 3,
         RETRY_DELAY_MS: 1000,
+        FETCH_TIMEOUT_MS: 6000,
     },
 };
 /**
@@ -96,6 +97,11 @@ class GoogleService {
             setTimeout(resolve, ms);
         });
     }
+    static fetchWithTimeout(url, timeoutMs = CONFIG.GOOGLE.FETCH_TIMEOUT_MS) {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+        return fetch(url, { signal: controller.signal }).finally(() => clearTimeout(timeoutId));
+    }
     static isPurelyLatinScript(text) {
         // Basic check for Latin script characters plus common punctuation and numbers
         // eslint-disable-next-line no-control-regex
@@ -137,7 +143,7 @@ class GoogleService {
                 try {
                     const url = `https://translate.googleapis.com/translate_a/single?client=gtx&sl=auto&tl=${targetLang}&dt=t&q=${encodeURIComponent(joinedText)}`;
                     // eslint-disable-next-line no-await-in-loop
-                    const response = await fetch(url);
+                    const response = await GoogleService.fetchWithTimeout(url);
                     if (!response.ok)
                         throw new Error(`Status ${response.status}`);
                     // eslint-disable-next-line no-await-in-loop
@@ -210,9 +216,11 @@ class GoogleService {
         // Determine if we should treat as word-synced (has syllabus) or line-synced
         const lines = Array.isArray(originalLyrics)
             ? originalLyrics
-            : originalLyrics.data || originalLyrics.content;
-        if (!lines)
-            return originalLyrics;
+            : originalLyrics.data ||
+                originalLyrics.content ||
+                [];
+        if (!lines || lines.length === 0)
+            return Array.isArray(originalLyrics) ? originalLyrics : [];
         // Check if word synced
         const isWordSynced = lines.some((l) => l.isWordSynced !== false && Array.isArray(l.text) && l.text.length > 1);
         if (isWordSynced) {
@@ -229,7 +237,9 @@ class GoogleService {
             )
                 return line;
             // Get the entire line text to romanize together for context-aware pronunciation
-            const fullText = line.text.map((s) => s.text).join('');
+            const fullText = line.text
+                .map((s) => s.text)
+                .join('');
             // romanizeTexts expects an array of strings, so we pass an array of one
             const [romanizedFullLine] = await this.romanizeTexts([fullText]);
             const newSyllabus = line.text.map((s) => ({
@@ -279,7 +289,7 @@ class GoogleService {
                 while (attempt < CONFIG.GOOGLE.MAX_RETRIES && !success) {
                     try {
                         const romanizeUrl = `https://translate.googleapis.com/translate_a/single?client=gtx&sl=auto&tl=en&dt=rm&q=${encodeURIComponent(text)}`;
-                        const response = await fetch(romanizeUrl);
+                        const response = await GoogleService.fetchWithTimeout(romanizeUrl);
                         const data = await response.json();
                         // Response format is [[["...","...","...","romanization"]],...]
                         // or [null, ...] for English/Latin input where no romanization is needed
@@ -309,8 +319,26 @@ class GoogleService {
     }
 }
 
-const VERSION = '1.1.7';
+const VERSION = '1.2.0';
 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;
+const PRE_SCROLL_LEAD_MS = 500;
+const SCROLL_ANIMATION_DURATION_MS = 280;
+const SCROLL_DELAY_INCREMENT_MS = 24;
+const GAP_PULSE_DURATION_MS = 4000;
+const GAP_PULSE_CYCLE_MS = GAP_PULSE_DURATION_MS * 2;
+const GAP_EXIT_LEAD_MS = 360;
+const GAP_MIN_SCALE = 0.85;
+/**
+ * Fetch with an automatic timeout via AbortSignal.
+ * Rejects if the request takes longer than `timeoutMs`.
+ */
+function fetchWithTimeout(url, options = {}, timeoutMs = FETCH_TIMEOUT_MS) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+    return fetch(url, { ...options, signal: controller.signal }).finally(() => clearTimeout(timeoutId));
+}
 const KPOE_SERVERS = [
     'https://lyricsplus.binimum.org',
     'https://lyricsplus.atomix.one',
@@ -374,6 +402,9 @@ class AmLyrics extends i {
         // Syllable animation tracking
         this.lastActiveIndex = 0;
         this.visibleLineIds = new Set();
+        // Bound handler references for proper event listener removal
+        this._boundHandleUserScroll = this.handleUserScroll.bind(this);
+        this._boundAnimateProgress = this.animateProgress.bind(this);
     }
     async toggleRomanization() {
         this.showRomanization = !this.showRomanization;
@@ -459,12 +490,38 @@ class AmLyrics extends i {
         super.disconnectedCallback();
         if (this.animationFrameId) {
             cancelAnimationFrame(this.animationFrameId);
+            this.animationFrameId = undefined;
         }
         if (this.userScrollTimeoutId) {
             clearTimeout(this.userScrollTimeoutId);
+            this.userScrollTimeoutId = undefined;
+        }
+        if (this.clickSeekTimeout) {
+            clearTimeout(this.clickSeekTimeout);
+            this.clickSeekTimeout = undefined;
+        }
+        if (this.scrollUnlockTimeout) {
+            clearTimeout(this.scrollUnlockTimeout);
+            this.scrollUnlockTimeout = undefined;
+        }
+        if (this.scrollAnimationTimeout) {
+            clearTimeout(this.scrollAnimationTimeout);
+            this.scrollAnimationTimeout = undefined;
+        }
+        // Cancel any in-flight fetch requests
+        this.fetchAbortController?.abort();
+        this.fetchAbortController = undefined;
+        // Remove scroll event listeners
+        if (this.lyricsContainer) {
+            this.lyricsContainer.removeEventListener('wheel', this._boundHandleUserScroll);
+            this.lyricsContainer.removeEventListener('touchmove', this._boundHandleUserScroll);
         }
     }
     async fetchLyrics() {
+        // Cancel any in-flight fetch to prevent stale results from racing
+        this.fetchAbortController?.abort();
+        const controller = new AbortController();
+        this.fetchAbortController = controller;
         this.isLoading = true;
         this.lyrics = undefined;
         this.lyricsSource = null;
@@ -474,6 +531,9 @@ class AmLyrics extends i {
         this.hasFetchedAllProviders = false;
         try {
             const resolvedMetadata = await this.resolveSongMetadata();
+            // If a newer fetch was triggered while we awaited, bail out
+            if (controller.signal.aborted)
+                return;
             const isMusicIdOnlyRequest = Boolean(this.musicId) &&
                 !this.songTitle &&
                 !this.songArtist &&
@@ -532,7 +592,10 @@ class AmLyrics extends i {
             this.lyricsSource = null;
         }
         finally {
-            this.isLoading = false;
+            // Only update loading state if this fetch wasn't superseded
+            if (!controller.signal.aborted) {
+                this.isLoading = false;
+            }
         }
     }
     async onLyricsLoaded() {
@@ -793,7 +856,7 @@ class AmLyrics extends i {
             const url = `${normalizedBase}/v1/songlist/search?q=${encodeURIComponent(trimmedQuery)}`;
             try {
                 // eslint-disable-next-line no-await-in-loop
-                const response = await fetch(url);
+                const response = await fetchWithTimeout(url);
                 if (response.ok) {
                     // eslint-disable-next-line no-await-in-loop
                     const payload = await response.json();
@@ -827,7 +890,9 @@ class AmLyrics extends i {
         if (metadata.durationMs && metadata.durationMs > 0) {
             params.append('duration', Math.round(metadata.durationMs / 1000).toString());
         }
-        params.append('source', DEFAULT_KPOE_SOURCE_ORDER);
+        if (!DEFAULT_KPOE_SOURCE_ORDER.includes('apple')) {
+            params.append('source', DEFAULT_KPOE_SOURCE_ORDER);
+        }
         const getRank = (sourceLabel, parsedLines) => {
             const lower = sourceLabel.toLowerCase();
             const hasWordSync = parsedLines.some((line) => line.text && Array.isArray(line.text) && line.text.length > 1);
@@ -872,13 +937,13 @@ class AmLyrics extends i {
                 cacheParams.append('duration', Math.round(metadata.durationMs / 1000).toString());
             }
             const cacheUrl = `https://lyrics-api.binimum.org/?${cacheParams.toString()}`;
-            const cacheRes = await fetch(cacheUrl);
+            const cacheRes = await fetchWithTimeout(cacheUrl);
             if (cacheRes.ok) {
                 const cacheData = await cacheRes.json();
                 if (cacheData.results && cacheData.results.length > 0) {
                     const result = cacheData.results[0];
                     if (result.timing_type === 'word' && result.lyricsUrl) {
-                        const ttmlRes = await fetch(result.lyricsUrl);
+                        const ttmlRes = await fetchWithTimeout(result.lyricsUrl);
                         if (ttmlRes.ok) {
                             const ttmlText = await ttmlRes.text();
                             const lines = AmLyrics.parseTTML(ttmlText);
@@ -893,7 +958,7 @@ class AmLyrics extends i {
                         const fallbackParams = new URLSearchParams(params);
                         const fallbackUrl = `https://lyricsplus.binimum.org/v2/lyrics/get?${fallbackParams.toString()}`;
                         try {
-                            const fallbackRes = await fetch(fallbackUrl);
+                            const fallbackRes = await fetchWithTimeout(fallbackUrl);
                             if (fallbackRes.ok) {
                                 const payload = await fallbackRes.json();
                                 const lines = AmLyrics.convertKPoeLyrics(payload);
@@ -914,7 +979,7 @@ class AmLyrics extends i {
                         }
                         // If fallback fails or has no word sync, fall back to bini lyrics
                         if (result.lyricsUrl) {
-                            const ttmlRes = await fetch(result.lyricsUrl);
+                            const ttmlRes = await fetchWithTimeout(result.lyricsUrl);
                             if (ttmlRes.ok) {
                                 const ttmlText = await ttmlRes.text();
                                 const lines = AmLyrics.parseTTML(ttmlText);
@@ -936,23 +1001,23 @@ class AmLyrics extends i {
             console.error('Cache API failed', e);
         }
         // Shuffle servers so we pick a random one first, with all others as fallback
-        // Limit to 2 servers to prevent unnecessary API spam when Apple lyrics are missing
+        // Try up to 3 servers to improve reliability when some have CORS or connectivity issues
         const shuffledServers = [...KPOE_SERVERS]
             .sort(() => Math.random() - 0.5)
-            .slice(0, 2);
+            .slice(0, 3);
         for (const base of shuffledServers) {
             const normalizedBase = base.endsWith('/') ? base.slice(0, -1) : base;
             const url = `${normalizedBase}/v2/lyrics/get?${params.toString()}`;
             let payload = null;
             try {
                 // eslint-disable-next-line no-await-in-loop
-                const response = await fetch(url);
+                const response = await fetchWithTimeout(url);
                 if (response.ok) {
                     // eslint-disable-next-line no-await-in-loop
                     payload = await response.json();
                 }
             }
-            catch (error) {
+            catch {
                 payload = null;
             }
             if (payload) {
@@ -978,7 +1043,7 @@ class AmLyrics extends i {
             try {
                 const fallbackParams = new URLSearchParams(params);
                 const url = `https://lyricsplus.binimum.org/v2/lyrics/get?${fallbackParams.toString()}`;
-                const response = await fetch(url);
+                const response = await fetchWithTimeout(url);
                 if (response.ok) {
                     const payload = await response.json();
                     if (payload) {
@@ -1014,7 +1079,6 @@ class AmLyrics extends i {
             if (!match) {
                 // Skip non-timestamped lines (headers like [ti:], [ar:], etc.)
                 // eslint-disable-next-line no-continue
-                // eslint-disable-next-line no-continue
                 continue;
             }
             const minutes = parseInt(match[1], 10);
@@ -1034,7 +1098,6 @@ class AmLyrics extends i {
             const endtime = i + 1 < parsed.length ? parsed[i + 1].timestamp : timestamp + 5000;
             // Skip empty lines (instrumental gaps)
             if (!text.trim()) {
-                // eslint-disable-next-line no-continue
                 // eslint-disable-next-line no-continue
                 continue;
             }
@@ -1066,9 +1129,9 @@ class AmLyrics extends i {
         const artist = metadata.artist?.trim();
         if (!title || !artist)
             return null;
-        // Pick 2 random unique servers
+        // Pick 3 random unique servers for better reliability
         const shuffled = [...TIDAL_SERVERS].sort(() => Math.random() - 0.5);
-        const serversToTry = shuffled.slice(0, 2);
+        const serversToTry = shuffled.slice(0, 3);
         for (const base of serversToTry) {
             try {
                 const normalizedBase = base.endsWith('/') ? base.slice(0, -1) : base;
@@ -1076,9 +1139,8 @@ class AmLyrics extends i {
                 const searchQuery = `${title} ${artist}`;
                 const searchParams = new URLSearchParams({ s: searchQuery });
                 // eslint-disable-next-line no-await-in-loop
-                const searchResponse = await fetch(`${normalizedBase}/search/?${searchParams.toString()}`);
+                const searchResponse = await fetchWithTimeout(`${normalizedBase}/search/?${searchParams.toString()}`);
                 if (!searchResponse.ok) {
-                    // eslint-disable-next-line no-continue
                     // eslint-disable-next-line no-continue
                     continue;
                 }
@@ -1086,7 +1148,6 @@ class AmLyrics extends i {
                 const searchData = await searchResponse.json();
                 const items = searchData?.data?.items;
                 if (!Array.isArray(items) || items.length === 0) {
-                    // eslint-disable-next-line no-continue
                     // eslint-disable-next-line no-continue
                     continue;
                 }
@@ -1100,15 +1161,13 @@ class AmLyrics extends i {
                 }
                 const trackId = bestTrack?.id;
                 if (!trackId) {
-                    // eslint-disable-next-line no-continue
                     // eslint-disable-next-line no-continue
                     continue;
                 }
                 // Step 2: Fetch lyrics
                 // eslint-disable-next-line no-await-in-loop
-                const lyricsResponse = await fetch(`${normalizedBase}/lyrics/?id=${trackId}`);
+                const lyricsResponse = await fetchWithTimeout(`${normalizedBase}/lyrics/?id=${trackId}`);
                 if (!lyricsResponse.ok) {
-                    // eslint-disable-next-line no-continue
                     // eslint-disable-next-line no-continue
                     continue;
                 }
@@ -1144,7 +1203,7 @@ class AmLyrics extends i {
         try {
             const searchQuery = `${artist} ${title}`;
             const params = new URLSearchParams({ q: searchQuery });
-            const response = await fetch(`https://lrclib.net/api/search?${params.toString()}`, {
+            const response = await fetchWithTimeout(`https://lrclib.net/api/search?${params.toString()}`, {
                 headers: {
                     'User-Agent': `apple-music-web-components/${VERSION}`,
                 },
@@ -1202,7 +1261,7 @@ class AmLyrics extends i {
             return null;
         try {
             const params = new URLSearchParams({ title, artist });
-            const response = await fetch(`${GENIUS_WORKER_URL}?${params.toString()}`);
+            const response = await fetchWithTimeout(`${GENIUS_WORKER_URL}?${params.toString()}`);
             if (!response.ok)
                 return null;
             const data = await response.json();
@@ -1233,8 +1292,7 @@ class AmLyrics extends i {
             }
         }
         catch {
-            // eslint-disable-next-line no-console
-            console.error('No Genius lyrics found');
+            // Genius fetch failed, will fall through to return null
         }
         return null;
     }
@@ -1326,19 +1384,6 @@ class AmLyrics extends i {
                     }
                 }
             }
-            const transliterationNodes = doc.getElementsByTagName('transliteration');
-            for (let i = 0; i < transliterationNodes.length; i += 1) {
-                const texts = transliterationNodes[i].getElementsByTagName('text');
-                for (let j = 0; j < texts.length; j += 1) {
-                    const textNode = texts[j];
-                    const key = textNode.getAttribute('for');
-                    if (key && textNode.textContent) {
-                        transliterations[key] = textNode.textContent
-                            .trim()
-                            .replace(/\s+/g, ' ');
-                    }
-                }
-            }
             const timeToMs = (timeStr) => {
                 if (!timeStr)
                     return 0;
@@ -1358,6 +1403,52 @@ class AmLyrics extends i {
                 }
                 return Math.round(seconds * 1000);
             };
+            const transliterationNodes = doc.getElementsByTagName('transliteration');
+            for (let i = 0; i < transliterationNodes.length; i += 1) {
+                const texts = transliterationNodes[i].getElementsByTagName('text');
+                for (let j = 0; j < texts.length; j += 1) {
+                    const textNode = texts[j];
+                    const key = textNode.getAttribute('for');
+                    if (!key) {
+                        // eslint-disable-next-line no-continue
+                        continue;
+                    }
+                    const spans = Array.from(textNode.getElementsByTagName('span')).filter(span => span.getAttribute('begin'));
+                    if (spans.length > 0) {
+                        const syllabus = [];
+                        let fullText = '';
+                        for (let k = 0; k < spans.length; k += 1) {
+                            const span = spans[k];
+                            const begin = span.getAttribute('begin');
+                            const end = span.getAttribute('end');
+                            let spanText = span.textContent || '';
+                            const nextNode = span.nextSibling;
+                            if (nextNode &&
+                                nextNode.nodeType === 3 &&
+                                /^\s/.test(nextNode.textContent || '') &&
+                                !spanText.endsWith(' ')) {
+                                spanText += ' ';
+                            }
+                            if (spanText.trim() === '') {
+                                // eslint-disable-next-line no-continue
+                                continue;
+                            }
+                            syllabus.push({
+                                time: timeToMs(begin),
+                                duration: timeToMs(end) - timeToMs(begin),
+                                text: spanText,
+                            });
+                            fullText += spanText;
+                        }
+                        transliterations[key] = { text: fullText.trim(), syllabus };
+                    }
+                    else if (textNode.textContent) {
+                        transliterations[key] = {
+                            text: textNode.textContent.trim().replace(/\s+/g, ' '),
+                        };
+                    }
+                }
+            }
             const lines = [];
             const pNodes = doc.getElementsByTagName('p');
             const lineSingers = [];
@@ -1435,6 +1526,64 @@ class AmLyrics extends i {
                     });
                 }
                 const alignment = alignments[i];
+                // Distribute line-level transliteration to individual syllables
+                // so that per-syllable animated romanisation works (like KPoe lyrics)
+                const lineTransliterationItem = key ? transliterations[key] : undefined;
+                if (lineTransliterationItem &&
+                    mainSyllables.length > 1 &&
+                    spans.length > 0) {
+                    if (lineTransliterationItem.syllabus &&
+                        lineTransliterationItem.syllabus.length === mainSyllables.length) {
+                        mainSyllables.forEach((syl, mapIdx) => {
+                            // eslint-disable-next-line no-param-reassign
+                            syl.romanizedText = lineTransliterationItem.syllabus[mapIdx].text;
+                        });
+                    }
+                    else {
+                        const lineTransliteration = lineTransliterationItem.text;
+                        const romanWords = lineTransliteration.split(/\s+/).filter(Boolean);
+                        const syllableGroups = [];
+                        for (let si = 0; si < mainSyllables.length; si += 1) {
+                            if (mainSyllables[si].part && syllableGroups.length > 0) {
+                                syllableGroups[syllableGroups.length - 1].push(si);
+                            }
+                            else {
+                                syllableGroups.push([si]);
+                            }
+                        }
+                        const isCJK = /[\u4e00-\u9fff\u3040-\u309f\u30a0-\u30ff\uac00-\ud7af]/.test(mainSyllables.map(s => s.text).join(''));
+                        if (romanWords.length === syllableGroups.length) {
+                            syllableGroups.forEach((group, gi) => {
+                                // eslint-disable-next-line no-param-reassign
+                                mainSyllables[group[0]].romanizedText = romanWords[gi];
+                            });
+                        }
+                        else if (romanWords.length === mainSyllables.length) {
+                            mainSyllables.forEach((syl, mapIdx) => {
+                                // eslint-disable-next-line no-param-reassign
+                                syl.romanizedText = romanWords[mapIdx];
+                            });
+                        }
+                        else if (isCJK) {
+                            let romanIdx = 0;
+                            for (const group of syllableGroups) {
+                                const syl = mainSyllables[group[0]];
+                                const sylText = group
+                                    .map(gIndex => mainSyllables[gIndex].text)
+                                    .join('');
+                                const validChars = sylText.match(/[\u4e00-\u9fff\u3040-\u309f\u30a0-\u30ff\uac00-\ud7afA-Za-z0-9]/g) || [];
+                                const needed = validChars.length;
+                                if (needed > 0 && romanIdx < romanWords.length) {
+                                    // eslint-disable-next-line no-param-reassign
+                                    syl.romanizedText = romanWords
+                                        .slice(romanIdx, romanIdx + needed)
+                                        .join(' ');
+                                    romanIdx += needed;
+                                }
+                            }
+                        }
+                    }
+                }
                 lines.push({
                     text: mainSyllables,
                     background: bgSyllables.length > 0,
@@ -1445,7 +1594,7 @@ class AmLyrics extends i {
                     alignment,
                     songPart,
                     translation: key ? translations[key] : undefined,
-                    romanizedText: key ? transliterations[key] : undefined,
+                    romanizedText: lineTransliterationItem?.text,
                     oppositeTurn: alignment === 'end',
                 });
             }
@@ -1590,8 +1739,8 @@ class AmLyrics extends i {
         // Use wheel/touchmove which are guaranteed to be user initiated,
         // unlike 'scroll' which fires for both user and programmatic/inertia
         if (this.lyricsContainer) {
-            this.lyricsContainer.addEventListener('wheel', this.handleUserScroll.bind(this), { passive: true });
-            this.lyricsContainer.addEventListener('touchmove', this.handleUserScroll.bind(this), { passive: true });
+            this.lyricsContainer.addEventListener('wheel', this._boundHandleUserScroll, { passive: true });
+            this.lyricsContainer.addEventListener('touchmove', this._boundHandleUserScroll, { passive: true });
         }
     }
     /**
@@ -1602,12 +1751,12 @@ class AmLyrics extends i {
      */
     _onTimeChanged(oldTime, newTime) {
         const timeDiff = Math.abs(newTime - oldTime);
+        const isSeek = timeDiff > SEEK_THRESHOLD_MS;
         const newActiveLines = this.findActiveLineIndices(newTime);
         const oldActiveLines = this.activeLineIndices;
         // Reset animation if active lines change or if we skip time.
-        // A threshold of 0.5s (500ms) is used to detect a "skip".
         const linesChanged = !AmLyrics.arraysEqual(newActiveLines, oldActiveLines);
-        if (linesChanged || timeDiff > 0.5) {
+        if (linesChanged || isSeek) {
             // Imperatively manage 'active' class so that scroll-animate and other
             // imperative classes are never clobbered.
             if (this.lyricsContainer) {
@@ -1631,20 +1780,13 @@ class AmLyrics extends i {
                         }
                     }
                 }
-            }
-            this.startAnimationFromTime(newTime);
-            // Update position classes BEFORE scrolling so currentPrimaryActiveLine is current
-            if (this.lyricsContainer && this.activeLineIndices.length > 0) {
-                const primaryLineIndex = this.activeLineIndices[0];
-                const primaryLine = this.lyricsContainer.querySelector(`#lyrics-line-${primaryLineIndex}`);
-                if (primaryLine && primaryLine !== this.currentPrimaryActiveLine) {
-                    this.lastPrimaryActiveLine = this.currentPrimaryActiveLine;
-                    this.currentPrimaryActiveLine = primaryLine;
-                    this.updatePositionClasses(primaryLine);
+                if (newActiveLines.length > 0) {
+                    this.clearPreActiveClasses();
                 }
             }
+            this.startAnimationFromTime(newTime);
             // Trigger scroll imperatively (was previously in updated() via @state)
-            this._handleActiveLineScroll(oldActiveLines);
+            this._handleActiveLineScroll(oldActiveLines, isSeek);
         }
         // YouLyPlus-style syllable animation updates
         if (this.lyricsContainer) {
@@ -1669,7 +1811,7 @@ class AmLyrics extends i {
                 const isActive = gap.classList.contains('active');
                 const isExiting = gap.classList.contains('gap-exiting');
                 // Start exit animation early so it completes before the next lyric
-                const exitLeadMs = 600;
+                const exitLeadMs = GAP_EXIT_LEAD_MS;
                 const shouldStartExiting = isActive && !isExiting && newTime >= gapEndTime - exitLeadMs;
                 if (shouldBeActive && !isActive && !isExiting) {
                     // Entering gap: remove any leftover exit state, add active
@@ -1694,13 +1836,6 @@ class AmLyrics extends i {
                             AmLyrics.updateSyllableAnimation(dot);
                         }
                     });
-                    // Scroll to the gap element so dots animate in with
-                    // the staggered scroll rather than popping in.
-                    if (this.autoScroll &&
-                        !this.isUserScrolling &&
-                        !this.isClickSeeking) {
-                        this.scrollToActiveLineYouLy(gap);
-                    }
                 }
                 else if (shouldStartExiting) {
                     // Exiting gap: keep visible while dots animate out
@@ -1709,7 +1844,7 @@ class AmLyrics extends i {
                     // After exit animation completes, remove gap-exiting to collapse
                     setTimeout(() => {
                         gap.classList.remove('gap-exiting');
-                    }, 800);
+                    }, GAP_EXIT_LEAD_MS);
                 }
                 else if (isActive && !shouldBeActive) {
                     // NEW: Immediate cleanup if we seeked out of valid range
@@ -1729,48 +1864,32 @@ class AmLyrics extends i {
             else if (this.lastInstrumentalIndex !== null) {
                 this.lastInstrumentalIndex = null;
             }
-            // Update position classes for YouLyPlus blur/opacity effect
-            // (only needed when lines didn't change — when they DID change,
-            // position classes are already updated above before scrolling)
-            if (!linesChanged && this.activeLineIndices.length > 0) {
-                const primaryLineIndex = this.activeLineIndices[0];
-                const primaryLine = this.lyricsContainer.querySelector(`#lyrics-line-${primaryLineIndex}`);
-                if (primaryLine && primaryLine !== this.currentPrimaryActiveLine) {
-                    this.lastPrimaryActiveLine = this.currentPrimaryActiveLine;
-                    this.currentPrimaryActiveLine = primaryLine;
-                    this.updatePositionClasses(primaryLine);
-                }
-            }
             // Pre-scroll: scroll to upcoming line ~0.5s before it starts
             if (this.autoScroll &&
                 !this.isUserScrolling &&
                 !this.isClickSeeking &&
                 this.lyrics) {
-                const preScrollLeadMs = 500; // 500ms lead time
                 // Condition: ONLY pre-scroll if no other lyric is currently playing.
                 // If a lyric is playing, we must wait for it to finish (handled by updated()).
                 if (this.activeLineIndices.length === 0) {
+                    let preActiveLineIndex = null;
                     for (let i = 0; i < this.lyrics.length; i += 1) {
                         const line = this.lyrics[i];
                         const timeUntilStart = line.timestamp - newTime;
                         const nextLineEl = this.lyricsContainer.querySelector(`#lyrics-line-${i}`);
-                        if (timeUntilStart > 0 && timeUntilStart <= preScrollLeadMs) {
+                        if (timeUntilStart > 0 && timeUntilStart <= PRE_SCROLL_LEAD_MS) {
                             // Time to pre-scroll and pre-activate!
                             if (nextLineEl) {
                                 // Apply unblur & zoom effect ahead of lyric start
+                                preActiveLineIndex = i;
                                 nextLineEl.classList.add('pre-active');
-                                // Only trigger scroll if we aren't already targeting this line
-                                if (nextLineEl !== this.currentPrimaryActiveLine) {
-                                    this.scrollToActiveLineYouLy(nextLineEl);
-                                }
+                                this.clearPreActiveClasses(i);
+                                this.focusLine(nextLineEl);
                             }
                             break;
                         }
-                        else if (nextLineEl) {
-                            // Ensure lines outside the pre-scroll window don't stay pre-active
-                            nextLineEl.classList.remove('pre-active');
-                        }
                     }
+                    this.clearPreActiveClasses(preActiveLineIndex);
                 }
             }
         }
@@ -1834,32 +1953,16 @@ class AmLyrics extends i {
      * Handle scrolling when active line indices change.
      * Called imperatively from _onTimeChanged instead of from updated().
      */
-    _handleActiveLineScroll(oldActiveIndices) {
-        if (!this.autoScroll ||
-            this.isUserScrolling ||
-            this.isClickSeeking ||
-            this.activeLineIndices.length === 0) {
+    _handleActiveLineScroll(_oldActiveIndices, forceScroll = false) {
+        if (this.activeLineIndices.length === 0 || !this.lyricsContainer) {
             return;
         }
-        // Determine what changed: did we gain new lines or just lose old ones?
-        const newlyAdded = this.activeLineIndices.filter(idx => !oldActiveIndices.includes(idx));
-        if (newlyAdded.length === 0) {
-            // Only lost lines (an overlap resolved) — don't scroll
+        const targetLineIndex = this.getPrimaryActiveLineIndex(this.activeLineIndices);
+        if (targetLineIndex === null)
             return;
-        }
-        // New lines were added — scroll to the latest newly-added line.
-        // Previous overlap logic skipped every other line for songs with tiny
-        // timing overlaps between consecutive lines, causing a visible glitch.
-        const latestNewIndex = newlyAdded[newlyAdded.length - 1];
-        const targetLine = this.lyricsContainer?.querySelector(`#lyrics-line-${latestNewIndex}`);
+        const targetLine = this.lyricsContainer.querySelector(`#lyrics-line-${targetLineIndex}`);
         if (targetLine) {
-            this.scrollToActiveLineYouLy(targetLine);
-        }
-        else if (this.currentPrimaryActiveLine) {
-            this.scrollToActiveLineYouLy(this.currentPrimaryActiveLine);
-        }
-        else {
-            this.scrollToActiveLine();
+            this.focusLine(targetLine, forceScroll);
         }
     }
     _getTextWidth(text, font) {
@@ -1933,6 +2036,62 @@ class AmLyrics extends i {
     static arraysEqual(a, b) {
         return a.length === b.length && a.every((val, i) => val === b[i]);
     }
+    static getLineIndexFromElement(lineElement) {
+        if (!lineElement)
+            return null;
+        const match = lineElement.id.match(/^lyrics-line-(\d+)$/);
+        return match ? parseInt(match[1], 10) : null;
+    }
+    static getGapLoopDelay(gapDuration) {
+        const desiredPhase = GAP_PULSE_DURATION_MS;
+        const targetTime = gapDuration - GAP_EXIT_LEAD_MS;
+        const normalizedTarget = ((targetTime % GAP_PULSE_CYCLE_MS) + GAP_PULSE_CYCLE_MS) %
+            GAP_PULSE_CYCLE_MS;
+        return ((((desiredPhase - normalizedTarget) % GAP_PULSE_CYCLE_MS) +
+            GAP_PULSE_CYCLE_MS) %
+            GAP_PULSE_CYCLE_MS);
+    }
+    clearPreActiveClasses(exceptLineIndex = null) {
+        if (!this.lyricsContainer)
+            return;
+        this.lyricsContainer
+            .querySelectorAll('.lyrics-line.pre-active')
+            .forEach(element => {
+            const lineElement = element;
+            const lineIndex = AmLyrics.getLineIndexFromElement(lineElement);
+            if (lineIndex !== exceptLineIndex) {
+                lineElement.classList.remove('pre-active');
+            }
+        });
+    }
+    getPrimaryActiveLineIndex(activeIndices) {
+        if (activeIndices.length === 0)
+            return null;
+        const groupStart = activeIndices[0];
+        const groupEnd = activeIndices[activeIndices.length - 1];
+        let candidateIndex = Math.max(groupStart, groupEnd - 2);
+        const currentPrimaryIndex = AmLyrics.getLineIndexFromElement(this.currentPrimaryActiveLine);
+        if (currentPrimaryIndex !== null &&
+            activeIndices.includes(currentPrimaryIndex) &&
+            candidateIndex < currentPrimaryIndex) {
+            candidateIndex = currentPrimaryIndex;
+        }
+        return candidateIndex;
+    }
+    focusLine(lineElement, forceScroll = false) {
+        const primaryChanged = lineElement !== this.currentPrimaryActiveLine;
+        if (primaryChanged) {
+            this.lastPrimaryActiveLine = this.currentPrimaryActiveLine;
+            this.currentPrimaryActiveLine = lineElement;
+        }
+        this.updatePositionClasses(lineElement);
+        if ((forceScroll || primaryChanged) &&
+            this.autoScroll &&
+            !this.isUserScrolling &&
+            !this.isClickSeeking) {
+            this.scrollToActiveLineYouLy(lineElement, forceScroll);
+        }
+    }
     handleUserScroll() {
         // Ignore programmatic scrolls and click-seek scrolls
         if (this.isProgrammaticScroll || this.isClickSeeking) {
@@ -2202,7 +2361,8 @@ class AmLyrics extends i {
         this.activeLineIds.clear();
         this.animatingLines = [];
         // Find the clicked line element and scroll to it with forceScroll (like YouLyPlus)
-        const clickedLineElement = this.lyricsContainer?.querySelector(`.lyrics-line[data-start-time="${line.timestamp * 1000}"]`);
+        // 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}"]`);
         if (clickedLineElement && this.lyricsContainer) {
             // Update active line reference to the clicked line
             this.currentPrimaryActiveLine = clickedLineElement;
@@ -2328,11 +2488,10 @@ class AmLyrics extends i {
         }
         const { animatingLines } = this;
         const targetTop = Math.max(0, -newTranslateY);
-        // Always use actual scroll position - don't fall back to stale currentScrollOffset
-        // The || operator treats 0 as falsy, which caused bounce when scrollTop was 0
+        const appliedTranslateY = -targetTop;
         const prevOffset = -parent.scrollTop;
-        const delta = prevOffset - newTranslateY;
-        this.currentScrollOffset = newTranslateY;
+        const delta = prevOffset - appliedTranslateY;
+        this.currentScrollOffset = appliedTranslateY;
         // Skip animation if already at the target position (e.g., first lines at top)
         if (Math.abs(parent.scrollTop - targetTop) < 1 && Math.abs(delta) < 1) {
             animState.isAnimating = false;
@@ -2345,6 +2504,7 @@ class AmLyrics extends i {
                 line.classList.remove('scroll-animate');
                 line.style.removeProperty('--scroll-delta');
                 line.style.removeProperty('--lyrics-line-delay');
+                line.style.removeProperty('--scroll-duration');
             }
             animatingLines.length = 0;
             parent.scrollTo({ top: targetTop, behavior: 'smooth' });
@@ -2368,7 +2528,7 @@ class AmLyrics extends i {
         const referenceIndex = lineArray.indexOf(referenceLine);
         if (referenceIndex === -1)
             return;
-        const delayIncrement = 30;
+        const delayIncrement = SCROLL_DELAY_INCREMENT_MS;
         const lookBehind = 10;
         const lookAhead = 15;
         const len = lineArray.length;
@@ -2385,8 +2545,9 @@ class AmLyrics extends i {
             const delay = i >= referenceIndex ? (delayCounter - 1) * delayIncrement : 0;
             line.style.setProperty('--scroll-delta', `${delta}px`);
             line.style.setProperty('--lyrics-line-delay', `${delay}ms`);
+            line.style.setProperty('--scroll-duration', `${SCROLL_ANIMATION_DURATION_MS}ms`);
             newAnimatingLines.push(line);
-            const lineDuration = 400 + delay;
+            const lineDuration = SCROLL_ANIMATION_DURATION_MS + delay;
             if (lineDuration > maxAnimationDuration) {
                 maxAnimationDuration = lineDuration;
             }
@@ -2401,7 +2562,7 @@ class AmLyrics extends i {
             animatingLines.push(line);
         }
         animState.isAnimating = true;
-        const BASE_DURATION = 400;
+        const BASE_DURATION = SCROLL_ANIMATION_DURATION_MS;
         this.scrollUnlockTimeout = setTimeout(() => {
             animState.isAnimating = false;
             if (animState.pendingUpdate !== null) {
@@ -2416,6 +2577,7 @@ class AmLyrics extends i {
                 line.classList.remove('scroll-animate');
                 line.style.removeProperty('--scroll-delta');
                 line.style.removeProperty('--lyrics-line-delay');
+                line.style.removeProperty('--scroll-duration');
             }
             animatingLines.length = 0;
             this.scrollAnimationTimeout = undefined;
@@ -2497,7 +2659,7 @@ class AmLyrics extends i {
         }
         setTimeout(() => {
             this.isProgrammaticScroll = false;
-        }, 600);
+        }, SCROLL_ANIMATION_DURATION_MS + 160);
         this.animateScrollYouLy(targetTranslateY, forceScroll);
     }
     /**
@@ -2526,26 +2688,46 @@ class AmLyrics extends i {
         // Use a Map to collect animations like YouLyPlus
         const charAnimationsMap = new Map();
         const styleUpdates = [];
-        // Step 1: Grow Pass - apply grow-dynamic to ALL word chars on first syllable
+        // Step 1 & 2: Apply animations
         if (isGrowable && isFirstSyllable && allWordCharSpans.length > 0) {
-            const finalDuration = wordDurationMs;
-            const baseDelayPerChar = finalDuration * 0.09;
-            const growDurationMs = finalDuration * 1.5;
-            allWordCharSpans.forEach(span => {
+            // Glow AND wipe applied to ALL characters simultaneously from the first syllable
+            // This prevents CSS animation restarts because the `animation` property is set once.
+            const firstSyllableStartTime = parseFloat(syllable.getAttribute('data-start-time') || '0');
+            allWordCharSpans.forEach((span, charIndexInWord) => {
                 const horizontalOffset = parseFloat(span.dataset.horizontalOffset || '0');
-                // Use syllableCharIndex like YouLyPlus, not loop index
-                const charIndex = parseFloat(span.dataset.syllableCharIndex || '0');
-                const growDelay = baseDelayPerChar * charIndex;
-                // READ DATA ATTRIBUTES for style values
                 const maxScale = span.dataset.maxScale || '1.1';
                 const shadowIntensity = span.dataset.shadowIntensity || '0.6';
                 const translateYPeak = span.dataset.translateYPeak || '-2';
-                charAnimationsMap.set(span, `grow-dynamic ${growDurationMs}ms ease-in-out ${growDelay}ms forwards`);
-                // Push style updates to be applied imperatively
+                const animationParts = [];
+                const parentSyllable = span.closest('.lyrics-syllable');
+                if (parentSyllable) {
+                    const parentDuration = parseFloat(parentSyllable.getAttribute('data-duration') || '0');
+                    const parentStartTime = parseFloat(parentSyllable.getAttribute('data-start-time') || '0');
+                    const startPct = parseFloat(span.dataset.wipeStart || '0');
+                    const durationPct = parseFloat(span.dataset.wipeDuration || '0');
+                    const relativeStartOffset = Math.max(0, parentStartTime - firstSyllableStartTime);
+                    const wipeDelay = relativeStartOffset + parentDuration * startPct;
+                    const wipeDuration = parentDuration * durationPct;
+                    const useStartAnimation = isFirstInContainer && charIndexInWord === 0;
+                    let charWipeAnimation = 'wipe';
+                    if (useStartAnimation)
+                        charWipeAnimation = isRTL ? 'start-wipe-rtl' : 'start-wipe';
+                    else
+                        charWipeAnimation = isRTL ? 'wipe-rtl' : 'wipe';
+                    // Blend word and syllable durations to let the gradient flow smoothly
+                    // while still responding to syllable pacing (no strict exactness, just natural flow)
+                    const growDelay = wipeDelay;
+                    const growDurationMs = Math.max(600, wordDurationMs * 0.8 + parentDuration * 1.5);
+                    animationParts.push(`grow-dynamic ${growDurationMs}ms ease-in-out ${growDelay}ms forwards`);
+                    if (wipeDuration > 0) {
+                        animationParts.push(`${charWipeAnimation} ${wipeDuration}ms linear ${wipeDelay}ms forwards`);
+                    }
+                }
+                charAnimationsMap.set(span, animationParts.join(', '));
                 styleUpdates.push({
                     element: span,
                     property: '--char-offset-x',
-                    value: `${horizontalOffset}`, // Fixed: removed px suitable for matrix3d
+                    value: `${horizontalOffset}`,
                 });
                 styleUpdates.push({
                     element: span,
@@ -2560,58 +2742,64 @@ class AmLyrics extends i {
                 styleUpdates.push({
                     element: span,
                     property: '--translate-y-peak',
-                    value: `${translateYPeak}`, // Fixed: removed % because matrix3d expects raw number
+                    value: `${translateYPeak}`,
                 });
             });
         }
-        // Step 2: Wipe Pass
-        if (charSpans.length > 0) {
-            // Per-character wipe for growable words (matching YouLyPlus)
+        else if (isGrowable && !isFirstSyllable && charSpans.length > 0) {
+            // For subsequent syllables of a growable word:
+            // If they already have `grow-dynamic`, it means the first syllable correctly took care of BOTH grow and wipe!
+            // Otherwise, they scrubbed directly into this syllable, so let's at least do the wipe.
+            charSpans.forEach(span => {
+                const existingAnimation = charAnimationsMap.get(span) || span.style.animation || '';
+                if (existingAnimation.includes('grow-dynamic'))
+                    return;
+                const startPct = parseFloat(span.dataset.wipeStart || '0');
+                const durationPct = parseFloat(span.dataset.wipeDuration || '0');
+                const wipeDelay = syllableDurationMs * startPct;
+                const wipeDuration = syllableDurationMs * durationPct;
+                const charWipeAnimation = isRTL ? 'wipe-rtl' : 'wipe';
+                if (wipeDuration > 0) {
+                    charAnimationsMap.set(span, `${charWipeAnimation} ${wipeDuration}ms linear ${wipeDelay}ms forwards`);
+                }
+            });
+        }
+        else if (charSpans.length > 0) {
+            // Per-character wipe for non-growable words (matching YouLyPlus)
             charSpans.forEach((span, charIndex) => {
                 const startPct = parseFloat(span.dataset.wipeStart || '0');
                 const durationPct = parseFloat(span.dataset.wipeDuration || '0');
                 const wipeDelay = syllableDurationMs * startPct;
                 const wipeDuration = syllableDurationMs * durationPct;
                 const useStartAnimation = isFirstInContainer && charIndex === 0;
-                let charWipeAnimation;
+                let charWipeAnimation = 'wipe';
                 if (useStartAnimation) {
                     charWipeAnimation = isRTL ? 'start-wipe-rtl' : 'start-wipe';
                 }
                 else {
                     charWipeAnimation = isRTL ? 'wipe-rtl' : 'wipe';
                 }
-                // Get existing animation from map (grow-dynamic) and combine with wipe
-                const existingAnimation = charAnimationsMap.get(span) || span.style.animation || '';
-                const animationParts = [];
-                if (existingAnimation && existingAnimation.includes('grow-dynamic')) {
-                    animationParts.push(existingAnimation.split(',')[0].trim());
-                }
                 if (wipeDuration > 0) {
-                    animationParts.push(`${charWipeAnimation} ${wipeDuration}ms linear ${wipeDelay}ms forwards`);
+                    charAnimationsMap.set(span, `${charWipeAnimation} ${wipeDuration}ms linear ${wipeDelay}ms forwards`);
                 }
-                charAnimationsMap.set(span, animationParts.join(', '));
             });
         }
         else {
-            // Syllable-level wipe for regular (non-growable) words
+            // Syllable-level wipe for regular (non-growable) words without chars
             const wipeRatio = parseFloat(syllable.getAttribute('data-wipe-ratio') || '1');
             const visualDuration = syllableDurationMs * wipeRatio;
-            let wipeAnimation;
+            let wipeAnimation = 'wipe';
             if (isFirstInContainer) {
                 wipeAnimation = isRTL ? 'start-wipe-rtl' : 'start-wipe';
             }
             else {
                 wipeAnimation = isRTL ? 'wipe-rtl' : 'wipe';
             }
-            if (syllable.classList.contains('line-synced')) {
-                // If line-synced, just add the class for CSS animation, or ensure valid state
-                // The CSS rule .lyrics-syllable.line-synced handles the fade
+            if (syllable.classList.contains('line-synced'))
                 return;
-            }
             const currentWipeAnimation = isGap ? 'fade-gap' : wipeAnimation;
-            const syllableAnimation = `${currentWipeAnimation} ${visualDuration}ms ${isGap ? 'ease-out' : 'linear'} forwards`;
             // eslint-disable-next-line no-param-reassign
-            syllable.style.animation = syllableAnimation;
+            syllable.style.animation = `${currentWipeAnimation} ${visualDuration}ms ${isGap ? 'ease-out' : 'linear'} forwards`;
         }
         // --- WRITE PHASE ---
         classList.remove('pre-highlight');
@@ -2831,7 +3019,7 @@ class AmLyrics extends i {
             }
         }
         if (running) {
-            this.animationFrameId = requestAnimationFrame(this.animateProgress.bind(this));
+            this.animationFrameId = requestAnimationFrame(this._boundAnimateProgress);
         }
         else if (this.animationFrameId) {
             // Stop animation if no words are running
@@ -3066,6 +3254,7 @@ class AmLyrics extends i {
                 // the result to each individual group so it renders through the
                 // single-syllable path (which supports char-level glow).
                 const groupGrowable = new Array(wordGroups.length).fill(false);
+                const groupGlowing = new Array(wordGroups.length).fill(false);
                 // Visual word info for growable char-level glow:
                 // Each group stores the combined visual word's text, duration, and
                 // the char offset of this group within the visual word.
@@ -3098,18 +3287,26 @@ class AmLyrics extends i {
                         const isCJK = /[\u4e00-\u9fff\u3040-\u309f\u30a0-\u30ff\uac00-\ud7af]/.test(combinedText);
                         const isRTL = /[\u0600-\u06FF\u0750-\u077F\u08A0-\u08FF\u0590-\u05FF]/.test(combinedText);
                         const hasHyphen = combinedText.includes('-');
-                        const isGrowableVW = !isCJK &&
-                            !isRTL &&
-                            !hasHyphen &&
-                            combinedText.length <= 7 &&
-                            combinedText.length > 0 &&
-                            combinedDuration >= 900 &&
-                            combinedDuration >= combinedText.length * 300 &&
-                            (combinedText.length >= 4 ||
-                                combinedDuration / combinedText.length >= 600);
+                        const wordLen = combinedText.length;
+                        let isGrowableVW = !isCJK && !isRTL && !hasHyphen && wordLen > 0 && wordLen <= 12;
+                        if (isGrowableVW) {
+                            if (wordLen < 3) {
+                                isGrowableVW =
+                                    combinedDuration >= 1110 && combinedDuration >= wordLen * 550;
+                            }
+                            else {
+                                isGrowableVW =
+                                    combinedDuration >= 800 && combinedDuration >= wordLen * 180;
+                            }
+                        }
+                        // Glow requirement (more strict)
+                        const isGlowingVW = isGrowableVW &&
+                            combinedDuration >= 1200 &&
+                            combinedDuration >= combinedText.length * 300;
                         let charOff = 0;
                         for (let gi = vwStart; gi <= vwEnd; gi += 1) {
                             groupGrowable[gi] = isGrowableVW;
+                            groupGlowing[gi] = isGlowingVW;
                             vwFullText[gi] = combinedText;
                             vwFullDuration[gi] = combinedDuration;
                             vwCharOffset[gi] = charOff;
@@ -3125,224 +3322,126 @@ class AmLyrics extends i {
                 const mainVocalElement = b `<p class="main-vocal-container">
           ${wordGroups.map((group, groupIdx) => {
                     const isGrowable = groupGrowable[groupIdx];
-                    // For growable visual words spanning multiple groups:
-                    // skip continuation groups (rendered by the first group)
-                    if (isGrowable && vwCharOffset[groupIdx] > 0) {
-                        return '';
-                    }
-                    // Check if ANY syllable in group is line-synced
+                    const isGlowing = groupGlowing[groupIdx];
                     const groupLineSynced = group.some(s => s.lineSynced);
-                    // For growable multi-group visual words, combine all text
-                    // into one syllable so the wipe + glow animates as one unit
-                    if (isGrowable && vwFullText[groupIdx].length > 0) {
-                        const wordText = vwFullText[groupIdx];
-                        const wordDuration = vwFullDuration[groupIdx];
-                        const startTimeMs = vwStartMs[groupIdx];
-                        const endTimeMs = vwEndMs[groupIdx];
-                        const numChars = wordText.length;
-                        // Collect all text from groups in this visual word
-                        // by scanning forward while vwCharOffset is consecutive
-                        let combinedRawText = '';
-                        for (let gi = groupIdx; gi < wordGroups.length; gi += 1) {
-                            if (gi > groupIdx && vwCharOffset[gi] === 0)
-                                break;
-                            if (gi > groupIdx && !groupGrowable[gi])
-                                break;
-                            combinedRawText += wordGroups[gi].map(s => s.text).join('');
-                        }
-                        const syllableContent = b `${combinedRawText
-                            .split('')
-                            .map((char, charIndex) => {
-                            if (char === ' ') {
-                                return ' ';
-                            }
-                            const charStartPercent = charIndex / numChars;
-                            const minDuration = 1000;
-                            const maxDuration = 5000;
-                            const easingPower = 3;
-                            const progress = Math.min(1, Math.max(0, (wordDuration - minDuration) /
-                                (maxDuration - minDuration)));
-                            const easedProgress = progress ** easingPower;
-                            const isLongWord = numChars > 5;
-                            const isShortDuration = wordDuration < 1500;
-                            let maxDecayRate = 0;
-                            if (isLongWord || isShortDuration) {
-                                let decayStrength = 0;
-                                if (isLongWord)
-                                    decayStrength += Math.min((numChars - 5) / 3, 1.0) * 0.4;
-                                if (isShortDuration)
-                                    decayStrength +=
-                                        Math.max(0, 1.0 - (wordDuration - 1000) / 500) * 0.4;
-                                maxDecayRate = Math.min(decayStrength, 0.85);
-                            }
-                            const positionInWord = numChars > 1 ? charIndex / (numChars - 1) : 0;
-                            const decayFactor = 1.0 - positionInWord * maxDecayRate;
-                            const charProgress = easedProgress * decayFactor;
-                            const baseGrowth = numChars <= 3 ? 0.07 : 0.05;
-                            const charMaxScale = 1.0 + baseGrowth + charProgress * 0.1;
-                            const charShadowIntensity = 0.4 + charProgress * 0.4;
-                            const normalizedGrowth = (charMaxScale - 1.0) / 0.13;
-                            const charTranslateYPeak = -normalizedGrowth * 6;
-                            const position = (charIndex + 0.5) / numChars;
-                            const horizontalOffset = (position - 0.5) * 2 * ((charMaxScale - 1.0) * 25);
-                            return b `<span
-                    class="char"
-                    data-char-index="${charIndex}"
-                    data-syllable-char-index="${charIndex}"
-                    data-wipe-start="${charStartPercent.toFixed(4)}"
-                    data-wipe-duration="${(1 / numChars).toFixed(4)}"
-                    data-horizontal-offset="${horizontalOffset.toFixed(2)}"
-                    data-max-scale="${charMaxScale.toFixed(3)}"
-                    data-shadow-intensity="${charShadowIntensity.toFixed(3)}"
-                    data-translate-y-peak="${charTranslateYPeak.toFixed(3)}"
-                    >${char}</span
-                  >`;
-                        })}`;
-                        return b `<span class="lyrics-word growable">
-                <span class="lyrics-syllable-wrap">
-                  <span
-                    class="lyrics-syllable ${groupLineSynced
-                            ? 'line-synced'
-                            : ''}"
-                    data-start-time="${startTimeMs}"
-                    data-end-time="${endTimeMs}"
-                    data-duration="${wordDuration}"
-                    data-syllable-index="0"
-                    data-wipe-ratio="1"
-                    >${syllableContent}</span
-                  >
-                </span>
-              </span>`;
-                    }
-                    // For single-syllable groups, use original logic
-                    if (group.length === 1) {
-                        const syllable = group[0];
+                    const wordText = isGrowable ? vwFullText[groupIdx] : '';
+                    const wordDuration = isGrowable ? vwFullDuration[groupIdx] : 0;
+                    const wordNumChars = wordText.length;
+                    const groupCharOffset = isGrowable ? vwCharOffset[groupIdx] : 0;
+                    let sylCharAccumulator = 0;
+                    return b `<span
+              class="lyrics-word ${isGrowable ? 'growable' : ''} ${isGlowing
+                        ? 'glowing'
+                        : ''} ${group.length > 1 ? 'allow-break' : ''}"
+            >
+              ${group.map((syllable, sylIdx) => {
                         const startTimeMs = syllable.timestamp;
                         const endTimeMs = syllable.endtime;
                         const durationMs = endTimeMs - startTimeMs;
                         const text = syllable.text || '';
-                        const trimmedText = text.trim();
-                        // Optional romanization per syllable (hide if same as the original text)
                         const romanizedText = this.showRomanization &&
                             syllable.romanizedText &&
                             syllable.romanizedText.trim() !== syllable.text.trim()
                             ? b `<span
-                      class="lyrics-syllable transliteration ${syllable.lineSynced
+                        class="lyrics-syllable transliteration ${groupLineSynced
                                 ? 'line-synced'
                                 : ''}"
-                      data-start-time="${startTimeMs}"
-                      data-end-time="${endTimeMs}"
-                      data-duration="${durationMs}"
-                      data-syllable-index="0"
-                      data-wipe-ratio="1"
-                      >${syllable.romanizedText}</span
-                    >`
+                        data-start-time="${startTimeMs}"
+                        data-end-time="${endTimeMs}"
+                        data-duration="${durationMs}"
+                        data-syllable-index="0"
+                        data-wipe-ratio="1"
+                        >${syllable.romanizedText}</span
+                      >`
                             : '';
-                        // For growable words (single-group visual word), use char glow
-                        const syllableContent = isGrowable
-                            ? b `${text.split('').map((char, charIndex) => {
-                                if (char === ' ') {
+                        let syllableContent = text;
+                        if (isGrowable) {
+                            let charIndexInsideSyllable = 0;
+                            const numCharsInSyllable = text.replace(/\s/g, '').length || 1;
+                            syllableContent = b `${text.split('').map(char => {
+                                if (char === ' ')
                                     return ' ';
-                                }
-                                const numChars = trimmedText.length;
-                                const charStartPercent = charIndex / text.length;
-                                const minDuration = 1000;
-                                const maxDuration = 5000;
+                                const charIndexInsideWord = groupCharOffset + sylCharAccumulator;
+                                const charStartPercentVal = charIndexInsideSyllable / numCharsInSyllable;
+                                sylCharAccumulator += 1;
+                                charIndexInsideSyllable += 1;
+                                const minDuration = 400;
+                                const maxDuration = 3000;
                                 const easingPower = 3;
-                                const progress = Math.min(1, Math.max(0, (durationMs - minDuration) /
+                                const progress = Math.min(1, Math.max(0, (wordDuration - minDuration) /
                                     (maxDuration - minDuration)));
                                 const easedProgress = progress ** easingPower;
-                                const isLongWord = numChars > 5;
-                                const isShortDuration = durationMs < 1500;
+                                const isLongWord = wordNumChars > 5;
+                                const isShortDuration = wordDuration < 1200;
                                 let maxDecayRate = 0;
                                 if (isLongWord || isShortDuration) {
                                     let decayStrength = 0;
                                     if (isLongWord)
                                         decayStrength +=
-                                            Math.min((numChars - 5) / 3, 1.0) * 0.4;
-                                    if (isShortDuration)
+                                            Math.min((wordNumChars - 5) / 5, 1.0) * 0.4;
+                                    if (isShortDuration && wordNumChars > 3)
+                                        decayStrength +=
+                                            Math.max(0, 1.0 - (wordDuration - 800) / 400) * 0.3;
+                                    else if (isShortDuration && wordNumChars <= 3)
                                         decayStrength +=
-                                            Math.max(0, 1.0 - (durationMs - 1000) / 500) * 0.4;
-                                    maxDecayRate = Math.min(decayStrength, 0.85);
+                                            Math.max(0, 1.0 - (wordDuration - 800) / 400) * 0.1;
+                                    maxDecayRate = Math.min(decayStrength, 0.7);
                                 }
-                                const positionInWord = numChars > 1 ? charIndex / (numChars - 1) : 0;
+                                const positionInWord = wordNumChars > 1
+                                    ? charIndexInsideWord / (wordNumChars - 1)
+                                    : 0;
                                 const decayFactor = 1.0 - positionInWord * maxDecayRate;
                                 const charProgress = easedProgress * decayFactor;
-                                const baseGrowth = numChars <= 3 ? 0.07 : 0.05;
-                                const charMaxScale = 1.0 + baseGrowth + charProgress * 0.1;
-                                const charShadowIntensity = 0.4 + charProgress * 0.4;
-                                const normalizedGrowth = (charMaxScale - 1.0) / 0.13;
-                                const charTranslateYPeak = -normalizedGrowth * 6;
-                                const position = (charIndex + 0.5) / numChars;
+                                const baseGrowth = wordNumChars <= 3 ? 0.05 : 0.04;
+                                const charMaxScale = 1.0 + baseGrowth + charProgress * 0.08;
+                                const glowDurFactor = Math.min(1.1, wordDuration / 1500);
+                                let glowLenFactor = 1.0;
+                                if (wordNumChars <= 3) {
+                                    glowLenFactor = 0.85;
+                                }
+                                else if (wordNumChars >= 6) {
+                                    glowLenFactor = 1.1;
+                                }
+                                const glowIntensityScale = glowDurFactor * glowLenFactor;
+                                const charShadowIntensity = isGlowing
+                                    ? (0.35 + charProgress * 0.45) * glowIntensityScale
+                                    : 0;
+                                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 position = (charIndexInsideWord + 0.5) / wordNumChars;
                                 const horizontalOffset = (position - 0.5) * 2 * ((charMaxScale - 1.0) * 25);
                                 return b `<span
                       class="char"
-                      data-char-index="${charIndex}"
-                      data-syllable-char-index="${charIndex}"
-                      data-wipe-start="${charStartPercent.toFixed(4)}"
-                      data-wipe-duration="${(1 / text.length).toFixed(4)}"
+                      data-char-index="${charIndexInsideWord}"
+                      data-syllable-char-index="${charIndexInsideWord}"
+                      data-wipe-start="${charStartPercentVal.toFixed(4)}"
+                      data-wipe-duration="${(1 / numCharsInSyllable).toFixed(4)}"
                       data-horizontal-offset="${horizontalOffset.toFixed(2)}"
                       data-max-scale="${charMaxScale.toFixed(3)}"
                       data-shadow-intensity="${charShadowIntensity.toFixed(3)}"
                       data-translate-y-peak="${charTranslateYPeak.toFixed(3)}"
                       >${char}</span
                     >`;
-                            })}`
-                            : text;
-                        return b `<span
-                class="lyrics-word ${isGrowable ? 'growable' : ''}"
-              >
-                <span class="lyrics-syllable-wrap">
+                            })}`;
+                        }
+                        return b `<span class="lyrics-syllable-wrap">
                   <span
-                    class="lyrics-syllable ${syllable.lineSynced
+                    class="lyrics-syllable ${groupLineSynced
                             ? 'line-synced'
                             : ''}"
                     data-start-time="${startTimeMs}"
                     data-end-time="${endTimeMs}"
                     data-duration="${durationMs}"
-                    data-syllable-index="0"
+                    data-word-duration="${wordDuration}"
+                    data-syllable-index="${sylIdx}"
                     data-wipe-ratio="1"
                     >${syllableContent}</span
                   >
                   ${romanizedText}
-                </span>
-              </span>`;
-                    }
-                    // Multi-syllable group (part=true): render all syllables inside one lyrics-word
-                    return b `<span
-              class="lyrics-word ${isGrowable ? 'growable' : ''} allow-break"
-            >
-              ${group.map((syllable, sylIdx) => b `
-                  <span class="lyrics-syllable-wrap">
-                    <span
-                      class="lyrics-syllable ${groupLineSynced
-                        ? 'line-synced'
-                        : ''}"
-                      data-start-time="${syllable.timestamp}"
-                      data-end-time="${syllable.endtime}"
-                      data-duration="${syllable.endtime - syllable.timestamp}"
-                      data-syllable-index="${sylIdx}"
-                      data-wipe-ratio="1"
-                      >${syllable.text}</span
-                    >
-                    ${this.showRomanization &&
-                        syllable.romanizedText &&
-                        syllable.romanizedText.trim() !== syllable.text.trim()
-                        ? b `<span
-                          class="lyrics-syllable transliteration ${groupLineSynced
-                            ? 'line-synced'
-                            : ''}"
-                          data-start-time="${syllable.timestamp}"
-                          data-end-time="${syllable.endtime}"
-                          data-duration="${syllable.endtime -
-                            syllable.timestamp}"
-                          data-syllable-index="0"
-                          data-wipe-ratio="1"
-                          >${syllable.romanizedText}</span
-                        >`
-                        : ''}
-                  </span>
-                `)}
+                </span>`;
+                    })}
             </span>`;
                 })}
         </p>`;
@@ -3373,14 +3472,17 @@ class AmLyrics extends i {
                 let maybeInstrumentalBlock = null;
                 const gapForLine = gapByIndex.get(lineIndex);
                 if (gapForLine) {
+                    const gapDuration = gapForLine.gapEnd - gapForLine.gapStart;
                     // Calculate dot timing for fill-up animation (3 dots)
-                    const dotDuration = (gapForLine.gapEnd - gapForLine.gapStart) / 3;
+                    const dotDuration = gapDuration / 3;
+                    const gapLoopDelay = AmLyrics.getGapLoopDelay(gapDuration);
                     // Gap starts without 'active' — _onTimeChanged toggles it imperatively
                     maybeInstrumentalBlock = b `<div
             id="gap-${lineIndex}"
             class="lyrics-line lyrics-gap"
             data-start-time="${gapForLine.gapStart}"
             data-end-time="${gapForLine.gapEnd}"
+            style="--gap-pulse-duration: ${GAP_PULSE_DURATION_MS}ms; --gap-loop-delay: -${gapLoopDelay}ms; --gap-exit-duration: ${GAP_EXIT_LEAD_MS}ms; --gap-exit-scale: ${GAP_MIN_SCALE};"
           >
             <div class="lyrics-line-container">
               <p class="main-vocal-container">
@@ -3703,7 +3805,7 @@ AmLyrics.styles = i$3 `
     .lyrics-line.scroll-animate {
       transition: none !important; /* Prevent conflict with scroll animation */
       animation-name: lyrics-scroll;
-      animation-duration: 400ms;
+      animation-duration: var(--scroll-duration, 280ms);
       animation-timing-function: cubic-bezier(0.41, 0, 0.12, 0.99);
       animation-fill-mode: both;
       animation-delay: var(--lyrics-line-delay, 0ms);
@@ -3775,19 +3877,20 @@ AmLyrics.styles = i$3 `
       opacity: 0;
       font-size: var(--lyplus-font-size-subtext);
       transition:
-        max-height 0.3s,
-        opacity 0.6s,
-        padding 0.6s;
+        max-height 350ms cubic-bezier(0.33, 1, 0.68, 1),
+        opacity 300ms ease-out,
+        padding 350ms cubic-bezier(0.33, 1, 0.68, 1);
       margin: 0;
     }
 
-    .lyrics-line.active .background-vocal-container {
+    .lyrics-line.active .background-vocal-container,
+    .lyrics-line.pre-active .background-vocal-container {
       max-height: 4em;
       opacity: 1;
       transition:
-        max-height 0.6s,
-        opacity 0.6s,
-        padding 0.6s;
+        max-height 350ms cubic-bezier(0.22, 1, 0.36, 1),
+        opacity 300ms ease-out,
+        padding 350ms cubic-bezier(0.22, 1, 0.36, 1);
       will-change: max-height, opacity, padding;
     }
 
@@ -3798,6 +3901,11 @@ AmLyrics.styles = i$3 `
       will-change: transform, opacity;
     }
 
+    .lyrics-line.pre-active {
+      opacity: 1;
+      will-change: transform, opacity;
+    }
+
     .lyrics-line.singer-right {
       text-align: end;
     }
@@ -3877,7 +3985,7 @@ AmLyrics.styles = i$3 `
     /* Unblur early for pre-active lines */
     .lyrics-container.blur-inactive-enabled .lyrics-line.pre-active {
       filter: blur(0px) !important;
-      opacity: var(--lyplus-primary-opacity);
+      opacity: 1;
     }
 
     /* ==========================================================================
@@ -4115,43 +4223,45 @@ AmLyrics.styles = i$3 `
        INSTRUMENTAL GAP STYLES
        ========================================================================== */
     .lyrics-gap {
-      height: 0;
+      max-height: 0;
       padding: 0 var(--lyplus-padding-gap);
       overflow: hidden;
       opacity: 0;
       box-sizing: content-box;
       background-clip: unset;
+      transform-origin: top;
       transition:
-        padding 0.3s 0.5s,
-        height 0.3s 0.5s,
-        opacity 0.2s 0.5s,
-        transform 0.3s var(--lyrics-line-delay, 0ms);
+        padding 220ms cubic-bezier(0.33, 1, 0.68, 1),
+        max-height 220ms cubic-bezier(0.33, 1, 0.68, 1),
+        opacity 160ms ease-out,
+        transform var(--scroll-duration, 280ms) var(--lyrics-line-delay, 0ms);
     }
 
     .lyrics-gap.active {
-      height: 1.3em;
+      max-height: 1.6em;
       padding: var(--lyplus-padding-gap);
       opacity: 1;
       overflow: visible;
       transition:
-        padding 0.3s,
-        height 0.3s,
-        opacity 0.2s 0.3s,
-        transform 0.3s;
-      will-change: height, opacity, padding;
+        padding 220ms cubic-bezier(0.22, 1, 0.36, 1),
+        max-height 220ms cubic-bezier(0.22, 1, 0.36, 1),
+        opacity 160ms ease-out,
+        transform var(--scroll-duration, 280ms);
+      will-change: max-height, opacity, padding;
     }
 
-    /* Exiting state: keep gap visible while dots animate out */
+    /* Exiting state: quickly collapse width and height so dots don't distort page, or remove max-height transition */
     .lyrics-gap.gap-exiting {
-      height: 1.3em;
-      padding: var(--lyplus-padding-gap);
-      opacity: 1;
+      max-height: 0;
+      padding: 0 var(--lyplus-padding-gap);
+      opacity: 0;
       overflow: visible;
       transition:
-        padding 0.3s 0.5s,
-        height 0.3s 0.5s,
-        opacity 0.2s 0.5s,
-        transform 0.3s;
+        padding var(--gap-exit-duration, 360ms) cubic-bezier(0.33, 1, 0.68, 1),
+        max-height var(--gap-exit-duration, 360ms)
+          cubic-bezier(0.33, 1, 0.68, 1),
+        opacity 160ms ease-out,
+        transform var(--scroll-duration, 280ms);
     }
 
     .lyrics-gap .main-vocal-container {
@@ -4160,7 +4270,8 @@ AmLyrics.styles = i$3 `
 
     /* Jump animation plays during exit */
     .lyrics-gap.gap-exiting .main-vocal-container {
-      animation: gap-ended 0.8s ease forwards;
+      animation: gap-ended var(--gap-exit-duration, 360ms)
+        cubic-bezier(0.33, 1, 0.68, 1) forwards;
     }
 
     .lyrics-gap:not(.active):not(.gap-exiting) .main-vocal-container {
@@ -4174,7 +4285,9 @@ AmLyrics.styles = i$3 `
     }
 
     .lyrics-gap.active .main-vocal-container .lyrics-word {
-      animation: gap-loop 4s ease infinite alternate;
+      animation: gap-loop var(--gap-pulse-duration, 4000ms) ease-in-out infinite
+        alternate;
+      animation-delay: var(--gap-loop-delay, 0ms);
       will-change: transform;
     }
 
@@ -4198,6 +4311,18 @@ AmLyrics.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 {
+      background-image: none !important;
+      background-color: var(--lyplus-text-primary) !important;
+      transition: background-color 120ms ease-out !important;
+    }
+
     @keyframes fade-in-line {
       from {
         opacity: 0.5;
@@ -4611,19 +4736,20 @@ AmLyrics.styles = i$3 `
     /* Gap dot animations */
     @keyframes gap-loop {
       from {
-        transform: scale(1.15);
+        transform: scale(1.12);
       }
       to {
-        transform: scale(0.85);
+        transform: scale(var(--gap-exit-scale, 0.85));
       }
     }
 
     @keyframes gap-ended {
       0% {
-        transform: translateY(-25%) scale(1) translateZ(0);
+        transform: translateY(-25%) scale(var(--gap-exit-scale, 0.85))
+          translateZ(0);
       }
       35% {
-        transform: translateY(-25%) scale(1.2) translateZ(0);
+        transform: translateY(-5%) scale(1.08) translateZ(0);
       }
       100% {
         transform: translateY(-25%) scale(0) translateZ(0);