@braccato/core 1.13.2 → 1.14.0

package/README.md

@@ -479,3 +479,42 @@ loading regional CJK web fonts should set `--noto-sans-universal` on these eleme
 `--blyrics-font-family` and `--blyrics-translated-font-family` remain explicit theme overrides.
 They are unset by default; custom CSS that reads them directly should use
 `var(--blyrics-font-family, var(--blyrics-default-font-family))` for the default stack.
+
+### Theme-provided image fills
+
+Image highlights are optional. Enable them in a theme comment:
+
+```css
+/* blyrics-image-highlights = true; */
+.blyrics-container {
+  --blyrics-highlight-image: url("my-image.jpg");
+  --blyrics-image-glow-opacity-from: 0.5;
+  --blyrics-image-glow-opacity-to: 0;
+}
+```
+
+Changing this setting requests a lyric rebuild through the existing `setTheme` return value.
+Without it, the renderer adds no image or glow layers and keeps its shadow animation. With it,
+the sharp fill and a separate blurred copy share the word reveal, letter motion, opacity, pause,
+seek and playback-rate handling. Existing glow radius, duration and easing properties still apply;
+the two image-glow opacity properties replace the solid shadow color's alpha.
+
+The image may be an SDR texture or an HDR gain-map asset. The theme owns HDR media queries
+and `dynamic-range-limit`; the core never opts into extra display brightness. Ordinary active
+text color backs up the image fill, while the note keeps its original color path until its
+SVG image loads. The note image reuses the original animated wave clip and fade group.
+
+The glow layer is outside the paint's mask, avoiding clipped halos at word edges. Bidi-sensitive
+runs and fragmented long words use a parallel inline text run for the glow, so the browser
+reproduces the same ordering and wrapped fragments. Its reveal and visibility use the same
+animation clock as the sharp text. No generated text or per-frame geometry reads are needed.
+Joining-script word groups retain contextual joining by using whole-word sweeps instead of
+inline-block letter waves, including when image highlights are disabled.
+Forced colors suppress the image and halo in favor of system text colors.
+
+For real-browser regression checks, build the package, serve the repository root and open
+`tooling/browser/image-highlights.html`. Import `image-highlights-checks.js` from that page and
+call `runImageHighlightChecks(testView)`. The default fixture uses an SDR image; a `theme` query
+parameter can point at a consumer's HDR stylesheet for physical-display testing.
+
+Words that mix RTL characters with LTR letters or numbers retain native text shaping instead of per-letter motion. Image glow, letter masks and letter motion retain their current paint during the line exit fade.

package/dist/README.md

@@ -479,3 +479,42 @@ loading regional CJK web fonts should set `--noto-sans-universal` on these eleme
 `--blyrics-font-family` and `--blyrics-translated-font-family` remain explicit theme overrides.
 They are unset by default; custom CSS that reads them directly should use
 `var(--blyrics-font-family, var(--blyrics-default-font-family))` for the default stack.
+
+### Theme-provided image fills
+
+Image highlights are optional. Enable them in a theme comment:
+
+```css
+/* blyrics-image-highlights = true; */
+.blyrics-container {
+  --blyrics-highlight-image: url("my-image.jpg");
+  --blyrics-image-glow-opacity-from: 0.5;
+  --blyrics-image-glow-opacity-to: 0;
+}
+```
+
+Changing this setting requests a lyric rebuild through the existing `setTheme` return value.
+Without it, the renderer adds no image or glow layers and keeps its shadow animation. With it,
+the sharp fill and a separate blurred copy share the word reveal, letter motion, opacity, pause,
+seek and playback-rate handling. Existing glow radius, duration and easing properties still apply;
+the two image-glow opacity properties replace the solid shadow color's alpha.
+
+The image may be an SDR texture or an HDR gain-map asset. The theme owns HDR media queries
+and `dynamic-range-limit`; the core never opts into extra display brightness. Ordinary active
+text color backs up the image fill, while the note keeps its original color path until its
+SVG image loads. The note image reuses the original animated wave clip and fade group.
+
+The glow layer is outside the paint's mask, avoiding clipped halos at word edges. Bidi-sensitive
+runs and fragmented long words use a parallel inline text run for the glow, so the browser
+reproduces the same ordering and wrapped fragments. Its reveal and visibility use the same
+animation clock as the sharp text. No generated text or per-frame geometry reads are needed.
+Joining-script word groups retain contextual joining by using whole-word sweeps instead of
+inline-block letter waves, including when image highlights are disabled.
+Forced colors suppress the image and halo in favor of system text colors.
+
+For real-browser regression checks, build the package, serve the repository root and open
+`tooling/browser/image-highlights.html`. Import `image-highlights-checks.js` from that page and
+call `runImageHighlightChecks(testView)`. The default fixture uses an SDR image; a `theme` query
+parameter can point at a consumer's HDR stylesheet for physical-display testing.
+
+Words that mix RTL characters with LTR letters or numbers retain native text shaping instead of per-letter motion. Image glow, letter masks and letter motion retain their current paint during the line exit fade.

