@braccato/core 1.4.0 → 1.6.0

package/README.md

@@ -186,6 +186,33 @@ frequency. Both must use the same commands in the same order with the same numbe
 browser only interpolates two paths smoothly when their command sequences match, and a mismatched
 pair snaps at the halfway point instead of flowing.
 
+### Letter wave (experimental)
+
+On by default; a theme opts out with `/* blyrics-letter-wave = false; */`. It splits every word into
+per-letter spans and, as the word is sung, floats each letter up and eases it most of the way back on
+a small stagger, so a wave travels through the word. It layers on top of the word wobble rather than
+replacing it: the word keeps whatever `--blyrics-word-wobble-*` does and the letters ride on top, so
+it composes with the default `scaleX` pop and reduces to just the letters when a theme sets its wobble
+to identity. It follows `--blyrics-animate-word-wobble`, so reduced motion turns it off with the rest.
+
+A word held past `blyrics-long-word-threshold` (the same `data-long-word` the glow keys off) also
+swells each letter with a transient scale at the crest.
+
+```css
+.blyrics-container {
+  --blyrics-letter-wave-transform: translateY(-0.05em); /* crest lift */
+  --blyrics-letter-wave-settle: translateY(-0.02em); /* rest the crest eases back to */
+  --blyrics-letter-wave-emphasis-scale: 1.11; /* long-word letter swell, 1 turns it off */
+  --blyrics-letter-wave-duration: 0.9s;
+  --blyrics-letter-wave-rise-easing: ease-in-out;
+  --blyrics-letter-wave-fall-easing: ease-out;
+}
+```
+
+The split multiplies the DOM per character and reruns the karaoke sweep per letter, so a theme that
+does not want the cost turns it off with `/* blyrics-letter-wave = false; */`. `blyrics-letter-wave`
+reloads the lines when it changes, the way every build-time setting does.
+
 ### Class names
 
 These are published API rather than implementation. Renaming one costs a migration rather than a

package/dist/README.md

@@ -186,6 +186,33 @@ frequency. Both must use the same commands in the same order with the same numbe
 browser only interpolates two paths smoothly when their command sequences match, and a mismatched
 pair snaps at the halfway point instead of flowing.
 
+### Letter wave (experimental)
+
+On by default; a theme opts out with `/* blyrics-letter-wave = false; */`. It splits every word into
+per-letter spans and, as the word is sung, floats each letter up and eases it most of the way back on
+a small stagger, so a wave travels through the word. It layers on top of the word wobble rather than
+replacing it: the word keeps whatever `--blyrics-word-wobble-*` does and the letters ride on top, so
+it composes with the default `scaleX` pop and reduces to just the letters when a theme sets its wobble
+to identity. It follows `--blyrics-animate-word-wobble`, so reduced motion turns it off with the rest.
+
+A word held past `blyrics-long-word-threshold` (the same `data-long-word` the glow keys off) also
+swells each letter with a transient scale at the crest.
+
+```css
+.blyrics-container {
+  --blyrics-letter-wave-transform: translateY(-0.05em); /* crest lift */
+  --blyrics-letter-wave-settle: translateY(-0.02em); /* rest the crest eases back to */
+  --blyrics-letter-wave-emphasis-scale: 1.11; /* long-word letter swell, 1 turns it off */
+  --blyrics-letter-wave-duration: 0.9s;
+  --blyrics-letter-wave-rise-easing: ease-in-out;
+  --blyrics-letter-wave-fall-easing: ease-out;
+}
+```
+
+The split multiplies the DOM per character and reruns the karaoke sweep per letter, so a theme that
+does not want the cost turns it off with `/* blyrics-letter-wave = false; */`. `blyrics-letter-wave`
+reloads the lines when it changes, the way every build-time setting does.
+
 ### Class names
 
 These are published API rather than implementation. Renaming one costs a migration rather than a

package/dist/constants.d.ts

@@ -2,6 +2,7 @@ export declare const LYRICS_WRAPPER_ID: "blyrics-wrapper";
 export declare const LYRICS_CLASS: "blyrics-container";
 export declare const LINE_CLASS: "blyrics--line";
 export declare const WORD_CLASS: "blyrics--word";
+export declare const LETTER_CLASS: "blyrics--letter";
 export declare const FOOTER_CLASS: "blyrics-footer";
 export declare const CURRENT_LYRICS_CLASS: "blyrics--active";
 export declare const ANIMATING_CLASS: "blyrics--animating";

package/dist/constants.js

@@ -5,6 +5,7 @@ export const LYRICS_WRAPPER_ID = "blyrics-wrapper";
 export const LYRICS_CLASS = "blyrics-container";
 export const LINE_CLASS = "blyrics--line";
 export const WORD_CLASS = "blyrics--word";
+export const LETTER_CLASS = "blyrics--letter";
 export const FOOTER_CLASS = "blyrics-footer";
 // -- Playback state --------------------------------------------
 export const CURRENT_LYRICS_CLASS = "blyrics--active";

package/dist/engine.d.ts

