@braccato/core 1.1.0 → 1.2.1

package/README.md

@@ -179,6 +179,13 @@ The ones a theme reaches for first. `variables.css` declares the rest.
 `line-height`. Every word is given the glow, so a theme that wants it to mean something selects on
 `data-long-word`, which the module sets on any part held past `blyrics-long-word-threshold`.
 
+The instrumental ripple is the one place a property carries geometry rather than a value.
+`--blyrics-instrumental-wave-path-high` and `--blyrics-instrumental-wave-path-low` are the two shapes
+it morphs between, each a `path()`, and a theme redrawing them is how the wave changes amplitude or
+frequency. Both must use the same commands in the same order with the same number of arguments: a
+browser only interpolates two paths smoothly when their command sequences match, and a mismatched
+pair snaps at the halfway point instead of flowing.
+
 ### Class names
 
 These are published API rather than implementation. Renaming one costs a migration rather than a

package/dist/README.md

@@ -179,6 +179,13 @@ The ones a theme reaches for first. `variables.css` declares the rest.
 `line-height`. Every word is given the glow, so a theme that wants it to mean something selects on
 `data-long-word`, which the module sets on any part held past `blyrics-long-word-threshold`.
 
+The instrumental ripple is the one place a property carries geometry rather than a value.
+`--blyrics-instrumental-wave-path-high` and `--blyrics-instrumental-wave-path-low` are the two shapes
+it morphs between, each a `path()`, and a theme redrawing them is how the wave changes amplitude or
+frequency. Both must use the same commands in the same order with the same number of arguments: a
+browser only interpolates two paths smoothly when their command sequences match, and a mismatched
+pair snaps at the halfway point instead of flowing.
+
 ### Class names
 
 These are published API rather than implementation. Renaming one costs a migration rather than a

package/dist/constants.d.ts

@@ -19,6 +19,7 @@ export declare const BACKGROUND_LINE_CLASS: "blyrics-background-line";
 export declare const WORD_GROUP_CLASS: "blyrics-word-group";
 export declare const LONG_WORD_GROUP_CLASS: "blyrics-word-group-long";
 export declare const WORD_HIGHLIGHT_CLASS: "blyrics-word-highlight";
+export declare const HIGHLIGHT_RUN_CLASS: "blyrics-highlight-run";
 export declare const LINE_SYNCED_WORD_CLASS: "blyrics-line-synced-word";
 export declare const BIDI_RUN_CLASS: "blyrics-bidi-run";
 export declare const BIDI_SENSITIVE_CLASS: "blyrics-bidi-sensitive";

package/dist/constants.js

@@ -25,6 +25,7 @@ export const BACKGROUND_LINE_CLASS = "blyrics-background-line";
 export const WORD_GROUP_CLASS = "blyrics-word-group";
 export const LONG_WORD_GROUP_CLASS = "blyrics-word-group-long";
 export const WORD_HIGHLIGHT_CLASS = "blyrics-word-highlight";
+export const HIGHLIGHT_RUN_CLASS = "blyrics-highlight-run";
 export const LINE_SYNCED_WORD_CLASS = "blyrics-line-synced-word";
 export const BIDI_RUN_CLASS = "blyrics-bidi-run";
 export const BIDI_SENSITIVE_CLASS = "blyrics-bidi-sensitive";

package/dist/engine.d.ts

@@ -184,6 +184,8 @@ interface AnimationConfig {
         waveFrom: string;
         waveTo: string;
         waveEasing: string;
+        wavePathHigh: string;
+        wavePathLow: string;
         waveOscillationDurationMs: number;
         waveOscillationEasing: string;
     };

package/dist/engine.js

@@ -17,6 +17,7 @@
 // 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, 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";
 const NO_LYRICS_ELEMENT_LOG = "No lyrics element found on the page, skipping lyrics injection";
@@ -301,10 +302,14 @@ function resetLineAnimationState(lineData) {
     resetLineAnimations(lineData);
     markLineAnimationsStopped(lineData);
 }