package/dist/engine.d.ts

@@ -171,6 +171,10 @@ interface AnimationConfig {
         swipeEndFrom: string;
         swipeStartTo: string;
         swipeEndTo: string;
+        imageGlowFrom: string;
+        imageGlowTo: string;
+        imageGlowOpacityFrom: string;
+        imageGlowOpacityTo: string;
         glowFrom: string;
         glowTo: string;
         glowDurationRatio: number;

package/dist/engine.js

@@ -319,6 +319,7 @@ function togglePartClass(part, className, force) {
     part.lyricElement.classList.toggle(className, force);
     if ("highlightElement" in part) {
         part.highlightElement.classList.toggle(className, force);
+        part.imageLayers?.highlight?.classList.toggle(className, force);
     }
 }
 function setAnimationsPlayState(lineData, isPlaying) {
@@ -359,6 +360,7 @@ export function updateWordStates(lineData, currentTime) {
         part.wordState = state;
         part.lyricElement.setAttribute(WORD_STATE_ATTR, state);
         part.highlightElement.setAttribute(WORD_STATE_ATTR, state);
+        part.imageLayers?.highlight?.setAttribute(WORD_STATE_ATTR, state);
     }
 }
 const LINE_SYNCED_WORD_CLASS = "blyrics-line-synced-word";
@@ -386,6 +388,25 @@ const LINE_SCROLL_INLINE_PROPERTIES = [
     ...LINE_SCROLL_STYLE_SETTINGS.map(([property]) => property),
 ];
 const animationTimingTracks = new WeakMap();
+function mirrorImageHighlightAnimations(part, animations) {
+    const target = part.imageLayers?.highlight;
+    if (!target)
+        return [];
+    const mirrors = [];
+    for (const animation of animations) {
+        const effect = animation.effect;
+        if (!effect || effect.target !== part.highlightElement)
+            continue;
+        const mirror = target.animate(effect.getKeyframes(), effect.getTiming());
+        mirror.playbackRate = animation.playbackRate;
+        mirror.currentTime = animation.currentTime;
+        const timing = animationTimingTracks.get(animation);
+        if (timing)
+            animationTimingTracks.set(mirror, timing);
+        mirrors.push(mirror);
+    }
+    return mirrors;
+}
 function trackLyricAnimationTiming(engine, animation, timing) {
     animationTimingTracks.set(animation, {
         ...timing,
@@ -652,7 +673,12 @@ function activeTextGradientKeyframes(config) {
         },
     ];
 }
-function activeTextGlowKeyframes(config) {
+function activeTextGlowKeyframes(config, part) {
+    if (part.imageLayers)
+        return [
+            { filter: `blur(${config.highlight.imageGlowFrom})`, opacity: config.highlight.imageGlowOpacityFrom },
+            { filter: `blur(${config.highlight.imageGlowTo})`, opacity: config.highlight.imageGlowOpacityTo },
+        ];
     return [{ filter: config.highlight.glowFrom }, { filter: config.highlight.glowTo }];
 }
 function activeTextVisibleKeyframes() {
@@ -686,17 +712,17 @@ function lineSyncedTextKeyframes(config) {
         },
     ];
 }
-function fadeOutTextKeyframes(config) {
+function fadeOutTextKeyframes(config, part) {
     return [
         {
             opacity: 1,
-            filter: config.highlight.glowTo,
+            filter: part.imageLayers ? "none" : config.highlight.glowTo,
             "--lyric-transition-amount-start": config.highlight.swipeStartTo,
             "--lyric-transition-amount-end": config.highlight.swipeEndTo,
         },
         {
             opacity: 0,
-            filter: config.highlight.glowTo,
+            filter: part.imageLayers ? "none" : config.highlight.glowTo,
             "--lyric-transition-amount-start": config.highlight.swipeStartTo,
             "--lyric-transition-amount-end": config.highlight.swipeEndTo,
         },
@@ -790,15 +816,18 @@ function startRichSyncedHighlightAnimations(engine, part, config, swipeTimeMs, w
                 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);
+                const targets = [highlightLetters[index], part.imageLayers?.glowLetters[index]].filter((target) => target !== undefined);
+                for (const target of targets) {
+                    const animation = trackLyricAnimationTiming(engine, target.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 {
@@ -820,10 +849,10 @@ function startRichSyncedHighlightAnimations(engine, part, config, swipeTimeMs, w
     animations.push(opacityAnimation);
     let glowAnimation;
     if (config.enabled.highlightGlow && !part.glowSuppressed) {
-        glowAnimation = trackLyricAnimationTiming(engine, highlight.animate(activeTextGlowKeyframes(config), {
+        glowAnimation = trackLyricAnimationTiming(engine, (part.imageLayers?.glow ?? highlight).animate(activeTextGlowKeyframes(config, part), {
             duration: glowDurationMs,
             easing: config.highlight.glowEasing,
-            fill: config.highlight.glowRestingInvisible ? "none" : "forwards",
+            fill: part.imageLayers ? "forwards" : config.highlight.glowRestingInvisible ? "none" : "forwards",
         }), { appliedTimingOffsetMs, offsetMs: 0 });
         glowAnimation.currentTime = correctedAnimationTimeMs(wordTimeMs, appliedTimingOffsetMs, glowDurationMs);
         animations.push(glowAnimation);
@@ -843,10 +872,10 @@ function startLineSyncedHighlightAnimations(engine, part, config, wordTimeMs, gl
     animations.push(opacityAnimation);
     let glowAnimation;
     if (config.enabled.highlightGlow && !part.glowSuppressed) {
-        glowAnimation = trackLyricAnimationTiming(engine, highlight.animate(activeTextGlowKeyframes(config), {
+        glowAnimation = trackLyricAnimationTiming(engine, (part.imageLayers?.glow ?? highlight).animate(activeTextGlowKeyframes(config, part), {
             duration: glowDurationMs,
             easing: config.highlight.glowEasing,
-            fill: config.highlight.glowRestingInvisible ? "none" : "forwards",
+            fill: part.imageLayers ? "forwards" : config.highlight.glowRestingInvisible ? "none" : "forwards",
         }), { appliedTimingOffsetMs, offsetMs: 0 });
         glowAnimation.currentTime = correctedAnimationTimeMs(wordTimeMs, appliedTimingOffsetMs, glowDurationMs);
         animations.push(glowAnimation);
@@ -947,7 +976,7 @@ function startWordAnimations(engine, part, config, currentTime, appliedTimingOff
             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]) {
+            for (const set of [part.letterElements, part.highlightLetterElements, part.imageLayers?.glowLetters]) {
                 set?.forEach((letterElement, index) => {
                     const animation = trackLyricAnimationTiming(engine, acquireWaveAnimation(engine, letterElement, floatKeyframes, floatKeyframeSignature, {
                         duration: config.letterWave.durationMs,
@@ -960,7 +989,11 @@ function startWordAnimations(engine, part, config, currentTime, appliedTimingOff
             }
         }
     }
-    part.animations = [...highlightAnimations.animations, ...wobbleAnimations];
+    part.animations = [
+        ...highlightAnimations.animations,
+        ...mirrorImageHighlightAnimations(part, highlightAnimations.animations),
+        ...wobbleAnimations,
+    ];
 }
 function startLineAnimations(engine, lineData, config, currentTime) {
     const appliedTimingOffsetMs = engine.learnedAnimationTimingOffsetMs;
@@ -974,20 +1007,43 @@ function startLineAnimations(engine, lineData, config, currentTime) {
         startWordAnimations(engine, part, config, currentTime, appliedTimingOffsetMs);
     }
 }
-function startWordExitAnimation(part, config) {
+function startWordExitAnimation(part, config, imagePaint = []) {
     resetPartAnimations(part);
     const fadeDuration = config.enabled.highlightFade ? config.highlight.fadeOutDurationMs : 1;
-    const animation = part.highlightElement.animate(fadeOutTextKeyframes(config), {
+    const animation = part.highlightElement.animate(fadeOutTextKeyframes(config, part), {
         duration: fadeDuration,
         easing: config.enabled.highlightFade ? config.highlight.fadeOutEasing : "linear",
         fill: "none",
     });
-    part.animations = [animation];
+    part.animations = [animation, ...mirrorImageHighlightAnimations(part, [animation])];
+    // Keep the current blur, letter masks and motion visible until the parent fade ends.
+    for (const { target, frame } of imagePaint) {
+        part.animations.push(target.animate([frame, frame], { duration: fadeDuration, fill: "none" }));
+    }
     animation.addEventListener("finish", () => {
         resetPartAnimations(part);
     }, { once: true });
 }
 function startLineExitAnimations(engine, lineData, config, currentTime) {
+    // Read the entire line before cancelling any effects, so this does not alternate
+    // per-word style reads with writes. There are no extra reads during normal ticks.
+    const imagePaint = new Map();
+    for (const part of lineData.parts) {
+        if (!part.imageLayers || currentTime < part.time)
+            continue;
+        const style = engine.window.getComputedStyle(part.imageLayers.glow);
+        const paint = [
+            { target: part.imageLayers.glow, frame: { opacity: style.opacity, filter: style.filter } },
+        ];
+        for (const target of part.letterElements ?? []) {
+            paint.push({ target, frame: { transform: engine.window.getComputedStyle(target).transform } });
+        }
+        for (const target of [...(part.highlightLetterElements ?? []), ...part.imageLayers.glowLetters]) {
+            const letterStyle = engine.window.getComputedStyle(target);
+            paint.push({ target, frame: { maskPosition: letterStyle.maskPosition, transform: letterStyle.transform } });
+        }
+        imagePaint.set(part, paint);
+    }
     startLineExitAnimation(lineData, config);
     if (lineData.lyricElement.dataset.instrumental === "true") {
         startInstrumentalExitAnimations(engine, lineData, config, currentTime);
@@ -995,7 +1051,7 @@ function startLineExitAnimations(engine, lineData, config, currentTime) {
     }
     for (const part of lineData.parts) {
         if (currentTime >= part.time) {
-            startWordExitAnimation(part, config);
+            startWordExitAnimation(part, config, imagePaint.get(part));
         }
         else {
             resetPartAnimations(part);
@@ -1171,7 +1227,7 @@ export function parseColorAlpha(value) {
 // 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) {
+    if (lineData.parts.some(part => part.imageLayers) || config.highlight.glowContainerAlpha >= GLOW_INVISIBLE_ALPHA) {
         for (const part of lineData.parts)
             part.glowSuppressed = false;
         return;
@@ -1229,6 +1285,10 @@ function readAnimationConfig(engine, lyricsElement) {
             swipeEndFrom: getCSSValue(engine, lyricsElement, "--blyrics-highlight-swipe-end-from", "-0.1"),
             swipeStartTo: getCSSValue(engine, lyricsElement, "--blyrics-highlight-swipe-start-to", "1.4"),
             swipeEndTo: getCSSValue(engine, lyricsElement, "--blyrics-highlight-swipe-end-to", "1.5"),
+            imageGlowFrom: getCSSValue(engine, lyricsElement, "--blyrics-highlight-glow-radius-from", "0.8rem"),
+            imageGlowTo: getCSSValue(engine, lyricsElement, "--blyrics-highlight-glow-radius-to", "0px"),
+            imageGlowOpacityFrom: getCSSValue(engine, lyricsElement, "--blyrics-image-glow-opacity-from", "0.5"),
+            imageGlowOpacityTo: getCSSValue(engine, lyricsElement, "--blyrics-image-glow-opacity-to", "0"),
             glowFrom: resolveGlowFilter(engine, lyricsElement, "from", "0.8rem"),
             glowTo: resolveGlowFilter(engine, lyricsElement, "to", "0"),
             glowDurationRatio: getCSSNumber(engine, lyricsElement, "--blyrics-highlight-glow-duration-ratio", 1.2),

package/dist/imageHighlights.d.ts

@@ -0,0 +1,15 @@
+import type { PartData } from "./inject.js";
+export declare const imageHighlights: import("./themeSettings.js").Setting;
+export interface ImageHighlightLayers {
+    glow: HTMLElement;
+    glowLetters: HTMLElement[];
+    /** A separate inline layout host, only for runs that can fragment. */
+    highlight?: HTMLElement;
+}
+export declare function wrapImageHighlight(highlight: HTMLElement): ImageHighlightLayers | undefined;
+/** Keep bidi ordering and inline fragments in the browser's normal text layout. An
+ * absolutely positioned copy inside an inline word cannot reproduce those fragments. */
+export declare function alignImageGlowRun(run: HTMLElement, parts: PartData[]): void;
+/** A single CSS url(), not gradients or an arbitrary list of background layers. */
+export declare function imageURL(value: string): string | null;
+export declare function refreshInstrumentalImages(container: HTMLElement | null, view: Window): void;

package/dist/imageHighlights.js

@@ -0,0 +1,80 @@
+// Optional image paint, independent of HDR: a theme supplies the image and its dynamic range.
+// The extra layer exists only when requested. Blur surrounds the already-masked paint, so it
+// cannot be cut off by the karaoke mask. Both copies are driven by the engine's own animations.
+import { registerThemeSetting } from "./themeSettings.js";
+export const imageHighlights = registerThemeSetting("blyrics-image-highlights", false, true);
+export function wrapImageHighlight(highlight) {
+    if (!imageHighlights.getBooleanValue())
+        return;
+    const doc = highlight.ownerDocument;
+    const paint = doc.createElement("span");
+    paint.classList.add("blyrics-image-fill");
+    while (highlight.firstChild)
+        paint.appendChild(highlight.firstChild);
+    const glow = doc.createElement("span");
+    glow.classList.add("blyrics-image-glow");
+    glow.setAttribute("aria-hidden", "true");
+    glow.appendChild(paint.cloneNode(true));
+    highlight.classList.add("blyrics-image-highlight");
+    highlight.appendChild(glow);
+    highlight.appendChild(paint);
+    return { glow, glowLetters: Array.from(glow.querySelectorAll(".blyrics--letter")) };
+}
+/** Keep bidi ordering and inline fragments in the browser's normal text layout. An
+ * absolutely positioned copy inside an inline word cannot reproduce those fragments. */
+export function alignImageGlowRun(run, parts) {
+    if (!imageHighlights.getBooleanValue())
+        return;
+    if (!run.parentElement?.classList.contains("blyrics-bidi-sensitive") &&
+        !run.querySelector(".blyrics-word-group-long"))
+        return;
+    const originals = Array.from(run.querySelectorAll(".blyrics-word-highlight"));
+    const byHighlight = new Map(parts.map(part => [part.highlightElement, part]));
+    const glowRun = run.cloneNode(true);
+    glowRun.classList.add("blyrics-image-glow-run");
+    const copies = glowRun.querySelectorAll(".blyrics-word-highlight");
+    originals.forEach((original, index) => {
+        const part = byHighlight.get(original);
+        if (!part?.imageLayers)
+            return;
+        const copy = copies[index];
+        copy.replaceChildren(part.imageLayers.glow);
+        part.imageLayers.highlight = copy;
+        // Non-fragmented groups in a mixed run can still wobble. Give their glow the
+        // identical group transform, rather than letting it drift from the sharp copy.
+        const group = original.parentElement;
+        if (group && part.wobbleElements.includes(group) && copy.parentElement)
+            part.wobbleElements.push(copy.parentElement);
+    });
+    run.parentElement.insertBefore(glowRun, run);
+}
+/** A single CSS url(), not gradients or an arbitrary list of background layers. */
+export function imageURL(value) {
+    const match = /^url\(\s*(?:"([^"]*)"|'([^']*)'|([^\s'"()]+))\s*\)$/i.exec(value.trim());
+    return match ? (match[1] ?? match[2] ?? match[3]) : null;
+}
+// SVG <image> follows the browser's normal image drawing path, including gain maps. feImage
+// and SVG patterns can rasterize through an SDR intermediate. Keep the original color path
+// available until loading succeeds, and whenever a theme's media query supplies no image.
+export function refreshInstrumentalImages(container, view) {
+    if (!container || !imageHighlights.getBooleanValue())
+        return;
+    for (const svg of container.querySelectorAll(".blyrics--instrumental-icon")) {
+        const image = svg.querySelector(".blyrics-instrumental-image");
+        if (!image)
+            continue;
+        const source = imageURL(view.getComputedStyle(svg).getPropertyValue("--blyrics-highlight-image"));
+        if (source === image.getAttribute("href"))
+            continue;
+        svg.removeAttribute("data-image-ready");
+        image.onload = () => {
+            if (image.getAttribute("href") === source)
+                svg.setAttribute("data-image-ready", "");
+        };
+        image.onerror = () => svg.removeAttribute("data-image-ready");
+        if (source)
+            image.setAttribute("href", source);
+        else
+            image.removeAttribute("href");
+    }
+}

package/dist/inject.d.ts

@@ -1,3 +1,4 @@
+import { type ImageHighlightLayers } from "./imageHighlights.js";
 import { type WordState } from "./constants.js";
 import type { Lyric, LyricPart, LyricSyncType } from "./types.js";
 export declare let disableRichsync: import("./themeSettings.js").Setting;
@@ -19,6 +20,7 @@ export interface AnimationData {
 }
 export interface PartData extends AnimationData {
     highlightElement: HTMLElement;
+    imageLayers?: ImageHighlightLayers;
     letterElements?: HTMLElement[];
     highlightLetterElements?: HTMLElement[];
     wobbleElements: HTMLElement[];

package/dist/inject.js

@@ -11,6 +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 { alignImageGlowRun, wrapImageHighlight } from "./imageHighlights.js";
 import { normalizeLanguage } from "./language.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, WORD_HIGHLIGHT_LETTERED_CLASS, WORD_STATE_ATTR, WORD_STATE_UPCOMING, ZERO_DURATION_ANIMATION_CLASS, } from "./constants.js";
 import { getSeekTimeFromClick } from "./seek.js";
@@ -69,6 +70,7 @@ function newPartData(part, span, highlight, wobbleElements, letterElements, high
         duration: part.durationMs / 1000,
         lyricElement: span,
         highlightElement: highlight,
+        imageLayers: wrapImageHighlight(highlight),
         letterElements,
         highlightLetterElements,
         wobbleElements,
@@ -216,7 +218,7 @@ function appendLetters(doc, wordElement, text) {
         return letter;
     });
 }
-function createTimedWordSpan(doc, part, wrapThreshold, perLetter) {
+function createTimedWordSpan(doc, part, wrapThreshold, perLetter, preserveJoining) {
     const span = doc.createElement("span");
     const highlight = doc.createElement("span");
     highlight.classList.add(WORD_HIGHLIGHT_CLASS);
@@ -237,7 +239,8 @@ function createTimedWordSpan(doc, part, wrapThreshold, perLetter) {
             wordElement.classList.add(BACKGROUND_LYRIC_CLASS);
         if (part.explicit)
             wordElement.classList.add(EXPLICIT_WORD_CLASS);
-        if (perLetter && !testJoiningScript(part.words)) {
+        if (perLetter) {
+            wordElement.classList.add("blyrics-word--lettered");
             const collected = appendLetters(doc, wordElement, part.words);
             if (wordElement === span) {
                 letters = collected;
@@ -247,6 +250,9 @@ function createTimedWordSpan(doc, part, wrapThreshold, perLetter) {
                 wordElement.classList.add(WORD_HIGHLIGHT_LETTERED_CLASS);
             }
         }
+        else if (preserveJoining) {
+            wordElement.textContent = part.words;
+        }
         else {
             appendLongWordBreaks(doc, wordElement, part.words, wrapThreshold);
         }
@@ -260,7 +266,10 @@ function createTimedWordSpan(doc, part, wrapThreshold, perLetter) {
 }
 function createWordGroup(doc, group, lineData) {
     const wrapThreshold = Math.max(1, longWordWrapThreshold.getNumberValue());
-    const perLetter = letterWave.getBooleanValue();
+    // Atomic grapheme spans disrupt the browser's bidi ordering inside a mixed word.
+    const mixedDirection = testRtl(group.text) && [...group.text].some(char => /[\p{Letter}\p{Number}]/u.test(char) && !testRtl(char));
+    const preserveJoining = testJoiningScript(group.text);
+    const perLetter = letterWave.getBooleanValue() && !preserveJoining && !mixedDirection;
     const lyricGroup = doc.createElement("span");
     const highlightGroup = doc.createElement("span");
     for (const groupElement of [lyricGroup, highlightGroup]) {
@@ -277,7 +286,7 @@ function createWordGroup(doc, group, lineData) {
     for (const token of group.tokens) {
         if (token.kind === "space")
             continue;
-        const { span, highlight, letters, highlightLetters } = createTimedWordSpan(doc, token.part, wrapThreshold, perLetter);
+        const { span, highlight, letters, highlightLetters } = createTimedWordSpan(doc, token.part, wrapThreshold, perLetter, preserveJoining);
         const wobbleElements = lyricGroup.childNodes.length === 0 ? [lyricGroup, highlightGroup] : [];
         lineData.parts.push(newPartData(token.part, span, highlight, wobbleElements, letters, highlightLetters));
         lyricGroup.appendChild(span);
@@ -366,6 +375,9 @@ export function createLyricsLine(doc, parts, line, lyricElement, options = { spl
             }
         }
     }
+    alignImageGlowRun(mainHighlightRun, line.parts);
+    if (hasBackground)
+        alignImageGlowRun(backgroundHighlightRun, line.parts);
     lyricElement.appendChild(main);
     if (hasBackground) {
         lyricElement.appendChild(backgroundLine);

package/dist/instrumental.js

@@ -1,3 +1,4 @@
+import { imageHighlights } from "./imageHighlights.js";
 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";
 /**
@@ -72,7 +73,45 @@ export function createInstrumentalElement(doc, container, durationMs, lineIndex)
     fillPath.classList.add("blyrics--instrumental-fill");
     fillPath.setAttribute("clip-path", `url(#${clipId})`);
     fillPath.setAttribute("d", "M10 21q-1.65 0-2.825-1.175T6 17t1.175-2.825T10 13q.575 0 1.063.138t.937.412V4q0-.425.288-.712T13 3h4q.425 0 .713.288T18 4v2q0 .425-.288.713T17 7h-3v10q0 1.65-1.175 2.825T10 21");
-    g.appendChild(fillPath);
+    if (imageHighlights.getBooleanValue()) {
+        // Fade the common group so both the image and the SDR fallback follow the original
+        // instrumental animation. The wave and silhouette clips are inside the glow filter.
+        fillPath.classList.remove("blyrics--instrumental-fill");
+        fillPath.classList.add("blyrics-instrumental-color");
+        const fill = doc.createElementNS(svgNS, "g");
+        fill.classList.add("blyrics--instrumental-fill");
+        fill.appendChild(fillPath);
+        const shapeId = `${clipId}-image-shape`;
+        const shape = doc.createElementNS(svgNS, "clipPath");
+        shape.setAttribute("id", shapeId);
+        const shapePath = doc.createElementNS(svgNS, "path");
+        shapePath.setAttribute("d", fillPath.getAttribute("d"));
+        shape.appendChild(shapePath);
+        defs.appendChild(shape);
+        const silhouette = doc.createElementNS(svgNS, "g");
+        silhouette.setAttribute("clip-path", `url(#${shapeId})`);
+        const wave = doc.createElementNS(svgNS, "g");
+        wave.setAttribute("clip-path", `url(#${clipId})`);
+        const image = doc.createElementNS(svgNS, "image");
+        image.classList.add("blyrics-instrumental-image");
+        image.setAttribute("x", "0");
+        image.setAttribute("y", "0");
+        image.setAttribute("width", "24");
+        image.setAttribute("height", "24");
+        image.setAttribute("preserveAspectRatio", "none");
+        wave.appendChild(image);
+        silhouette.appendChild(wave);
+        fill.appendChild(silhouette);
+        g.appendChild(fill);
+        // Blur RGB directly instead of recoloring the halo with an SDR flood/shadow.
+        filter.setAttribute("color-interpolation-filters", "sRGB");
+        feGaussianBlur.setAttribute("stdDeviation", "1");
+        filter.removeChild(feColorMatrix);
+        feMergeNode1.setAttribute("in", "blur");
+    }
+    else {
+        g.appendChild(fillPath);
+    }
     svg.appendChild(g);
     container.appendChild(svg);
     return container;

package/dist/renderer.js

@@ -9,6 +9,7 @@
 // this view on screen, is a loader up) and performs the actions it must not own (seek the player).
 // `debug` is the exception because there is nothing to default it to. A consumer that wants the
 // diagnostic overlay supplies the sink, and one that says nothing draws nothing.
+import { imageHighlights, refreshInstrumentalImages } from "./imageHighlights.js";
 import { CUSTOM_THEME_STYLE_ID } from "./constants.js";
 import { clearLyrics, clearOnScreenLyrics as clearEngineOnScreenLyrics, clearStyleCaches as clearEngineStyleCaches, createAnimationEngineInstance, getRenderedLines, getRenderedSyncType, hasUnsyncedLyrics, noteContainerResize, noteUserScroll as noteEngineUserScroll, noteVisibilityChange as noteEngineVisibilityChange, relayout, resetScrollResume, resolveTickOptions, retickFromPlaybackClock as retickEngineFromPlaybackClock, scheduleLyricPositionUpdate as scheduleEngineLyricPositionUpdate, tickView, } from "./engine.js";
 import { parseThemeConfig, setThemeSettings } from "./themeSettings.js";
@@ -139,6 +140,21 @@ export function createLyricsRenderer(rendererOptions) {
     let currentLanguage = "";
     const { host, forgetScrollElement } = withHostDefaults(rendererOptions.host, rendererWindow, () => mount);
     const engine = createAnimationEngineInstance(rendererDocument, rendererWindow, host);
+    let imageMediaQueries = [];
+    const refreshImagePaint = () => refreshInstrumentalImages(engine.lyricsContainer, rendererWindow);
+    function syncImagePaint() {
+        if (imageHighlights.getBooleanValue() && imageMediaQueries.length === 0) {
+            imageMediaQueries = ["(dynamic-range: high)", "(forced-colors: active)"].map(query => rendererWindow.matchMedia(query));
+            for (const query of imageMediaQueries)
+                query.addEventListener("change", refreshImagePaint);
+        }
+        else if (!imageHighlights.getBooleanValue()) {
+            for (const query of imageMediaQueries)
+                query.removeEventListener("change", refreshImagePaint);
+            imageMediaQueries = [];
+        }
+        refreshImagePaint();
+    }
     /**
      * Every re-measurement runs through here, which makes it the one place that knows the layout may
      * have moved under the view. The default scroll element is walked once and remembered, so this is
@@ -262,6 +278,7 @@ export function createLyricsRenderer(rendererOptions) {
                 noLyrics: options?.noLyrics ?? false,
                 songwriters: options?.songwriters,
             });
+            syncImagePaint();
             currentLyrics = lyrics;
             currentLanguage = normalizeLanguage(options?.language);
             measure();
@@ -284,6 +301,7 @@ export function createLyricsRenderer(rendererOptions) {
             // the theme it is answering about.
             const needsLyricRebuild = setThemeSettings(parseThemeConfig(css));
             adoptThemeStyleSheet(css);
+            syncImagePaint();
             // Everything the engine resolved off the document was resolved against the theme that just
             // went away.
             clearEngineStyleCaches(engine);
@@ -320,6 +338,9 @@ export function createLyricsRenderer(rendererOptions) {
             createdThemeStyleElement?.remove();
             createdThemeStyleElement = null;
             rendererWindow.removeEventListener("resize", remeasureForViewport);
+            for (const query of imageMediaQueries)
+                query.removeEventListener("change", refreshImagePaint);
+            imageMediaQueries = [];
             engine.destroy();
         },
         noteUserScroll() {

package/dist/styles/image-highlights.css

@@ -0,0 +1,62 @@
+/* The renderer adds these classes only for blyrics-image-highlights = true.
+   An SDR image is equally valid. HDR assets and dynamic-range-limit belong to the theme. */
+.blyrics--word.blyrics-word-highlight.blyrics-image-highlight {
+  background: none;
+  mask: none;
+  -webkit-mask: none;
+  color: transparent;
+}
+.blyrics-image-fill,
+.blyrics-word-highlight.blyrics-image-highlight .blyrics--letter {
+  background-image: var(--blyrics-highlight-image, none);
+  background-color: var(--blyrics-lyric-active-color, white);
+  background-size: 100% 100%;
+  background-repeat: no-repeat;
+  background-clip: text;
+  -webkit-background-clip: text;
+  color: transparent;
+  -webkit-text-fill-color: transparent;
+}
+.blyrics-image-highlight:not(.blyrics-word-highlight--lettered) .blyrics-image-fill {
+  --blyrics-image-sweep-angle: 90deg;
+  mask-image: linear-gradient(var(--blyrics-image-sweep-angle),
+    #000 calc(100% * var(--lyric-transition-amount-start)),
+    transparent calc(100% * var(--lyric-transition-amount-end) + 1px));
+  mask-repeat: no-repeat;
+}
+.blyrics-image-highlight.blyrics-rtl:not(.blyrics-word-highlight--lettered) .blyrics-image-fill {
+  --blyrics-image-sweep-angle: 270deg;
+}
+.blyrics-image-highlight.blyrics-word-highlight--lettered .blyrics-image-fill {
+  background: none;
+}
+.blyrics-image-glow {
+  position: absolute;
+  inset: 0;
+  pointer-events: none;
+  user-select: none;
+  opacity: 0;
+  overflow: visible;
+}
+/* A parallel run reproduces the full inline formatting context, including bidi
+   reordering and every wrapped fragment. No generated text or per-frame measuring. */
+.blyrics-image-glow-run .blyrics-image-glow {
+  position: static;
+  inset: auto;
+  display: inline;
+}
+.blyrics-instrumental-image { display: none; }
+.blyrics--instrumental-icon[data-image-ready] .blyrics-instrumental-image { display: inline; }
+.blyrics--instrumental-icon[data-image-ready] .blyrics-instrumental-color { display: none; }
+@media (forced-colors: active) {
+  .blyrics-image-glow,
+  .blyrics-image-glow-run .blyrics-image-glow { display: none; }
+  .blyrics-image-fill,
+  .blyrics-word-highlight.blyrics-image-highlight .blyrics--letter {
+    background: none;
+    color: CanvasText;
+    -webkit-text-fill-color: CanvasText;
+  }
+  .blyrics--instrumental-icon[data-image-ready] .blyrics-instrumental-image { display: none; }
+  .blyrics--instrumental-icon[data-image-ready] .blyrics-instrumental-color { display: inline; }
+}

package/dist/styles/lyrics.css

@@ -1,3 +1,5 @@
+@import url("image-highlights.css");
+
 /* Resolve the default stack at each language boundary. A root-level var() would freeze
    the host's language-specific fallback before the lyric/translation language is known.
    Theme overrides remain inherited through --blyrics-font-family. */
@@ -122,7 +124,6 @@
 .blyrics-bidi-sensitive .blyrics--word,
 .blyrics-bidi-sensitive .blyrics-word-group:not(.blyrics-word-group-long) .blyrics--word {
 	display: inline;
-	unicode-bidi: normal;
 	white-space: inherit;
 }
 
@@ -170,6 +171,12 @@
 	display: inline-block;
 }
 
+/* Atomic letter boxes otherwise take their visual ordering from the surrounding
+   paragraph. Isolate each word's own dir=auto while keeping it inline/wrappable. */
+.blyrics--word.blyrics-word--lettered {
+	unicode-bidi: isolate;
+}
+
 .blyrics-word-highlight.blyrics-word-highlight--lettered {
 	background-image: none;
 }

package/dist/styles/variables.css

@@ -1,4 +1,9 @@
 :root {
+  /* Optional image paint; themes own the asset and any HDR brightness policy. */
+  --blyrics-highlight-image: none;
+  --blyrics-image-glow-opacity-from: 0.5;
+  --blyrics-image-glow-opacity-to: 0;
+
 	/* Colors */
 	--blyrics-ui-text-color: var(
 		--blyrics-text-color,

package/dist/view.js

@@ -12,6 +12,7 @@
 import { CREDITS_CLASS, CREDITS_NAMES_CLASS, CREDITS_TEXT_CLASS, LINE_CLASS, LYRICS_CLASS, RTL_CLASS, } from "./constants.js";
 import { setupLineCullObserver } from "./engine.js";
 import { addSeekHandler, applyDirection, buildLineSyncedParts, createLyricsLine, deriveSyncType, disableRichsync, findNearestAgent, hideCredits, isNearestLyricRtl, newLineData, } from "./inject.js";
+import { refreshInstrumentalImages } from "./imageHighlights.js";
 import { createInstrumentalElement } from "./instrumental.js";
 import { applyLyricLanguage, resolveLyricLanguages } from "./language.js";
 const INITIAL_SKIP_SCROLLS = 2;
@@ -112,6 +113,7 @@ export function setLyrics(engine, mount, lyrics, options) {
     engine.lines = lines;
     engine.lyricsContainer = container;
     engine.syncType = syncType;
+    refreshInstrumentalImages(container, engine.window);
     // Measured last: the container is in the document, filled, and carrying the attributes CSS
     // sizes it by.
     engine.lyricWidth = container.clientWidth;

package/package.json

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