@@ -41,6 +41,10 @@ export interface AnimationEngineInstance extends AnimEngineViewState {
     window: EngineWindow;
     host: LyricsRendererHost;
     cachedTabRendererHeight: number | null;
+    cachedMaxScrollTop: number | null;
+    cachedScrollTop: number | null;
+    cachedFooterItem: LineScrollItem | null;
+    cachedLineScrollTiming: Map<string, LineScrollTiming>;
     tabRendererResizeObserver: ResizeObserver | null;
     observedTabRenderer: HTMLElement | null;
     lineScrollAnimations: LineScrollAnimationRecord[];
@@ -48,6 +52,9 @@ export interface AnimationEngineInstance extends AnimEngineViewState {
     pendingLineScroll: PendingLineScroll | null;
     lineScrollElementTokens: WeakMap<HTMLElement, number>;
     visibleWillChangeElements: Set<HTMLElement>;
+    culledLineElements: Set<HTMLElement>;
+    waveAnimationPool: Animation[];
+    lineCullObserver: IntersectionObserver | null;
     cachedDurations: Map<string, number>;
     cachedCSSValues: Map<string, string>;
     cachedAnimationSettings: AnimationSettings | null;
@@ -123,6 +130,11 @@ export declare function getRenderedSyncType(engine: AnimationEngineInstance): Ly
  */
 export declare function clearLyrics(engine: AnimationEngineInstance): void;
 type LineScrollSide = "above" | "active" | "below";
+interface LineScrollItem {
+    lyricElement: HTMLElement;
+    height: number;
+    position: number;
+}
 interface LineScrollAnimationRecord {
     animation: Animation;
     lineElement: HTMLElement;
@@ -162,6 +174,8 @@ interface AnimationConfig {
         glowDurationRatio: number;
         glowMinDurationMs: number;
         glowEasing: string;
+        glowContainerAlpha: number;
+        glowRestingInvisible: boolean;
     };
     word: {
         wobbleDurationMs: number;
@@ -175,6 +189,14 @@ interface AnimationConfig {
         wobblePeakOffset: number;
         wobbleSettleOffset: number;
     };
+    letterWave: {
+        transform: string;
+        settle: string;
+        emphasisScale: string;
+        durationMs: number;
+        riseEasing: string;
+        fallEasing: string;
+    };
     instrumental: {
         fillFadeDurationMs: number;
         fillFadeEasing: string;
@@ -207,7 +229,39 @@ interface AnimationSettings {
     };
 }
 export declare function noteVisibilityChange(engine: AnimationEngineInstance): void;
+export interface LetterSwipeWindow {
+    delayMs: number;
+    durationMs: number;
+    from: {
+        start: number;
+        end: number;
+    };
+    to: {
+        start: number;
+        end: number;
+    };
+}
+export interface SwipeRamp {
+    easing: string;
+    startFrom: string;
+    startTo: string;
+    endFrom: string;
+    endTo: string;
+}
+export declare function computeLetterSwipeWindows(swipe: SwipeRamp, letterCount: number, swipeDurationMs: number): LetterSwipeWindow[] | null;
+export interface LetterMaskKeyframe {
+    offset: number;
+    maskPosition: string;
+}
+export interface LetterMaskSweep {
+    keyframes: LetterMaskKeyframe[];
+    delayMs: number;
+    durationMs: number;
+    easing: string;
+}
+export declare function planLetterMaskSweep(swipe: SwipeRamp, letterCount: number, swipeDurationMs: number, rtl: boolean): LetterMaskSweep[];
 export declare function clearStyleCaches(engine: AnimationEngineInstance): void;
+export declare function parseColorAlpha(value: string): number | null;
 interface PreparedLineScroll {
     lineElement: HTMLElement;
     side: LineScrollSide;
@@ -220,6 +274,11 @@ interface ResolvedLineScroll extends PreparedLineScroll {
     startTranslate: string;
     endTranslate: string;
 }
+interface LineScrollTiming {
+    durationMs: number;
+    startEasing: string;
+    endEasing: string;
+}
 interface LineScrollPlan {
     items: ResolvedLineScroll[];
 }
@@ -229,6 +288,7 @@ interface PendingLineScroll {
     fromScrollTop: number;
     toScrollTop: number;
 }
+export declare function setupLineCullObserver(engine: AnimationEngineInstance): void;
 /**
  * Unsynced lyrics that this view still has on screen. `syncType` outlives the lyrics it was derived
  * from, so the container is the term that says they are still there.

package/dist/engine.js

@@ -16,7 +16,7 @@
 // playback clock the last tick wrote. Their unit is a bundle rather than a document, and this
 // module is bundled into the isolated world and the page world separately, so those are two clocks
 // that never meet. `themeSettings.ts` holds the third thing under that rule.
-import { ANIMATING_CLASS, CURRENT_LYRICS_CLASS, FOOTER_CLASS, LINE_CLASS, PAUSED_CLASS, ROMANIZED_LYRICS_CLASS, TRANSLATED_LYRICS_CLASS, USER_SCROLLING_CLASS, } from "./constants.js";
+import { ANIMATING_CLASS, CURRENT_LYRICS_CLASS, FOOTER_CLASS, LINE_CLASS, PAUSED_CLASS, ROMANIZED_LYRICS_CLASS, RTL_CLASS, TRANSLATED_LYRICS_CLASS, USER_SCROLLING_CLASS, } from "./constants.js";
 import { INSTRUMENTAL_WAVE_PATH_HIGH, INSTRUMENTAL_WAVE_PATH_LOW } from "./instrumental.js";
 import { registerThemeSetting } from "./themeSettings.js";
 import { clamp, getRelativeLayoutBounds, positiveModulo, roundedMs, toMs } from "./util.js";
@@ -78,6 +78,8 @@ const LINE_SCROLL_STYLE_SETTINGS = [
     registerLineScrollStyleSetting("--blyrics-line-scroll-active-translate-y-end", ""),
     registerLineScrollStyleSetting("--blyrics-line-scroll-below-translate-y-end", ""),
 ];
+// Tracked so the tick can skip the per-line translate write-then-read unless a theme overrides it.
+const LINE_SCROLL_TRANSLATE_SETTINGS = LINE_SCROLL_STYLE_SETTINGS.filter(([property]) => property.includes("translate-y")).map(([, setting]) => setting);
 const animationTimingLastLogTimes = new WeakMap();
 // 0.5 means the selected lyric will be in the middle of the screen, 0 means top, 1 means bottom
 const SCROLL_POS_OFFSET_RATIO = registerThemeSetting("blyrics-target-scroll-pos-ratio", 0.37);
@@ -135,6 +137,10 @@ export function createAnimationEngineInstance(engineDocument, engineWindow, host
         passiveScrollAccumulatedTime: 0,
         passiveLastWallTime: 0,
         cachedTabRendererHeight: null,
+        cachedMaxScrollTop: null,
+        cachedScrollTop: null,
+        cachedFooterItem: null,
+        cachedLineScrollTiming: new Map(),
         tabRendererResizeObserver: null,
         observedTabRenderer: null,
         lineScrollAnimations: [],
@@ -142,6 +148,9 @@ export function createAnimationEngineInstance(engineDocument, engineWindow, host
         pendingLineScroll: null,
         lineScrollElementTokens: new WeakMap(),
         visibleWillChangeElements: new Set(),
+        culledLineElements: new Set(),
+        waveAnimationPool: [],
+        lineCullObserver: null,
         cachedDurations: new Map(),
         cachedCSSValues: new Map(),
         cachedAnimationSettings: null,
@@ -157,6 +166,8 @@ export function createAnimationEngineInstance(engineDocument, engineWindow, host
             engine.tabRendererResizeObserver?.disconnect();
             engine.tabRendererResizeObserver = null;
             engine.observedTabRenderer = null;
+            engine.lineCullObserver?.disconnect();
+            engine.lineCullObserver = null;
             stopPassiveScrollLoop(engine);
             cancelLyricPositionUpdate(engine);
         },
@@ -265,6 +276,9 @@ export function clearLyrics(engine) {
     dropPendingLineScroll(engine);
     clearLineScrollAnimations(engine);
     clearVisibleLyricWillChange(engine);
+    engine.lineCullObserver?.disconnect();
+    engine.lineCullObserver = null;
+    clearOffscreenLineCulling(engine);
     for (const line of engine.lines) {
         resetLineAnimationState(line);
         line.isSelected = false;
@@ -278,11 +292,16 @@ export function clearLyrics(engine) {
     engine.passiveLastWallTime = 0;
     stopPassiveScrollLoop(engine);
     engine.lines = [];
+    engine.cachedFooterItem = null;
     engine.lyricsContainer = null;
+    engine.waveAnimationPool.length = 0;
 }
 function resetPartAnimations(part) {
     for (const animation of part.animations) {
         animation.cancel();
+        const pool = pooledWaveAnimations.get(animation);
+        if (pool)
+            pool.push(animation);
     }
     part.animations = [];
 }
@@ -363,6 +382,30 @@ function trackLyricAnimationTiming(engine, animation, timing) {
     animation.playbackRate = engine.playbackRate;
     return animation;
 }
+// Finished per-letter wave animations are pooled and retargeted onto new letters, since recreating
+// ~150 identical ones per line activation is pure churn.
+const pooledWaveAnimations = new WeakMap();
+const pooledWaveKeyframeSignatures = new WeakMap();
+function acquireWaveAnimation(engine, letterElement, keyframes, keyframeSignature, timing) {
+    const pool = engine.waveAnimationPool;
+    const pooled = pool[pool.length - 1];
+    const effect = pooled?.effect;
+    if (pooled && effect && typeof effect.setKeyframes === "function") {
+        pool.pop();
+        effect.target = letterElement;
+        if (pooledWaveKeyframeSignatures.get(pooled) !== keyframeSignature) {
+            effect.setKeyframes(keyframes);
+            pooledWaveKeyframeSignatures.set(pooled, keyframeSignature);
+        }
+        effect.updateTiming(timing);
+        pooled.play();
+        return pooled;
+    }
+    const animation = letterElement.animate(keyframes, timing);
+    pooledWaveAnimations.set(animation, pool);
+    pooledWaveKeyframeSignatures.set(animation, keyframeSignature);
+    return animation;
+}
 /**
  * Puts the animations already running onto a new rate. Setting `playbackRate` keeps `currentTime`,
  * so each one carries on from where the song left it rather than restarting.
@@ -645,18 +688,114 @@ function fadeOutTextKeyframes(config) {
         },
     ];
 }
+// null unless the ramp is linear and forward; planLetterMaskSweep sweeps the whole word instead there.
+export function computeLetterSwipeWindows(swipe, letterCount, swipeDurationMs) {
+    if (swipe.easing !== "linear" || swipeDurationMs <= 0 || letterCount <= 0) {
+        return null;
+    }
+    const startFrom = Number.parseFloat(swipe.startFrom);
+    const startTo = Number.parseFloat(swipe.startTo);
+    const endFrom = Number.parseFloat(swipe.endFrom);
+    const endTo = Number.parseFloat(swipe.endTo);
+    if (![startFrom, startTo, endFrom, endTo].every(Number.isFinite) || startTo <= startFrom || endTo <= endFrom) {
+        return null;
+    }
+    const startAt = (timeMs) => startFrom + ((startTo - startFrom) * timeMs) / swipeDurationMs;
+    const endAt = (timeMs) => endFrom + ((endTo - endFrom) * timeMs) / swipeDurationMs;
+    const timeWhereEnd = (value) => (swipeDurationMs * (value - endFrom)) / (endTo - endFrom);
+    const timeWhereStart = (value) => (swipeDurationMs * (value - startFrom)) / (startTo - startFrom);
+    const windows = [];
+    for (let index = 0; index < letterCount; index++) {
+        const beginMs = clamp(timeWhereEnd(index / letterCount), 0, swipeDurationMs);
+        const finishMs = clamp(timeWhereStart((index + 1) / letterCount), 0, swipeDurationMs);
+        windows.push({
+            delayMs: beginMs,
+            durationMs: Math.max(finishMs - beginMs, 1),
+            from: { start: startAt(beginMs), end: endAt(beginMs) },
+            to: { start: startAt(finishMs), end: endAt(finishMs) },
+        });
+    }
+    return windows;
+}
+// Per-letter mask reveal. A linear forward ramp keeps the short windowed animations so a settled letter
+// holds a finished one; any other easing runs the same geometry over the whole duration, letting the
+// theme easing warp when each letter reveals, so it ends revealed rather than swept past.
+export function planLetterMaskSweep(swipe, letterCount, swipeDurationMs, rtl) {
+    if (letterCount <= 0)
+        return [];
+    const windows = computeLetterSwipeWindows({ ...swipe, easing: "linear" }, letterCount, swipeDurationMs);
+    if (!windows)
+        return [];
+    const maskSpan = letterCount + 2;
+    const maskPositionAt = (start, index) => {
+        const q = (0.5 * maskSpan - (start * letterCount - index)) / (maskSpan - 1);
+        return `${(rtl ? 1 - q : q) * 100}% 0%`;
+    };
+    const linear = swipe.easing === "linear";
+    const durationMs = swipeDurationMs > 0 ? swipeDurationMs : 1;
+    return windows.map((window, index) => {
+        const from = maskPositionAt(window.from.start, index);
+        const to = maskPositionAt(window.to.start, index);
+        if (linear) {
+            return {
+                keyframes: [
+                    { offset: 0, maskPosition: from },
+                    { offset: 1, maskPosition: to },
+                ],
+                delayMs: window.delayMs,
+                durationMs: window.durationMs,
+                easing: "linear",
+            };
+        }
+        const revealStart = clamp(window.delayMs / durationMs, 0, 1);
+        const revealEnd = clamp((window.delayMs + window.durationMs) / durationMs, 0, 1);
+        const keyframes = [{ offset: 0, maskPosition: from }];
+        if (revealStart > 0)
+            keyframes.push({ offset: revealStart, maskPosition: from });
+        if (revealEnd > revealStart)
+            keyframes.push({ offset: revealEnd, maskPosition: to });
+        if (revealEnd < 1)
+            keyframes.push({ offset: 1, maskPosition: to });
+        return { keyframes, delayMs: 0, durationMs, easing: swipe.easing };
+    });
+}
 function startRichSyncedHighlightAnimations(engine, part, config, swipeTimeMs, wordTimeMs, swipeDurationMs, glowDurationMs, appliedTimingOffsetMs) {
     const animations = [];
     const highlight = part.highlightElement;
     let swipeAnimation;
     if (config.enabled.highlightSwipe) {
-        swipeAnimation = trackLyricAnimationTiming(engine, highlight.animate(activeTextGradientKeyframes(config), {
-            duration: swipeDurationMs,
-            easing: config.highlight.swipeEasing,
-            fill: "forwards",
-        }), { appliedTimingOffsetMs, offsetMs: swipeTimeMs - wordTimeMs });
-        swipeAnimation.currentTime = correctedAnimationTimeMs(swipeTimeMs, appliedTimingOffsetMs, swipeDurationMs);
-        animations.push(swipeAnimation);
+        const swipeTiming = { appliedTimingOffsetMs, offsetMs: swipeTimeMs - wordTimeMs };
+        const swipeCurrentTimeMs = correctedAnimationTimeMs(swipeTimeMs, appliedTimingOffsetMs, swipeDurationMs);
+        const highlightLetters = part.highlightLetterElements;
+        if (highlightLetters && highlightLetters.length > 0) {
+            const sweeps = planLetterMaskSweep({
+                easing: config.highlight.swipeEasing,
+                startFrom: config.highlight.swipeStartFrom,
+                startTo: config.highlight.swipeStartTo,
+                endFrom: config.highlight.swipeEndFrom,
+                endTo: config.highlight.swipeEndTo,
+            }, highlightLetters.length, swipeDurationMs, part.highlightElement.classList.contains(RTL_CLASS));
+            sweeps.forEach((sweep, index) => {
+                const animation = trackLyricAnimationTiming(engine, highlightLetters[index].animate(sweep.keyframes.map(frame => ({
+                    offset: frame.offset,
+                    maskPosition: frame.maskPosition,
+                    WebkitMaskPosition: frame.maskPosition,
+                })), { duration: sweep.durationMs, delay: sweep.delayMs, easing: sweep.easing, fill: "both" }), swipeTiming);
+                animation.currentTime = swipeCurrentTimeMs;
+                if (index === 0)
+                    swipeAnimation = animation;
+                animations.push(animation);
+            });
+        }
+        else {
+            swipeAnimation = trackLyricAnimationTiming(engine, highlight.animate(activeTextGradientKeyframes(config), {
+                duration: swipeDurationMs,
+                easing: config.highlight.swipeEasing,
+                fill: "forwards",
+            }), swipeTiming);
+            swipeAnimation.currentTime = swipeCurrentTimeMs;
+            animations.push(swipeAnimation);
+        }
     }
     const opacityAnimation = trackLyricAnimationTiming(engine, highlight.animate(config.enabled.highlightSwipe ? activeTextVisibleKeyframes() : activeTextInstantKeyframes(config), {
         duration: 1,
@@ -666,11 +805,11 @@ function startRichSyncedHighlightAnimations(engine, part, config, swipeTimeMs, w
     opacityAnimation.currentTime = correctedAnimationTimeMs(wordTimeMs, appliedTimingOffsetMs, 1);
     animations.push(opacityAnimation);
     let glowAnimation;
-    if (config.enabled.highlightGlow) {
+    if (config.enabled.highlightGlow && !part.glowSuppressed) {
         glowAnimation = trackLyricAnimationTiming(engine, highlight.animate(activeTextGlowKeyframes(config), {
             duration: glowDurationMs,
             easing: config.highlight.glowEasing,
-            fill: "forwards",
+            fill: config.highlight.glowRestingInvisible ? "none" : "forwards",
         }), { appliedTimingOffsetMs, offsetMs: 0 });
         glowAnimation.currentTime = correctedAnimationTimeMs(wordTimeMs, appliedTimingOffsetMs, glowDurationMs);
         animations.push(glowAnimation);
@@ -689,11 +828,11 @@ function startLineSyncedHighlightAnimations(engine, part, config, wordTimeMs, gl
     opacityAnimation.currentTime = correctedAnimationTimeMs(wordTimeMs, appliedTimingOffsetMs, fadeInDuration);
     animations.push(opacityAnimation);
     let glowAnimation;
-    if (config.enabled.highlightGlow) {
+    if (config.enabled.highlightGlow && !part.glowSuppressed) {
         glowAnimation = trackLyricAnimationTiming(engine, highlight.animate(activeTextGlowKeyframes(config), {
             duration: glowDurationMs,
             easing: config.highlight.glowEasing,
-            fill: "forwards",
+            fill: config.highlight.glowRestingInvisible ? "none" : "forwards",
         }), { appliedTimingOffsetMs, offsetMs: 0 });
         glowAnimation.currentTime = correctedAnimationTimeMs(wordTimeMs, appliedTimingOffsetMs, glowDurationMs);
         animations.push(glowAnimation);
@@ -755,9 +894,6 @@ function startWordAnimations(engine, part, config, currentTime, appliedTimingOff
                 offset: config.word.wobblePeakOffset,
                 easing: config.word.wobblePeakEasing,
             },
-            // The two offsets are read and clamped independently, so a theme is free to settle
-            // before it peaks. animate() rejects offsets that go backwards, and that throw would
-            // orphan the highlight animations above, which are not tracked until the end.
             {
                 transform: config.word.wobbleSettle,
                 offset: Math.max(config.word.wobblePeakOffset, config.word.wobbleSettleOffset),
@@ -770,8 +906,6 @@ function startWordAnimations(engine, part, config, currentTime, appliedTimingOff
             fill: "forwards",
         };
         const wobbleStartMs = correctedAnimationTimeMs(wordTimeMs, appliedTimingOffsetMs, config.word.wobbleDurationMs);
-        // The wobble is a paint transform, so the highlight copy must carry it too or the active
-        // sweep drifts off the word.
         for (const wordElement of [part.lyricElement, part.highlightElement]) {
             const animation = trackLyricAnimationTiming(engine, wordElement.animate(wobbleKeyframes, wobbleOptions), {
                 appliedTimingOffsetMs,
@@ -780,6 +914,37 @@ function startWordAnimations(engine, part, config, currentTime, appliedTimingOff
             animation.currentTime = wobbleStartMs;
             wobbleAnimations.push(animation);
         }
+        const letters = part.letterElements;
+        if (letters && letters.length > 0) {
+            const emphasise = part.lyricElement?.dataset.longWord === "true";
+            const emphasisPeak = emphasise ? ` scale(${config.letterWave.emphasisScale})` : "";
+            const emphasisRest = emphasise ? " scale(1)" : "";
+            const floatKeyframes = [
+                { transform: `translateY(0)${emphasisRest}`, easing: config.letterWave.riseEasing },
+                {
+                    transform: `${config.letterWave.transform}${emphasisPeak}`,
+                    offset: 0.4,
+                    easing: config.letterWave.fallEasing,
+                },
+                { transform: `${config.letterWave.settle}${emphasisRest}` },
+            ];
+            const letterCount = letters.length;
+            const staggerMs = timedDurationMs > 0 ? timedDurationMs / 2.5 / letterCount : 0;
+            const cascadeDurationMs = config.letterWave.durationMs + (letterCount - 1) * staggerMs;
+            const floatStartMs = correctedAnimationTimeMs(wordTimeMs, appliedTimingOffsetMs, cascadeDurationMs);
+            const floatKeyframeSignature = JSON.stringify(floatKeyframes);
+            for (const set of [part.letterElements, part.highlightLetterElements]) {
+                set?.forEach((letterElement, index) => {
+                    const animation = trackLyricAnimationTiming(engine, acquireWaveAnimation(engine, letterElement, floatKeyframes, floatKeyframeSignature, {
+                        duration: config.letterWave.durationMs,
+                        delay: index * staggerMs,
+                        fill: "forwards",
+                    }), { appliedTimingOffsetMs, offsetMs: 0 });
+                    animation.currentTime = floatStartMs;
+                    wobbleAnimations.push(animation);
+                });
+            }
+        }
     }
     part.animations = [...highlightAnimations.animations, ...wobbleAnimations];
 }
@@ -790,6 +955,7 @@ function startLineAnimations(engine, lineData, config, currentTime) {
         startInstrumentalAnimations(engine, lineData, config, currentTime, appliedTimingOffsetMs);
         return;
     }
+    resolveLineGlowSuppression(engine, lineData, config);
     for (const part of lineData.parts) {
         startWordAnimations(engine, part, config, currentTime, appliedTimingOffsetMs);
     }
@@ -896,6 +1062,7 @@ export function clearStyleCaches(engine) {
     engine.cachedDurations.clear();
     engine.cachedCSSValues.clear();
     engine.cachedAnimationSettings = null;
+    engine.cachedLineScrollTiming.clear();
 }
 function getCSSValue(engine, lyricsElement, property, fallback) {
     let value = engine.cachedCSSValues.get(property);
@@ -949,6 +1116,52 @@ function getCSSOffset(engine, lyricsElement, property, fallback) {
 // the color left as a literal var lets the Web Animations API resolve it against each animated
 // word instead. A theme that sets the full filter var still wins, but its color resolves once
 // at the container (globally), as before.
+// A glow whose resolved color falls below half a quantization step stays invisible even after the
+// blur spreads it, so the per-frame drop-shadow can be skipped with no pixel changing.
+const GLOW_INVISIBLE_ALPHA = 0.5 / 255;
+function alphaToken(token) {
+    const value = token.endsWith("%") ? Number.parseFloat(token) / 100 : Number.parseFloat(token);
+    return clamp(value, 0, 1);
+}
+// null for an unrecognized format, which the caller treats as opaque so a visible glow is never dropped.
+export function parseColorAlpha(value) {
+    const color = value.trim().toLowerCase();
+    if (color === "")
+        return null;
+    if (color === "transparent")
+        return 0;
+    const slashAlpha = color.match(/\/\s*([0-9]*\.?[0-9]+%?)\s*\)\s*$/);
+    if (slashAlpha)
+        return alphaToken(slashAlpha[1]);
+    const commaAlpha = color.match(/^(?:rgba|hsla)\([^)]*,\s*([0-9]*\.?[0-9]+%?)\s*\)$/);
+    if (commaAlpha)
+        return alphaToken(commaAlpha[1]);
+    const hex = color.match(/^#([0-9a-f]{4}|[0-9a-f]{8})$/);
+    if (hex) {
+        const digits = hex[1];
+        const alphaHex = digits.length === 8 ? digits.slice(6) : digits.slice(3).repeat(2);
+        return Number.parseInt(alphaHex, 16) / 255;
+    }
+    const opaqueFunction = /^(?:rgb|hsl|hwb|lab|lch|oklab|oklch|color)\(/.test(color);
+    const opaqueHex = /^#(?:[0-9a-f]{3}|[0-9a-f]{6})$/.test(color);
+    const namedColor = /^[a-z]+$/.test(color);
+    if (opaqueFunction || opaqueHex || namedColor)
+        return 1;
+    return null;
+}
+// Per-word glow is resolved only when the container glow already renders nothing, so an empty word
+// drops its blur while a word a theme lit up keeps it.
+function resolveLineGlowSuppression(engine, lineData, config) {
+    if (config.highlight.glowContainerAlpha >= GLOW_INVISIBLE_ALPHA) {
+        for (const part of lineData.parts)
+            part.glowSuppressed = false;
+        return;
+    }
+    for (const part of lineData.parts) {
+        const color = engine.window.getComputedStyle(part.highlightElement).getPropertyValue("--blyrics-glow-color");
+        part.glowSuppressed = (parseColorAlpha(color) ?? 1) < GLOW_INVISIBLE_ALPHA;
+    }
+}
 function resolveGlowFilter(engine, lyricsElement, suffix, radiusDefault) {
     const override = getCSSValue(engine, lyricsElement, `--blyrics-highlight-glow-filter-${suffix}`, "");
     if (override)
@@ -956,6 +1169,15 @@ function resolveGlowFilter(engine, lyricsElement, suffix, radiusDefault) {
     const radius = getCSSValue(engine, lyricsElement, `--blyrics-highlight-glow-radius-${suffix}`, radiusDefault);
     return `drop-shadow(0 0 ${radius} var(--blyrics-glow-color))`;
 }
+// Only the engine's own drop-shadow(0 0 <radius> ...) resting shape counts, so a theme override or a
+// non-zero radius keeps its permanent glow on fill:forwards.
+function isGlowRestingInvisible(glowTo) {
+    const value = glowTo.trim();
+    if (value === "" || value === "none")
+        return true;
+    const match = value.match(/^drop-shadow\(\s*0\s+0\s+(\S+)\s+var\(--blyrics-glow-color\)\)$/);
+    return match ? Number.parseFloat(match[1]) === 0 : false;
+}
 function readAnimationConfig(engine, lyricsElement) {
     const prefersReducedMotion = engine.window.matchMedia(REDUCED_MOTION_QUERY).matches;
     const scrollDurationMs = getCSSDurationWithFallback(engine, lyricsElement, "--blyrics-lyric-scroll-duration", "650ms");
@@ -994,6 +1216,8 @@ function readAnimationConfig(engine, lyricsElement) {
             glowDurationRatio: getCSSNumber(engine, lyricsElement, "--blyrics-highlight-glow-duration-ratio", 1.2),
             glowMinDurationMs: getCSSDurationWithFallback(engine, lyricsElement, "--blyrics-highlight-glow-min-duration", "1.2s"),
             glowEasing: getCSSValue(engine, lyricsElement, "--blyrics-highlight-glow-easing", "ease"),
+            glowContainerAlpha: parseColorAlpha(getCSSValue(engine, lyricsElement, "--blyrics-glow-color", "")) ?? 1,
+            glowRestingInvisible: isGlowRestingInvisible(resolveGlowFilter(engine, lyricsElement, "to", "0")),
         },
         word: {
             wobbleDurationMs: getCSSDurationWithFallback(engine, lyricsElement, "--blyrics-wobble-duration", "1s"),
@@ -1007,6 +1231,14 @@ function readAnimationConfig(engine, lyricsElement) {
             wobblePeakOffset: getCSSOffset(engine, lyricsElement, "--blyrics-word-wobble-peak-offset", 0.125),
             wobbleSettleOffset: getCSSOffset(engine, lyricsElement, "--blyrics-word-wobble-settle-offset", 0.75),
         },
+        letterWave: {
+            transform: getCSSValue(engine, lyricsElement, "--blyrics-letter-wave-transform", "translateY(-0.06em)"),
+            settle: getCSSValue(engine, lyricsElement, "--blyrics-letter-wave-settle", "translateY(-0.05em)"),
+            emphasisScale: getCSSValue(engine, lyricsElement, "--blyrics-letter-wave-emphasis-scale", "1.08"),
+            durationMs: getCSSDurationWithFallback(engine, lyricsElement, "--blyrics-letter-wave-duration", "0.9s"),
+            riseEasing: getCSSValue(engine, lyricsElement, "--blyrics-letter-wave-rise-easing", "ease-in-out"),
+            fallEasing: getCSSValue(engine, lyricsElement, "--blyrics-letter-wave-fall-easing", "ease-in-out"),
+        },
         instrumental: {
             fillFadeDurationMs: getCSSDurationWithFallback(engine, lyricsElement, "--blyrics-instrumental-fill-fade-duration", "150ms"),
             fillFadeEasing: getCSSValue(engine, lyricsElement, "--blyrics-instrumental-fill-fade-easing", "ease"),
@@ -1187,6 +1419,55 @@ function clearVisibleLyricWillChange(engine) {
     }
     engine.visibleWillChangeElements = new Set();
 }
+// Near-viewport lines come from the intersection observer with one viewport of overscan, not from
+// scrollTop, because a scaled/transformed scroll decouples layout coords from what is on screen.
+const LINE_CULL_ROOT_MARGIN = "100% 0px 100% 0px";
+function cullLine(element) {
+    element.style.setProperty("content-visibility", "auto");
+}
+function uncullLine(element) {
+    element.style.removeProperty("content-visibility");
+}
+function clearOffscreenLineCulling(engine) {
+    for (const element of engine.culledLineElements) {
+        uncullLine(element);
+    }
+    engine.culledLineElements = new Set();
+}
+// Rebuilt rather than updated on every line change or relayout, so a skipped line's placeholder height
+// is always freshly measured. Without IntersectionObserver every line stays rendered.
+export function setupLineCullObserver(engine) {
+    engine.lineCullObserver?.disconnect();
+    clearOffscreenLineCulling(engine);
+    const ObserverConstructor = engine.window.IntersectionObserver;
+    if (typeof ObserverConstructor !== "function" || engine.lines.length === 0) {
+        engine.lineCullObserver = null;
+        return;
+    }
+    // Pin each line's skipped placeholder to its last rendered size, so skipping a line never shifts the
+    // container's scroll height, which the engine would misread as a user scroll.
+    const restingHeights = engine.lines.map(line => line.lyricElement.offsetHeight);
+    engine.lines.forEach((line, index) => {
+        line.lyricElement.style.setProperty("contain-intrinsic-block-size", `auto ${restingHeights[index]}px`);
+    });
+    const observer = new ObserverConstructor(entries => {
+        for (const entry of entries) {
+            const element = entry.target;
+            if (entry.isIntersecting) {
+                if (engine.culledLineElements.delete(element))
+                    uncullLine(element);
+            }
+            else if (!engine.culledLineElements.has(element)) {
+                cullLine(element);
+                engine.culledLineElements.add(element);
+            }
+        }
+    }, { root: null, rootMargin: LINE_CULL_ROOT_MARGIN, threshold: 0 });
+    for (const line of engine.lines) {
+        observer.observe(line.lyricElement);
+    }
+    engine.lineCullObserver = observer;
+}
 function updateVisibleLyricWillChange(engine, lines, fromScrollTop, toScrollTop, viewportHeight) {
     const nextVisibleElements = new Set();
     for (const line of lines) {
@@ -1202,28 +1483,30 @@ function updateVisibleLyricWillChange(engine, lines, fromScrollTop, toScrollTop,
     }
     engine.visibleWillChangeElements = nextVisibleElements;
 }
-function getLineScrollItems(lines, lyricsElement) {
+// Footer bounds come from the relayout-time cache, not a getBoundingClientRect here, which would force
+// a synchronous recalc mid-tick after the scroll commit dirtied style.
+function getLineScrollItems(engine, lines) {
+    return engine.cachedFooterItem ? [...lines, engine.cachedFooterItem] : lines;
+}
+function measureFooterItem(engine, lyricsElement) {
     const footer = lyricsElement.querySelector(`:scope > .${FOOTER_CLASS}`);
-    if (!footer)
-        return lines;
+    if (!footer) {
+        engine.cachedFooterItem = null;
+        return;
+    }
     const footerBounds = getRelativeLayoutBounds(lyricsElement, footer);
-    return [
-        ...lines,
-        {
-            lyricElement: footer,
-            position: footerBounds.y,
-            height: footerBounds.height,
-        },
-    ];
+    engine.cachedFooterItem = { lyricElement: footer, position: footerBounds.y, height: footerBounds.height };
 }
 function prepareLineScrollOffsets(engine, lines, activeLineIndex, scrollDeltaPx, fromScrollTop, toScrollTop, viewportHeight, config) {
     if (!config.enabled.scroll || activeLineIndex < 0) {
         return null;
     }
     const scrollDistancePx = Math.abs(scrollDeltaPx);
-    const prepared = [];
+    const translateThemed = LINE_SCROLL_TRANSLATE_SETTINGS.some(setting => setting.isManuallySet());
+    const defaultStartTranslate = `0px ${scrollDeltaPx}px`;
     // Preserve the original windowing exactly: only lines intersecting the
     // union of the old and new viewports receive scroll animations.
+    const requests = [];
     for (let index = 0; index < lines.length; index++) {
         if (!isLineVisibleDuringScroll(lines[index], fromScrollTop, toScrollTop, viewportHeight)) {
             continue;
@@ -1231,35 +1514,64 @@ function prepareLineScrollOffsets(engine, lines, activeLineIndex, scrollDeltaPx,
         const lineElement = lines[index].lyricElement;
         const relativeIndex = index - activeLineIndex;
         const side = lineScrollSide(relativeIndex, scrollDeltaPx);
+        const token = ++engine.lineScrollAnimationToken;
+        engine.lineScrollElementTokens.set(lineElement, token);
+        const item = { lineElement, side, token };
+        const timingKey = `${side}|${Math.abs(relativeIndex)}`;
+        requests.push({ item, index, relativeIndex, timingKey, timing: engine.cachedLineScrollTiming.get(timingKey) });
+    }
+    // The line-scroll vars reach the DOM only for an uncached line, or every line when a theme drives the
+    // translate off them, so an otherwise-cached scroll leaves the visible lines untouched.
+    const linesToWrite = requests.filter(request => translateThemed || !request.timing);
+    for (const { item, index, relativeIndex } of linesToWrite) {
+        const lineElement = item.lineElement;
         lineElement.style.setProperty(LINE_SCROLL_INDEX_PROPERTY, String(index));
         lineElement.style.setProperty(LINE_SCROLL_ACTIVE_INDEX_PROPERTY, String(activeLineIndex));
         lineElement.style.setProperty(LINE_SCROLL_RELATIVE_INDEX_PROPERTY, String(relativeIndex));
         lineElement.style.setProperty(LINE_SCROLL_ABS_RELATIVE_INDEX_PROPERTY, String(Math.abs(relativeIndex)));
-        lineElement.style.setProperty(LINE_SCROLL_SIDE_PROPERTY, side);
+        lineElement.style.setProperty(LINE_SCROLL_SIDE_PROPERTY, item.side);
         lineElement.style.setProperty(LINE_SCROLL_DELTA_PROPERTY, `${scrollDeltaPx}px`);
         lineElement.style.setProperty(LINE_SCROLL_DISTANCE_PROPERTY, `${scrollDistancePx}px`);
         setLineScrollStyleProperties(lineElement);
-        const token = ++engine.lineScrollAnimationToken;
-        engine.lineScrollElementTokens.set(lineElement, token);
-        prepared.push({ lineElement, side, token });
     }
-    const durations = batchResolveLineScrollProperty(engine, prepared, "transition-duration", item => lineScrollDurationProperty(item.side, config.lineScroll.durationMs, config.lineScroll.differentialEffects), style => {
-        const durationMs = toMs(style.transitionDuration.split(",")[0].trim());
-        return durationMs > 0 ? durationMs : config.lineScroll.durationMs;
-    });
-    const startEasings = batchResolveLineScrollProperty(engine, prepared, "transition-timing-function", item => lineScrollEasingProperty(item.side, "start", config.lineScroll.easing, config.lineScroll.differentialEffects), style => style.transitionTimingFunction.trim() || config.lineScroll.easing);
-    const endEasings = batchResolveLineScrollProperty(engine, prepared, "transition-timing-function", item => lineScrollEasingProperty(item.side, "end", config.lineScroll.easing, config.lineScroll.differentialEffects), style => style.transitionTimingFunction.trim() || config.lineScroll.easing);
-    const startTranslates = batchResolveLineScrollProperty(engine, prepared, "translate", item => lineScrollTranslate(item.side, "start", config.lineScroll.differentialEffects), style => normalizedTranslate(style.translate));
-    const endTranslates = batchResolveLineScrollProperty(engine, prepared, "translate", item => lineScrollTranslate(item.side, "end", config.lineScroll.differentialEffects), style => normalizedTranslate(style.translate));
+    const misses = requests.filter(request => !request.timing);
+    if (misses.length > 0) {
+        const missItems = misses.map(request => request.item);
+        const durations = batchResolveLineScrollProperty(engine, missItems, "transition-duration", item => lineScrollDurationProperty(item.side, config.lineScroll.durationMs, config.lineScroll.differentialEffects), style => {
+            const durationMs = toMs(style.transitionDuration.split(",")[0].trim());
+            return durationMs > 0 ? durationMs : config.lineScroll.durationMs;
+        });
+        const startEasings = batchResolveLineScrollProperty(engine, missItems, "transition-timing-function", item => lineScrollEasingProperty(item.side, "start", config.lineScroll.easing, config.lineScroll.differentialEffects), style => style.transitionTimingFunction.trim() || config.lineScroll.easing);
+        const endEasings = batchResolveLineScrollProperty(engine, missItems, "transition-timing-function", item => lineScrollEasingProperty(item.side, "end", config.lineScroll.easing, config.lineScroll.differentialEffects), style => style.transitionTimingFunction.trim() || config.lineScroll.easing);
+        misses.forEach((request, resolveIndex) => {
+            const timing = {
+                durationMs: durations[resolveIndex],
+                startEasing: startEasings[resolveIndex],
+                endEasing: endEasings[resolveIndex],
+            };
+            engine.cachedLineScrollTiming.set(request.timingKey, timing);
+            request.timing = timing;
+        });
+    }
+    let startTranslates = null;
+    let endTranslates = null;
+    if (translateThemed) {
+        const items = requests.map(request => request.item);
+        startTranslates = batchResolveLineScrollProperty(engine, items, "translate", item => lineScrollTranslate(item.side, "start", config.lineScroll.differentialEffects), style => normalizedTranslate(style.translate));
+        endTranslates = batchResolveLineScrollProperty(engine, items, "translate", item => lineScrollTranslate(item.side, "end", config.lineScroll.differentialEffects), style => normalizedTranslate(style.translate));
+    }
     return {
-        items: prepared.map((item, index) => ({
-            ...item,
-            durationMs: durations[index],
-            startEasing: startEasings[index],
-            endEasing: endEasings[index],
-            startTranslate: startTranslates[index],
-            endTranslate: endTranslates[index],
-        })),
+        items: requests.map((request, requestIndex) => {
+            const timing = request.timing;
+            return {
+                ...request.item,
+                durationMs: timing.durationMs,
+                startEasing: timing.startEasing,
+                endEasing: timing.endEasing,
+                startTranslate: startTranslates ? startTranslates[requestIndex] : defaultStartTranslate,
+                endTranslate: endTranslates ? endTranslates[requestIndex] : "0px 0px",
+            };
+        }),
     };
 }
 function startPreparedLineScroll(engine, plan) {
@@ -1436,10 +1748,12 @@ function passiveScrollEngine(engine, isPlaying) {
     }
     const prevScrollTop = tabRenderer.scrollTop;
     tabRenderer.scrollTop = targetScroll;
+    const appliedScrollTop = tabRenderer.scrollTop;
+    engine.cachedScrollTop = appliedScrollTop;
     // Only skip the next scroll event if scrollTop actually changed.
     // When it doesn't change (pause phases, sub-pixel rounding), no programmatic
     // scroll event fires, so setting skipScrolls would eat user scroll events instead.
-    if (tabRenderer.scrollTop !== prevScrollTop) {
+    if (appliedScrollTop !== prevScrollTop) {
         engine.skipScrolls = 1;
     }
 }
@@ -1455,11 +1769,19 @@ function setupTabRendererObserver(engine, element) {
         dropPendingLineScroll(engine);
         if (element && element.isConnected) {
             engine.cachedTabRendererHeight = element.getBoundingClientRect().height;
+            refreshScrollMetrics(engine, element);
         }
     });
     engine.tabRendererResizeObserver.observe(element);
     engine.observedTabRenderer = element;
     engine.cachedTabRendererHeight = element.getBoundingClientRect().height;
+    refreshScrollMetrics(engine, element);
+}
+// Scroll position and bounds are cached here (and refreshed where layout is measured on purpose) so
+// the tick never reads them off the DOM, which would force a synchronous layout flush mid-frame.
+function refreshScrollMetrics(engine, tabRenderer) {
+    engine.cachedMaxScrollTop = Math.max(0, tabRenderer.scrollHeight - tabRenderer.clientHeight);
+    engine.cachedScrollTop = tabRenderer.scrollTop;
 }
 /**
  * Fills in everything a caller left out of a tick. The tick reads each of these arithmetically, so
@@ -1561,8 +1883,17 @@ export function tickView(engine, currentTime, options) {
             setupTabRendererObserver(engine, tabRenderer);
         }
         const tabRendererHeight = engine.cachedTabRendererHeight ?? tabRenderer.getBoundingClientRect().height;
-        let scrollTop = tabRenderer.scrollTop;
-        const maxScrollTop = Math.max(0, tabRenderer.scrollHeight - tabRenderer.clientHeight);
+        // Read the DOM position only while the user scrolls (they own it then); otherwise reuse the cached
+        // value the engine last wrote, so the tick never forces a mid-frame layout flush.
+        let scrollTop;
+        if (engine.scrollResumeTime >= now || engine.cachedScrollTop === null) {
+            scrollTop = tabRenderer.scrollTop;
+            engine.cachedScrollTop = scrollTop;
+        }
+        else {
+            scrollTop = engine.cachedScrollTop;
+        }
+        const maxScrollTop = engine.cachedMaxScrollTop ?? Math.max(0, tabRenderer.scrollHeight - tabRenderer.clientHeight);
         if (animationConfig.enabled.scroll) {
             updateVisibleLyricWillChange(engine, lines, scrollTop, engine.pendingLineScroll?.toScrollTop ?? scrollTop, tabRendererHeight);
         }
@@ -1798,7 +2129,7 @@ export function tickView(engine, currentTime, options) {
                 Date.now() > engine.nextScrollAllowedTime &&
                 Math.abs(scrollTop - scrollPos) > 2) {
                 updateVisibleLyricWillChange(engine, lines, scrollTop, scrollPos, tabRendererHeight);
-                prepareUpcomingLineScroll(engine, getLineScrollItems(lines, lyricsElement), lastActiveLyric, scrollPos - scrollTop, scrollTop, scrollPos, tabRendererHeight, animationConfig);
+                prepareUpcomingLineScroll(engine, getLineScrollItems(engine, lines), lastActiveLyric, scrollPos - scrollTop, scrollTop, scrollPos, tabRendererHeight, animationConfig);
             }
             if (engine.wasUserScrolling || newLyricSelected || engine.queuedScroll) {
                 if (Date.now() > engine.nextScrollAllowedTime) {
@@ -1810,7 +2141,7 @@ export function tickView(engine, currentTime, options) {
                         const scrollDeltaPx = scrollPos - scrollTop;
                         if (animationConfig.enabled.scroll) {
                             updateVisibleLyricWillChange(engine, lines, scrollTop, scrollPos, tabRendererHeight);
-                            const lineScrollItems = getLineScrollItems(lines, lyricsElement);
+                            const lineScrollItems = getLineScrollItems(engine, lines);
                             commitOrPrepareLineScroll(engine, lineScrollItems, lastActiveLyric, scrollDeltaPx, scrollTop, scrollPos, tabRendererHeight, animationConfig);
                             engine.nextScrollAllowedTime = animationConfig.scroll.durationMs + Date.now() + 20;
                         }
@@ -1821,6 +2152,7 @@ export function tickView(engine, currentTime, options) {
                     scrollTop = scrollPos;
                     engine.scrollPos = scrollTop;
                     tabRenderer.scrollTop = scrollTop;
+                    engine.cachedScrollTop = scrollTop;
                     engine.skipScrolls += 1;
                     engine.skipScrollsDecayTimes.push(Date.now() + 2000);
                 }
@@ -1926,12 +2258,20 @@ export function relayout(engine, measureLines) {
     // resize report looking like a new height, and each one measures again and forces a rescroll.
     engine.lyricWidth = lyricsElement.clientWidth;
     engine.lyricHeight = lyricsElement.clientHeight;
+    // Skipped lines report intrinsic size, so un-cull before the walk reads offsetTop/offsetHeight.
+    clearOffscreenLineCulling(engine);
     for (const line of engine.lines) {
         const bounds = getRelativeLayoutBounds(lyricsElement, line.lyricElement);
         line.position = bounds.y;
         line.height = bounds.height;
         line.decorations = new Map(lineDecorators(line.lyricElement).map(element => [element, getRelativeLayoutBounds(lyricsElement, element).y]));
     }
+    measureFooterItem(engine, lyricsElement);
+    // Re-arm from the fresh measurements, so a line skipped after this holds its new placeholder height.
+    setupLineCullObserver(engine);
+    const tabRenderer = engine.host.getScrollElement();
+    if (tabRenderer)
+        refreshScrollMetrics(engine, tabRenderer);
     engine.wasUserScrolling = true; // trigger rescrolls
     engine.host.debug?.resize();
 }

package/dist/inject.d.ts

@@ -17,6 +17,9 @@ export interface AnimationData {
 }
 export interface PartData extends AnimationData {
     highlightElement: HTMLElement;
+    letterElements?: HTMLElement[];
+    highlightLetterElements?: HTMLElement[];
+    glowSuppressed?: boolean;
 }
 export type LineData = {
     parts: PartData[];

package/dist/inject.js

@@ -11,7 +11,7 @@
 // animates is one word, so every part is split on whitespace with its timing pro-rated across the
 // split by character count. A line that arrives with no timed parts at all is rebuilt the same way
 // into zero duration words, so line synced lyrics reach the DOM the sweep already knows.
-import { BACKGROUND_LINE_CLASS, BACKGROUND_LYRIC_CLASS, BIDI_RUN_CLASS, BIDI_SENSITIVE_CLASS, CONTENT_LINE_CLASS, EXPLICIT_WORD_CLASS, HIGHLIGHT_RUN_CLASS, LINE_MAIN_CLASS, LINE_SYNCED_WORD_CLASS, LONG_WORD_GROUP_CLASS, ROMANIZED_LYRICS_CLASS, RTL_CLASS, TRANSLATED_LYRICS_CLASS, WORD_CLASS, WORD_GROUP_CLASS, WORD_HIGHLIGHT_CLASS, ZERO_DURATION_ANIMATION_CLASS, } from "./constants.js";
+import { BACKGROUND_LINE_CLASS, BACKGROUND_LYRIC_CLASS, BIDI_RUN_CLASS, BIDI_SENSITIVE_CLASS, CONTENT_LINE_CLASS, EXPLICIT_WORD_CLASS, HIGHLIGHT_RUN_CLASS, LETTER_CLASS, LINE_MAIN_CLASS, LINE_SYNCED_WORD_CLASS, LONG_WORD_GROUP_CLASS, ROMANIZED_LYRICS_CLASS, RTL_CLASS, TRANSLATED_LYRICS_CLASS, WORD_CLASS, WORD_GROUP_CLASS, WORD_HIGHLIGHT_CLASS, ZERO_DURATION_ANIMATION_CLASS, } from "./constants.js";
 import { getSeekTimeFromClick } from "./seek.js";
 import { testRtl } from "./text.js";
 import { registerThemeSetting } from "./themeSettings.js";
@@ -19,6 +19,7 @@ export let disableRichsync = registerThemeSetting("blyrics-disable-richsync", fa
 let lineSyncedAnimationDelay = registerThemeSetting("blyrics-line-synced-animation-delay", 50, true);
 let longWordThreshold = registerThemeSetting("blyrics-long-word-threshold", 1500, true);
 let longWordWrapThreshold = registerThemeSetting("blyrics-long-word-wrap-threshold", 10, true);
+let letterWave = registerThemeSetting("blyrics-letter-wave", true, true);
 const RTL_SCRIPT_REGEX = /[\p{Script=Arabic}\p{Script=Hebrew}\p{Script=Syriac}\p{Script=Thaana}]/u;
 const LTR_SCRIPT_REGEX = /[\p{Script=Latin}\p{Script=Greek}\p{Script=Cyrillic}\p{Script=Han}\p{Script=Hangul}\p{Script=Hiragana}\p{Script=Katakana}]/u;
 const SPACE_REGEX = /^\s+$/u;
@@ -60,12 +61,14 @@ export function deriveSyncType(lyrics) {
         return "richsync";
     return lyrics.every(item => item.startTimeMs === 0) ? "none" : "synced";
 }
-function newPartData(part, span, highlight) {
+function newPartData(part, span, highlight, letterElements, highlightLetterElements) {
     return {
         time: part.startTimeMs / 1000,
         duration: part.durationMs / 1000,
         lyricElement: span,
         highlightElement: highlight,
+        letterElements,
+        highlightLetterElements,
         animations: [],
     };
 }
@@ -195,10 +198,26 @@ function appendLongWordBreaks(doc, span, text, threshold) {
     }
     return true;
 }
-function createTimedWordSpan(doc, part, wrapThreshold) {
+function appendLetters(doc, wordElement, text) {
+    const chars = [...text];
+    wordElement.style.setProperty("--letters", String(chars.length));
+    // Width of the reveal mask's soft edge as a percentage of its (n+2)-letter-wide box, so the fade
+    // spans the same 0.1*letters of a letter that the old gradient did. See the mask rule in lyrics.css.
+    wordElement.style.setProperty("--mask-fade", `${(10 * chars.length) / (chars.length + 2)}%`);
+    return chars.map(char => {
+        const letter = doc.createElement("span");
+        letter.classList.add(LETTER_CLASS);
+        letter.textContent = char;
+        wordElement.appendChild(letter);
+        return letter;
+    });
+}
+function createTimedWordSpan(doc, part, wrapThreshold, perLetter) {
     const span = doc.createElement("span");
     const highlight = doc.createElement("span");
     highlight.classList.add(WORD_HIGHLIGHT_CLASS);
+    let letters;
+    let highlightLetters;
     for (const wordElement of [span, highlight]) {
         wordElement.classList.add(WORD_CLASS);
         wordElement.dir = "auto";
@@ -214,16 +233,26 @@ function createTimedWordSpan(doc, part, wrapThreshold) {
             wordElement.classList.add(BACKGROUND_LYRIC_CLASS);
         if (part.explicit)
             wordElement.classList.add(EXPLICIT_WORD_CLASS);
-        appendLongWordBreaks(doc, wordElement, part.words, wrapThreshold);
+        if (perLetter) {
+            const collected = appendLetters(doc, wordElement, part.words);
+            if (wordElement === span)
+                letters = collected;
+            else
+                highlightLetters = collected;
+        }
+        else {
+            appendLongWordBreaks(doc, wordElement, part.words, wrapThreshold);
+        }
         wordElement.dataset.time = String(part.startTimeMs / 1000);
         wordElement.dataset.duration = String(part.durationMs / 1000);
         wordElement.dataset.content = part.words;
         wordElement.style.setProperty("--blyrics-duration", part.durationMs + "ms");
     }
-    return { span, highlight };
+    return { span, highlight, letters, highlightLetters };
 }
 function createWordGroup(doc, group, lineData) {
     const wrapThreshold = Math.max(1, longWordWrapThreshold.getNumberValue());
+    const perLetter = letterWave.getBooleanValue();
     const lyricGroup = doc.createElement("span");
     const highlightGroup = doc.createElement("span");
     for (const groupElement of [lyricGroup, highlightGroup]) {
@@ -240,8 +269,8 @@ function createWordGroup(doc, group, lineData) {
     for (const token of group.tokens) {
         if (token.kind === "space")
             continue;
-        const { span, highlight } = createTimedWordSpan(doc, token.part, wrapThreshold);
-        lineData.parts.push(newPartData(token.part, span, highlight));
+        const { span, highlight, letters, highlightLetters } = createTimedWordSpan(doc, token.part, wrapThreshold, perLetter);
+        lineData.parts.push(newPartData(token.part, span, highlight, letters, highlightLetters));
         lyricGroup.appendChild(span);
         highlightGroup.appendChild(highlight);
     }

package/dist/styles/lyrics.css

@@ -117,13 +117,13 @@
 
 @property --lyric-transition-amount-start {
 	syntax: "<number>";
-	inherits: false;
+	inherits: true;
 	initial-value: -0.2;
 }
 
 @property --lyric-transition-amount-end {
 	syntax: "<number>";
-	inherits: false;
+	inherits: true;
 	initial-value: -0.1;
 }
 
@@ -137,7 +137,6 @@
 			calc(100% * var(--lyric-transition-amount-end) + 1px)
 	);
 	background-clip: text;
-	filter: drop-shadow(0 0 0 var(--blyrics-glow-color));
 	opacity: 0;
 	pointer-events: none;
 	--lyric-transition-amount-start: var(
@@ -157,6 +156,34 @@
 	);
 }
 
+.blyrics--letter {
+	display: inline-block;
+}
+
+.blyrics-word-highlight:has(.blyrics--letter) {
+	background-image: none;
+}
+
+.blyrics-word-highlight .blyrics--letter {
+	color: var(--blyrics-lyric-active-color);
+	-webkit-mask-image: linear-gradient(90deg, #000 0, #000 50%, #0000 calc(50% + var(--mask-fade, 3%)));
+	mask-image: linear-gradient(90deg, #000 0, #000 50%, #0000 calc(50% + var(--mask-fade, 3%)));
+	-webkit-mask-repeat: no-repeat;
+	mask-repeat: no-repeat;
+	-webkit-mask-size: calc((var(--letters, 1) + 2) * 100%) 100%;
+	mask-size: calc((var(--letters, 1) + 2) * 100%) 100%;
+	-webkit-mask-position: 0% 0%;
+	mask-position: 0% 0%;
+}
+
+.blyrics-word-highlight.blyrics-rtl .blyrics--letter,
+.blyrics-rtl .blyrics-word-highlight .blyrics--letter {
+	-webkit-mask-image: linear-gradient(270deg, #000 0, #000 50%, #0000 calc(50% + var(--mask-fade, 3%)));
+	mask-image: linear-gradient(270deg, #000 0, #000 50%, #0000 calc(50% + var(--mask-fade, 3%)));
+	-webkit-mask-position: 100% 0%;
+	mask-position: 100% 0%;
+}
+
 [blyrics-alt-hover] .blyrics--word:hover {
 	text-decoration: underline;
 	text-underline-offset: 0.15em;

package/dist/styles/variables.css

@@ -110,6 +110,13 @@
 	--blyrics-word-wobble-peak-easing: ease-in-out;
 	--blyrics-word-wobble-end-easing: ease-out;
 
+	--blyrics-letter-wave-transform: translateY(-0.05em);
+	--blyrics-letter-wave-settle: translateY(-0.02em);
+	--blyrics-letter-wave-emphasis-scale: 1.11;
+	--blyrics-letter-wave-duration: 0.9s;
+	--blyrics-letter-wave-rise-easing: ease-in-out;
+	--blyrics-letter-wave-fall-easing: ease-out;
+
 	--blyrics-instrumental-fill-fade-duration: 150ms;
 	--blyrics-instrumental-fill-fade-easing: ease;
 	--blyrics-instrumental-fill-transform-from: translateY(78%);

package/dist/view.d.ts

@@ -1,4 +1,4 @@
-import type { AnimationEngineInstance } from "./engine.js";
+import { type AnimationEngineInstance } from "./engine.js";
 import type { Lyric } from "./types.js";
 export interface SetLyricsOptions {
     /**

package/dist/view.js

@@ -10,6 +10,7 @@
 // lines is where those values are first knowable: the container, the records, the sync type, the
 // size they were measured at, and the scrolls to swallow before the view has settled.
 import { LINE_CLASS, LYRICS_CLASS, RTL_CLASS } from "./constants.js";
+import { setupLineCullObserver } from "./engine.js";
 import { addSeekHandler, applyDirection, buildLineSyncedParts, createLyricsLine, deriveSyncType, disableRichsync, findNearestAgent, isNearestLyricRtl, newLineData, } from "./inject.js";
 import { createInstrumentalElement } from "./instrumental.js";
 const INITIAL_SKIP_SCROLLS = 2;
@@ -90,4 +91,5 @@ export function setLyrics(engine, mount, lyrics, options) {
     // sizes it by.
     engine.lyricWidth = container.clientWidth;
     engine.lyricHeight = container.clientHeight;
+    setupLineCullObserver(engine);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@braccato/core",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "description": "Synchronized lyrics renderer with word-by-word animations",
   "type": "module",
   "license": "MIT",