+function togglePartClass(part, className, force) {
+    part.lyricElement.classList.toggle(className, force);
+    part.highlightElement?.classList.toggle(className, force);
+}
 function setAnimationsPlayState(lineData, isPlaying) {
     const children = [lineData, ...lineData.parts];
     for (const part of children) {
-        part.lyricElement.classList.toggle(PAUSED_CLASS, !isPlaying);
+        togglePartClass(part, PAUSED_CLASS, !isPlaying);
         for (const animation of part.animations) {
             if (isPlaying) {
                 animation.play();
@@ -318,16 +323,15 @@ function setAnimationsPlayState(lineData, isPlaying) {
 function clearLineStateClasses(lineData) {
     lineData.lyricElement.classList.remove(ANIMATING_CLASS);
     for (const part of [lineData, ...lineData.parts]) {
-        part.lyricElement.classList.remove(PAUSED_CLASS);
+        togglePartClass(part, PAUSED_CLASS, false);
     }
 }
 const LINE_SYNCED_WORD_CLASS = "blyrics-line-synced-word";
-const WORD_HIGHLIGHT_SELECTOR = ".blyrics-word-highlight";
 const INSTRUMENTAL_FILL_SELECTOR = ".blyrics--instrumental-fill";
 const INSTRUMENTAL_WAVE_CLIP_SELECTOR = ".blyrics--wave-clip";
 const INSTRUMENTAL_WAVE_PATH_SELECTOR = ".blyrics--wave-path";
-const INSTRUMENTAL_WAVE_PATH_HIGH = 'path("M -4 3 Q 1 2 5 3 Q 10 4 14 3 Q 18 2 22 3 Q 26 4 30 3 L 30 4 L -4 4 Z")';
-const INSTRUMENTAL_WAVE_PATH_LOW = 'path("M -4 3 Q 1 4 5 3 Q 10 2 14 3 Q 18 4 22 3 Q 26 2 30 3 L 30 4 L -4 4 Z")';
+const INSTRUMENTAL_WAVE_PATH_HIGH_FALLBACK = `path("${INSTRUMENTAL_WAVE_PATH_HIGH}")`;
+const INSTRUMENTAL_WAVE_PATH_LOW_FALLBACK = `path("${INSTRUMENTAL_WAVE_PATH_LOW}")`;
 const LINE_SCROLL_INDEX_PROPERTY = "--blyrics-line-scroll-index";
 const LINE_SCROLL_ACTIVE_INDEX_PROPERTY = "--blyrics-line-scroll-active-index";
 const LINE_SCROLL_RELATIVE_INDEX_PROPERTY = "--blyrics-line-scroll-relative-index";
@@ -609,13 +613,6 @@ function activeTextInstantKeyframes(config) {
         },
     ];
 }
-function highlightTarget(part) {
-    const highlight = part.lyricElement.querySelector(WORD_HIGHLIGHT_SELECTOR);
-    if (highlight) {
-        return { element: highlight, options: {} };
-    }
-    return { element: part.lyricElement, options: { pseudoElement: "::after" } };
-}
 function lineSyncedTextKeyframes(config) {
     return [
         {
@@ -648,33 +645,30 @@ function fadeOutTextKeyframes(config) {
 }
 function startRichSyncedHighlightAnimations(engine, part, config, swipeTimeMs, wordTimeMs, swipeDurationMs, glowDurationMs, appliedTimingOffsetMs) {
     const animations = [];
-    const target = highlightTarget(part);
+    const highlight = part.highlightElement;
     let swipeAnimation;
     if (config.enabled.highlightSwipe) {
-        swipeAnimation = trackLyricAnimationTiming(engine, target.element.animate(activeTextGradientKeyframes(config), {
+        swipeAnimation = trackLyricAnimationTiming(engine, highlight.animate(activeTextGradientKeyframes(config), {
             duration: swipeDurationMs,
             easing: config.highlight.swipeEasing,
             fill: "forwards",
-            ...target.options,
         }), { appliedTimingOffsetMs, offsetMs: swipeTimeMs - wordTimeMs });
         swipeAnimation.currentTime = correctedAnimationTimeMs(swipeTimeMs, appliedTimingOffsetMs, swipeDurationMs);
         animations.push(swipeAnimation);
     }
-    const opacityAnimation = trackLyricAnimationTiming(engine, target.element.animate(config.enabled.highlightSwipe ? activeTextVisibleKeyframes() : activeTextInstantKeyframes(config), {
+    const opacityAnimation = trackLyricAnimationTiming(engine, highlight.animate(config.enabled.highlightSwipe ? activeTextVisibleKeyframes() : activeTextInstantKeyframes(config), {
         duration: 1,
         easing: "linear",
         fill: "forwards",
-        ...target.options,
     }), { appliedTimingOffsetMs, offsetMs: 0 });
     opacityAnimation.currentTime = correctedAnimationTimeMs(wordTimeMs, appliedTimingOffsetMs, 1);
     animations.push(opacityAnimation);
     let glowAnimation;
     if (config.enabled.highlightGlow) {
-        glowAnimation = trackLyricAnimationTiming(engine, target.element.animate(activeTextGlowKeyframes(config), {
+        glowAnimation = trackLyricAnimationTiming(engine, highlight.animate(activeTextGlowKeyframes(config), {
             duration: glowDurationMs,
             easing: config.highlight.glowEasing,
             fill: "forwards",
-            ...target.options,
         }), { appliedTimingOffsetMs, offsetMs: 0 });
         glowAnimation.currentTime = correctedAnimationTimeMs(wordTimeMs, appliedTimingOffsetMs, glowDurationMs);
         animations.push(glowAnimation);
@@ -684,22 +678,20 @@ function startRichSyncedHighlightAnimations(engine, part, config, swipeTimeMs, w
 function startLineSyncedHighlightAnimations(engine, part, config, wordTimeMs, glowDurationMs, appliedTimingOffsetMs) {
     const animations = [];
     const fadeInDuration = config.enabled.highlightFade ? config.highlight.fadeInDurationMs : 1;
-    const target = highlightTarget(part);
-    const opacityAnimation = trackLyricAnimationTiming(engine, target.element.animate(lineSyncedTextKeyframes(config), {
+    const highlight = part.highlightElement;
+    const opacityAnimation = trackLyricAnimationTiming(engine, highlight.animate(lineSyncedTextKeyframes(config), {
         duration: fadeInDuration,
         easing: config.enabled.highlightFade ? config.highlight.fadeInEasing : "linear",
         fill: "forwards",
-        ...target.options,
     }), { appliedTimingOffsetMs, offsetMs: 0 });
     opacityAnimation.currentTime = correctedAnimationTimeMs(wordTimeMs, appliedTimingOffsetMs, fadeInDuration);
     animations.push(opacityAnimation);
     let glowAnimation;
     if (config.enabled.highlightGlow) {
-        glowAnimation = trackLyricAnimationTiming(engine, target.element.animate(activeTextGlowKeyframes(config), {
+        glowAnimation = trackLyricAnimationTiming(engine, highlight.animate(activeTextGlowKeyframes(config), {
             duration: glowDurationMs,
             easing: config.highlight.glowEasing,
             fill: "forwards",
-            ...target.options,
         }), { appliedTimingOffsetMs, offsetMs: 0 });
         glowAnimation.currentTime = correctedAnimationTimeMs(wordTimeMs, appliedTimingOffsetMs, glowDurationMs);
         animations.push(glowAnimation);
@@ -752,8 +744,9 @@ function startWordAnimations(engine, part, config, currentTime, appliedTimingOff
     const highlightAnimations = isLineSyncedWord
         ? startLineSyncedHighlightAnimations(engine, part, config, wordTimeMs, config.highlight.glowMinDurationMs, appliedTimingOffsetMs)
         : startRichSyncedHighlightAnimations(engine, part, config, swipeTimeMs, wordTimeMs, swipeDurationMs, glowDurationMs, appliedTimingOffsetMs);
-    const wobbleAnimation = config.enabled.wordWobble
-        ? trackLyricAnimationTiming(engine, part.lyricElement.animate([
+    const wobbleAnimations = [];
+    if (config.enabled.wordWobble) {
+        const wobbleKeyframes = [
             { transform: config.word.wobbleFrom },
             {
                 transform: config.word.wobblePeak,
@@ -768,18 +761,25 @@ function startWordAnimations(engine, part, config, currentTime, appliedTimingOff
                 offset: Math.max(config.word.wobblePeakOffset, config.word.wobbleSettleOffset),
             },
             { transform: config.word.wobbleTo, easing: config.word.wobbleEndEasing },
-        ], {
+        ];
+        const wobbleOptions = {
             duration: config.word.wobbleDurationMs,
             easing: config.word.wobbleEasing,
             fill: "forwards",
-        }), { appliedTimingOffsetMs, offsetMs: 0 })
-        : null;
-    if (wobbleAnimation) {
-        wobbleAnimation.currentTime = correctedAnimationTimeMs(wordTimeMs, appliedTimingOffsetMs, config.word.wobbleDurationMs);
+        };
+        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,
+                offsetMs: 0,
+            });
+            animation.currentTime = wobbleStartMs;
+            wobbleAnimations.push(animation);
+        }
     }
-    part.animations = wobbleAnimation
-        ? [...highlightAnimations.animations, wobbleAnimation]
-        : highlightAnimations.animations;
+    part.animations = [...highlightAnimations.animations, ...wobbleAnimations];
 }
 function startLineAnimations(engine, lineData, config, currentTime) {
     const appliedTimingOffsetMs = engine.learnedAnimationTimingOffsetMs;
@@ -795,12 +795,10 @@ function startLineAnimations(engine, lineData, config, currentTime) {
 function startWordExitAnimation(part, config) {
     resetPartAnimations(part);
     const fadeDuration = config.enabled.highlightFade ? config.highlight.fadeOutDurationMs : 1;
-    const target = highlightTarget(part);
-    const animation = target.element.animate(fadeOutTextKeyframes(config), {
+    const animation = part.highlightElement.animate(fadeOutTextKeyframes(config), {
         duration: fadeDuration,
         easing: config.enabled.highlightFade ? config.highlight.fadeOutEasing : "linear",
         fill: "none",
-        ...target.options,
     });
     part.animations = [animation];
     animation.addEventListener("finish", () => {
@@ -856,9 +854,9 @@ function startInstrumentalAnimations(engine, lineData, config, currentTime, appl
             fill: "both",
         }, { appliedTimingOffsetMs, offsetMs: 0 });
         waveOscillationAnimation = animateInstrumentalChild(engine, lineData, INSTRUMENTAL_WAVE_PATH_SELECTOR, [
-            { d: INSTRUMENTAL_WAVE_PATH_HIGH },
-            { d: INSTRUMENTAL_WAVE_PATH_LOW, offset: 0.5 },
-            { d: INSTRUMENTAL_WAVE_PATH_HIGH },
+            { d: config.instrumental.wavePathHigh },
+            { d: config.instrumental.wavePathLow, offset: 0.5 },
+            { d: config.instrumental.wavePathHigh },
         ], {
             duration: config.instrumental.waveOscillationDurationMs,
             easing: config.instrumental.waveOscillationEasing,
@@ -1016,6 +1014,8 @@ function readAnimationConfig(engine, lyricsElement) {
             waveFrom: getCSSValue(engine, lyricsElement, "--blyrics-instrumental-wave-transform-from", "scaleY(1.2)"),
             waveTo: getCSSValue(engine, lyricsElement, "--blyrics-instrumental-wave-transform-to", "scaleY(0.0001)"),
             waveEasing: getCSSValue(engine, lyricsElement, "--blyrics-instrumental-wave-easing", "ease-in"),
+            wavePathHigh: getCSSValue(engine, lyricsElement, "--blyrics-instrumental-wave-path-high", INSTRUMENTAL_WAVE_PATH_HIGH_FALLBACK),
+            wavePathLow: getCSSValue(engine, lyricsElement, "--blyrics-instrumental-wave-path-low", INSTRUMENTAL_WAVE_PATH_LOW_FALLBACK),
             waveOscillationDurationMs: getCSSDurationWithFallback(engine, lyricsElement, "--blyrics-instrumental-wave-oscillation-duration", "1.25s"),
             waveOscillationEasing: getCSSValue(engine, lyricsElement, "--blyrics-instrumental-wave-oscillation-easing", "ease-in-out"),
         },
@@ -1560,6 +1560,7 @@ export function tickView(engine, currentTime, options) {
         }
         const tabRendererHeight = engine.cachedTabRendererHeight ?? tabRenderer.getBoundingClientRect().height;
         let scrollTop = tabRenderer.scrollTop;
+        const maxScrollTop = Math.max(0, tabRenderer.scrollHeight - tabRenderer.clientHeight);
         if (animationConfig.enabled.scroll) {
             updateVisibleLyricWillChange(engine, lines, scrollTop, engine.pendingLineScroll?.toScrollTop ?? scrollTop, tabRendererHeight);
         }
@@ -1713,8 +1714,9 @@ export function tickView(engine, currentTime, options) {
             scrollPos = Math.max(scrollPos, lastActiveLyric.position - tabRendererHeight + lastActiveLyric.height);
             // Make sure top of last active lyric is visible.
             scrollPos = Math.min(scrollPos, lastActiveLyric.position);
-            // Make sure we're not trying to scroll to negative values
-            scrollPos = Math.max(0, scrollPos);
+            // Past either end the browser clamps the write and reports nothing, leaving the view aiming
+            // at a position it never reached and re-aiming once per remaining line.
+            scrollPos = clamp(scrollPos, 0, maxScrollTop);
             if (ENABLE_DEBUG_RENDER.getBooleanValue()) {
                 let transform = engine.window.getComputedStyle(lyricsElement).transform;
                 const matrix = new engine.window.DOMMatrix(transform);
@@ -1899,6 +1901,9 @@ function applyScrollPadding(engine) {
     });
     engine.document.documentElement.style.setProperty("--blyrics-padding-top", top + "px");
     engine.document.documentElement.style.setProperty("--blyrics-padding-bottom", bottom + "px");
+    // Inline, because a theme's own `.blyrics-container { padding }` is appended after the package's
+    // stylesheet at the same weight and would otherwise take this room away.
+    lyricsElement.style.setProperty("padding-bottom", bottom + "px");
 }
 /**
  * Re-reads the view's layout: the scroll padding first, then the line positions the padding moved.

package/dist/inject.d.ts

@@ -14,6 +14,7 @@ export interface PartData {
     duration: number;
     lyricElement: HTMLElement;
     animations: Animation[];
+    highlightElement?: HTMLElement;
 }
 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, 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, 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";
@@ -60,11 +60,12 @@ export function deriveSyncType(lyrics) {
         return "richsync";
     return lyrics.every(item => item.startTimeMs === 0) ? "none" : "synced";
 }
-function newPartData(part, span) {
+function newPartData(part, span, highlight) {
     return {
         time: part.startTimeMs / 1000,
         duration: part.durationMs / 1000,
         lyricElement: span,
+        highlightElement: highlight,
         animations: [],
     };
 }
@@ -193,67 +194,57 @@ function appendLongWordBreaks(doc, span, text, threshold) {
     }
     return true;
 }
-function cloneTextWithBreaks(doc, source) {
-    const fragment = doc.createDocumentFragment();
-    for (const node of source.childNodes) {
-        fragment.appendChild(node.cloneNode(true));
-    }
-    return fragment;
-}
 function createTimedWordSpan(doc, part, wrapThreshold) {
     const span = doc.createElement("span");
-    span.classList.add(WORD_CLASS);
-    span.dir = "auto";
-    if (part.durationMs === 0) {
-        span.classList.add(ZERO_DURATION_ANIMATION_CLASS);
-        span.classList.add(LINE_SYNCED_WORD_CLASS);
-    }
-    if (testRtl(part.words)) {
-        span.classList.add(RTL_CLASS);
-    }
-    if (part.durationMs > longWordThreshold.getNumberValue()) {
-        span.dataset.longWord = "true";
-    }
-    if (part.isBackground) {
-        span.classList.add(BACKGROUND_LYRIC_CLASS);
-    }
-    if (part.explicit) {
-        span.classList.add(EXPLICIT_WORD_CLASS);
-    }
-    const hasBreaks = appendLongWordBreaks(doc, span, part.words, wrapThreshold);
-    if (hasBreaks) {
-        const highlight = doc.createElement("span");
-        highlight.classList.add(WORD_HIGHLIGHT_CLASS);
-        highlight.setAttribute("aria-hidden", "true");
-        highlight.appendChild(cloneTextWithBreaks(doc, span));
-        span.appendChild(highlight);
+    const highlight = doc.createElement("span");
+    highlight.classList.add(WORD_HIGHLIGHT_CLASS);
+    for (const wordElement of [span, highlight]) {
+        wordElement.classList.add(WORD_CLASS);
+        wordElement.dir = "auto";
+        if (part.durationMs === 0) {
+            wordElement.classList.add(ZERO_DURATION_ANIMATION_CLASS);
+            wordElement.classList.add(LINE_SYNCED_WORD_CLASS);
+        }
+        if (testRtl(part.words))
+            wordElement.classList.add(RTL_CLASS);
+        if (part.durationMs > longWordThreshold.getNumberValue())
+            wordElement.dataset.longWord = "true";
+        if (part.isBackground)
+            wordElement.classList.add(BACKGROUND_LYRIC_CLASS);
+        if (part.explicit)
+            wordElement.classList.add(EXPLICIT_WORD_CLASS);
+        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");
     }
-    span.dataset.time = String(part.startTimeMs / 1000);
-    span.dataset.duration = String(part.durationMs / 1000);
-    span.dataset.content = part.words;
-    span.style.setProperty("--blyrics-duration", part.durationMs + "ms");
-    return span;
+    return { span, highlight };
 }
 function createWordGroup(doc, group, lineData) {
     const wrapThreshold = Math.max(1, longWordWrapThreshold.getNumberValue());
-    const groupElement = doc.createElement("span");
-    groupElement.classList.add(WORD_GROUP_CLASS);
-    groupElement.dir = "auto";
-    groupElement.dataset.content = group.text;
-    if (group.text.length > wrapThreshold * 2) {
-        groupElement.classList.add(LONG_WORD_GROUP_CLASS);
-    }
-    if (group.isBackground) {
-        groupElement.classList.add(BACKGROUND_LYRIC_CLASS);
+    const lyricGroup = doc.createElement("span");
+    const highlightGroup = doc.createElement("span");
+    for (const groupElement of [lyricGroup, highlightGroup]) {
+        groupElement.classList.add(WORD_GROUP_CLASS);
+        groupElement.dir = "auto";
+        groupElement.dataset.content = group.text;
+        if (group.text.length > wrapThreshold * 2) {
+            groupElement.classList.add(LONG_WORD_GROUP_CLASS);
+        }
+        if (group.isBackground) {
+            groupElement.classList.add(BACKGROUND_LYRIC_CLASS);
+        }
     }
     for (const token of group.tokens) {
         if (token.kind === "space")
             continue;
-        const span = createTimedWordSpan(doc, token.part, wrapThreshold);
-        lineData.parts.push(newPartData(token.part, span));
-        groupElement.appendChild(span);
+        const { span, highlight } = createTimedWordSpan(doc, token.part, wrapThreshold);
+        lineData.parts.push(newPartData(token.part, span, highlight));
+        lyricGroup.appendChild(span);
+        highlightGroup.appendChild(highlight);
     }
-    return groupElement;
+    return { lyricGroup, highlightGroup };
 }
 function createContentLine(doc, className, text) {
     const line = doc.createElement("div");
@@ -268,6 +259,12 @@ function createBidiRun(doc, text) {
     applyDirection(run, text);
     return run;
 }
+function createHighlightRun(doc, text) {
+    const run = createBidiRun(doc, text);
+    run.classList.add(HIGHLIGHT_RUN_CLASS);
+    run.setAttribute("aria-hidden", "true");
+    return run;
+}
 export function createLyricsLine(doc, parts, line, lyricElement, options = { splitBackgroundLine: true }) {
     const lineText = parts.map(part => part.words).join("");
     const mainText = options.splitBackgroundLine
@@ -282,13 +279,17 @@ export function createLyricsLine(doc, parts, line, lyricElement, options = { spl
         .join("");
     const main = createContentLine(doc, LINE_MAIN_CLASS, mainText);
     const mainRun = createBidiRun(doc, mainText);
+    const mainHighlightRun = createHighlightRun(doc, mainText);
     const groupedTokens = groupTokensByWord(normalizeParts(parts));
     const backgroundLine = createContentLine(doc, BACKGROUND_LINE_CLASS, backgroundText);
     const backgroundRun = createBidiRun(doc, backgroundText);
+    const backgroundHighlightRun = createHighlightRun(doc, backgroundText);
     let hasBackground = false;
     let pendingForegroundSpace = "";
     let pendingBackgroundSpace = "";
+    main.appendChild(mainHighlightRun);
     main.appendChild(mainRun);
+    backgroundLine.appendChild(backgroundHighlightRun);
     backgroundLine.appendChild(backgroundRun);
     for (const item of groupedTokens) {
         if ("kind" in item) {
@@ -299,11 +300,15 @@ export function createLyricsLine(doc, parts, line, lyricElement, options = { spl
         else {
             const shouldUseBackgroundLine = options.splitBackgroundLine && item.isBackground;
             const target = shouldUseBackgroundLine ? backgroundRun : mainRun;
+            const highlightRun = shouldUseBackgroundLine ? backgroundHighlightRun : mainHighlightRun;
             const pendingSpace = shouldUseBackgroundLine ? pendingBackgroundSpace : pendingForegroundSpace;
             if (target.childNodes.length > 0 && pendingSpace.length > 0) {
                 target.appendChild(doc.createTextNode(pendingSpace));
+                highlightRun.appendChild(doc.createTextNode(pendingSpace));
             }
-            target.appendChild(createWordGroup(doc, item, line));
+            const { lyricGroup, highlightGroup } = createWordGroup(doc, item, line);
+            target.appendChild(lyricGroup);
+            highlightRun.appendChild(highlightGroup);
             if (shouldUseBackgroundLine) {
                 hasBackground = true;
                 pendingBackgroundSpace = "";

package/dist/instrumental.d.ts

@@ -1,3 +1,5 @@
+export declare const INSTRUMENTAL_WAVE_PATH_HIGH = "M -4 3 Q 1 2 5 3 Q 10 4 14 3 Q 18 2 22 3 Q 26 4 30 3 L 30 4 L -4 4 Z";
+export declare const INSTRUMENTAL_WAVE_PATH_LOW = "M -4 3 Q 1 4 5 3 Q 10 2 14 3 Q 18 4 22 3 Q 26 2 30 3 L 30 4 L -4 4 Z";
 /**
  * Creates an HTML element representing an instrumental break in the lyrics.
  *

package/dist/instrumental.js

@@ -1,3 +1,5 @@
+export const INSTRUMENTAL_WAVE_PATH_HIGH = "M -4 3 Q 1 2 5 3 Q 10 4 14 3 Q 18 2 22 3 Q 26 4 30 3 L 30 4 L -4 4 Z";
+export const INSTRUMENTAL_WAVE_PATH_LOW = "M -4 3 Q 1 4 5 3 Q 10 2 14 3 Q 18 4 22 3 Q 26 2 30 3 L 30 4 L -4 4 Z";
 /**
  * Creates an HTML element representing an instrumental break in the lyrics.
  *
@@ -56,8 +58,7 @@ export function createInstrumentalElement(doc, container, durationMs, lineIndex)
     // This only contains the surface water. It closes at y=4.
     const wavePath = doc.createElementNS(svgNS, "path");
     wavePath.classList.add("blyrics--wave-path");
-    // Initial draw (matches the 0% keyframe below)
-    wavePath.setAttribute("d", "M -4 3 Q 1 2 5 3 Q 10 4 14 3 Q 18 2 22 3 Q 26 4 30 3 L 30 4 L -4 4 Z");
+    wavePath.setAttribute("d", INSTRUMENTAL_WAVE_PATH_HIGH);
     clipPath.appendChild(wavePath);
     defs.appendChild(clipPath);
     svg.appendChild(defs);

package/dist/renderer.js

@@ -269,6 +269,10 @@ export function createLyricsRenderer(rendererOptions) {
             // Everything the engine resolved off the document was resolved against the theme that just
             // went away.
             clearEngineStyleCaches(engine);
+            // The target scroll position is one of the settings a theme carries, and the scroll padding is
+            // sized against it, so a theme that moves the target moves the layout even when no rule in it
+            // does.
+            measure();
             return needsLyricRebuild;
         },
         tick(currentTimeS, options) {

package/dist/styles/instrumental.css

@@ -69,6 +69,8 @@
 
 	/* Prepare the WAAPI flatten transition. */
 	transform: scaleY(1.2);
+
+	d: var(--blyrics-instrumental-wave-path-high);
 }
 
 /* Trigger the Flattening */
@@ -90,14 +92,3 @@
 	transition-timing-function: ease-out;
 	transition-delay: 0s;
 }
-
-/* Update Keyframes for the "Split" shape */
-/* These paths must close at 'L 30 4 L -4 4' to match the static rect overlap */
-@keyframes blyrics-wave {
-	0%, 100% {
-		d: path("M -4 3 Q 1 2 5 3 Q 10 4 14 3 Q 18 2 22 3 Q 26 4 30 3 L 30 4 L -4 4 Z");
-	}
-	50% {
-		d: path("M -4 3 Q 1 4 5 3 Q 10 2 14 3 Q 18 4 22 3 Q 26 2 30 3 L 30 4 L -4 4 Z");
-	}
-}

package/dist/styles/lyrics.css

@@ -38,6 +38,7 @@
 	display: block;
 	max-width: 100%;
 	overflow-wrap: normal;
+	position: relative;
 	text-align: inherit;
 	unicode-bidi: plaintext;
 	white-space: normal;
@@ -47,18 +48,28 @@
 	display: block;
 	margin-top: 0.1em;
 	max-width: 100%;
+	position: relative;
 	text-align: inherit;
 	unicode-bidi: plaintext;
 	white-space: normal;
 }
 
 .blyrics-bidi-run {
-	display: inline;
+	display: block;
 	max-width: 100%;
 	unicode-bidi: normal;
 	white-space: inherit;
 }
 
+.blyrics-highlight-run {
+	inset: 0 0 auto;
+	pointer-events: none;
+	position: absolute;
+	user-select: none;
+	width: auto;
+	z-index: 1;
+}
+
 .blyrics-word-group {
 	display: inline-block;
 	max-width: 100%;
@@ -116,68 +127,33 @@
 	initial-value: -0.1;
 }
 
-.blyrics--word::after,
-.blyrics-word-highlight {
+.blyrics--word.blyrics-word-highlight {
 	color: transparent;
 	background-image: linear-gradient(
 		90deg,
 		var(--blyrics-lyric-active-color)
-			calc(
-				100% * var(--lyric-transition-amount-start) - 4rem *
-					var(--lyric-transition-amount-start) + 2rem
-			),
+			calc(100% * var(--lyric-transition-amount-start)),
 		#00000000
-			calc(
-				100% * var(--lyric-transition-amount-end) - 4rem *
-					var(--lyric-transition-amount-end) + 2rem + 1px
-			)
+			calc(100% * var(--lyric-transition-amount-end) + 1px)
 	);
 	background-clip: text;
-	box-sizing: content-box;
 	filter: drop-shadow(0 0 0 var(--blyrics-glow-color));
-	left: -2rem;
 	opacity: 0;
-	padding: 2rem;
 	pointer-events: none;
-	position: absolute;
-	top: -2rem;
-	white-space: inherit;
-	width: 100%;
 	--lyric-transition-amount-start: var(
 		--blyrics-highlight-swipe-start-from,
 		-0.2
 	);
 	--lyric-transition-amount-end: var(--blyrics-highlight-swipe-end-from, -0.1);
 }
-
-.blyrics--word::after {
-	content: attr(data-content);
-}
-
-.blyrics-word-highlight {
-	user-select: none;
-}
-
-.blyrics--word:has(.blyrics-word-highlight)::after {
-	content: none;
-}
-
-.blyrics-rtl.blyrics--word::after,
-.blyrics--word.blyrics-rtl::after,
-.blyrics-rtl .blyrics-word-highlight,
-.blyrics--word.blyrics-rtl .blyrics-word-highlight {
+.blyrics-word-highlight.blyrics-rtl,
+.blyrics-rtl .blyrics-word-highlight {
 	background-image: linear-gradient(
 		270deg,
 		var(--blyrics-lyric-active-color)
-			calc(
-				100% * var(--lyric-transition-amount-start) - 4rem *
-					var(--lyric-transition-amount-start) + 2rem
-			),
+			calc(100% * var(--lyric-transition-amount-start)),
 		#00000000
-			calc(
-				100% * var(--lyric-transition-amount-end) - 4rem *
-					var(--lyric-transition-amount-end) + 2rem + 1px
-			)
+			calc(100% * var(--lyric-transition-amount-end) + 1px)
 	);
 }
 

package/dist/styles/variables.css

@@ -117,6 +117,8 @@
 	--blyrics-instrumental-wave-transform-from: scaleY(1.2);
 	--blyrics-instrumental-wave-transform-to: scaleY(0.0001);
 	--blyrics-instrumental-wave-easing: ease-in;
+	--blyrics-instrumental-wave-path-high: path("M -4 3 Q 1 2 5 3 Q 10 4 14 3 Q 18 2 22 3 Q 26 4 30 3 L 30 4 L -4 4 Z");
+	--blyrics-instrumental-wave-path-low: path("M -4 3 Q 1 4 5 3 Q 10 2 14 3 Q 18 4 22 3 Q 26 2 30 3 L 30 4 L -4 4 Z");
 	--blyrics-instrumental-wave-oscillation-duration: 1.25s;
 	--blyrics-instrumental-wave-oscillation-easing: ease-in-out;
 

package/package.json

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