@braccato/core 1.13.2 → 1.15.0

package/dist/engine.js

@@ -18,6 +18,7 @@
 // that never meet. `themeSettings.ts` holds the third thing under that rule.
 import { ANIMATING_CLASS, CREDITS_CLASS, CURRENT_LYRICS_CLASS, FOOTER_CLASS, LINE_CLASS, PAUSED_CLASS, ROMANIZED_LYRICS_CLASS, RTL_CLASS, TRANSLATED_LYRICS_CLASS, USER_SCROLLING_CLASS, WORD_STATE_ACTIVE, WORD_STATE_ATTR, WORD_STATE_PAST, WORD_STATE_UPCOMING, } from "./constants.js";
 import { INSTRUMENTAL_WAVE_PATH_HIGH, INSTRUMENTAL_WAVE_PATH_LOW } from "./instrumental.js";
+import { layoutStage, planStage } from "./stage.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";
@@ -101,7 +102,7 @@ export function forEveryLiveView(runOperation) {
         runOperation(engine);
     }
 }
-export function createAnimationEngineInstance(engineDocument, engineWindow, host) {
+export function createAnimationEngineInstance(engineDocument, engineWindow, host, layout = "scroll") {
     const reducedMotionQuery = engineWindow.matchMedia(REDUCED_MOTION_QUERY);
     const handleReducedMotionChange = () => clearStyleCaches(engine);
     const engine = {
@@ -153,6 +154,15 @@ export function createAnimationEngineInstance(engineDocument, engineWindow, host
         pendingLyricsUpdateFrame: null,
         learnedAnimationTimingOffsetMs: 0,
         animationTimingVisibilityLogUntil: 0,
+        layout,
+        stageKey: "",
+        stageBox: null,
+        stageMetrics: new Map(),
+        stageY: new Map(),
+        stageMoves: new Map(),
+        stageFades: new Map(),
+        stageBlurs: new Map(),
+        stageFontSize: 16,
         destroy: () => {
             liveEngines.delete(engine);
             reducedMotionQuery.removeEventListener("change", handleReducedMotionChange);
@@ -242,6 +252,7 @@ export function clearOnScreenLyrics(engine) {
     if (!engine.lyricsContainer)
         return false;
     engine.lyricsContainer.replaceChildren();
+    resetStage(engine);
     return true;
 }
 export function hasRenderedLines(engine) {
@@ -289,6 +300,26 @@ export function clearLyrics(engine) {
     engine.creditsFocused = false;
     engine.lyricsContainer = null;
     engine.waveAnimationPool.length = 0;
+    resetStage(engine);
+}
+function resetStage(engine) {
+    for (const animation of [
+        ...engine.stageMoves.values(),
+        ...engine.stageFades.values(),
+        ...engine.stageBlurs.values(),
+    ]) {
+        animation.cancel();
+    }
+    engine.stageMoves.clear();
+    engine.stageFades.clear();
+    engine.stageBlurs.clear();
+    engine.stageMetrics.clear();
+    engine.stageY.clear();
+    engine.stageKey = "";
+    if (engine.stageBox !== null) {
+        engine.stageBox = null;
+        engine.host.onStageLayout?.(null);
+    }
 }
 function resetPartAnimations(part) {
     for (const animation of part.animations) {
@@ -319,6 +350,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 +391,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 +419,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 +704,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 +743,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 +847,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 +880,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 +903,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 +1007,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 +1020,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 +1038,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 +1082,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 +1258,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 +1316,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),
@@ -1425,6 +1516,10 @@ function clearOffscreenLineCulling(engine) {
 export function setupLineCullObserver(engine) {
     engine.lineCullObserver?.disconnect();
     clearOffscreenLineCulling(engine);
+    if (engine.layout === "stage") {
+        engine.lineCullObserver = null;
+        return;
+    }
     const ObserverConstructor = engine.window.IntersectionObserver;
     if (typeof ObserverConstructor !== "function" || engine.lines.length === 0) {
         engine.lineCullObserver = null;
@@ -1841,6 +1936,181 @@ export function resolveTickOptions(options) {
 function resolvePlaybackRate(rate) {
     return rate !== undefined && Number.isFinite(rate) && rate > 0 ? rate : 1;
 }
+// -- Stage layout --------------------------------------------
+const STAGE_MOTION = { durationMs: 380, easing: "cubic-bezier(0.2, 0, 0, 1)" };
+// Read by an important rule in stage.css, so a theme's own important opacity cannot reveal a line
+// the stage is hiding or fading.
+const STAGE_OPACITY_PROPERTY = "--blyrics-stage-opacity";
+const stageOpacityRegistrations = new WeakSet();
+const STAGE_FADE_IN_MS = 300;
+const STAGE_FADE_IN_DELAY_MS = 70;
+const STAGE_FADE_OUT_MS = 220;
+// Lines blur out and in across a handoff, so one reads as turning into the next.
+const STAGE_BLUR = "blur(3px)";
+const STAGE_GAP_EM = 0.32;
+function stageElements(engine) {
+    const elements = [];
+    const items = [];
+    let lastEnd = 0;
+    for (const line of engine.lines) {
+        const end = line.time + line.duration;
+        lastEnd = Math.max(lastEnd, end);
+        elements.push(line.lyricElement);
+        items.push({
+            kind: line.lyricElement.dataset.instrumental === "true" ? "instrumental" : "line",
+            start: line.time,
+            end,
+        });
+    }
+    const credits = engine.lyricsContainer?.querySelector(`:scope > .${CREDITS_CLASS}`);
+    if (credits) {
+        elements.push(credits);
+        items.push({ kind: "credits", start: lastEnd, end: Number.POSITIVE_INFINITY });
+    }
+    return { elements, items };
+}
+function originXOf(engine, element) {
+    const align = engine.window.getComputedStyle(element).textAlign;
+    if (align === "center")
+        return 0.5;
+    if (align === "right" || align === "end")
+        return 1;
+    return 0;
+}
+export function measureStage(engine) {
+    engine.stageMetrics.clear();
+    const container = engine.lyricsContainer;
+    if (!container)
+        return;
+    engine.stageFontSize = Number.parseFloat(engine.window.getComputedStyle(container).fontSize) || 16;
+    for (const element of stageElements(engine).elements) {
+        engine.stageMetrics.set(element, {
+            height: element.offsetHeight,
+            left: element.offsetLeft,
+            width: element.offsetWidth,
+            originX: originXOf(engine, element),
+        });
+    }
+    engine.stageKey = "";
+}
+function currentTranslateY(engine, element, fallback) {
+    const parts = engine.window.getComputedStyle(element).translate.split(" ");
+    const y = Number.parseFloat(parts[1] ?? "");
+    return Number.isFinite(y) ? y : fallback;
+}
+function placeStageElement(engine, { element, placement, wasVisible, fromY, fromOpacity }, instant, reduced) {
+    engine.stageMoves.get(element)?.cancel();
+    engine.stageFades.get(element)?.cancel();
+    const moveMs = instant || reduced ? 0 : STAGE_MOTION.durationMs;
+    engine.stageMoves.set(element, element.animate([{ translate: `0 ${fromY}px` }, { translate: `0 ${placement.y}px` }], {
+        duration: moveMs,
+        easing: STAGE_MOTION.easing,
+        fill: "forwards",
+    }));
+    const fadeMs = instant ? 0 : placement.visible ? STAGE_FADE_IN_MS : STAGE_FADE_OUT_MS;
+    if (placement.visible)
+        element.dataset.stageVisible = "";
+    else if (fadeMs === 0)
+        delete element.dataset.stageVisible;
+    const fade = element.animate([{ [STAGE_OPACITY_PROPERTY]: fromOpacity }, { [STAGE_OPACITY_PROPERTY]: placement.visible ? 1 : 0 }], {
+        duration: fadeMs,
+        delay: placement.visible && !instant ? STAGE_FADE_IN_DELAY_MS : 0,
+        easing: placement.visible ? "ease-out" : "ease",
+        // Backwards too: the fade replaces one that was cancelled, and through its delay the line would
+        // otherwise drop to the stylesheet's resting opacity of zero.
+        fill: "both",
+    });
+    if (!placement.visible && fadeMs > 0) {
+        fade.onfinish = () => {
+            if (engine.stageFades.get(element) === fade)
+                delete element.dataset.stageVisible;
+        };
+    }
+    engine.stageFades.set(element, fade);
+    engine.stageY.set(element, placement.y);
+    engine.stageBlurs.get(element)?.cancel();
+    engine.stageBlurs.delete(element);
+    if (fadeMs === 0 || reduced || wasVisible === placement.visible)
+        return;
+    const blurs = ["none", STAGE_BLUR];
+    engine.stageBlurs.set(element, element.animate((placement.visible ? blurs.reverse() : blurs).map(filter => ({ filter })), {
+        duration: fadeMs,
+        delay: placement.visible ? STAGE_FADE_IN_DELAY_MS : 0,
+        easing: placement.visible ? "ease-out" : "ease",
+        // Added to the theme's own filter rather than replacing it, and held only until the line is in focus.
+        composite: "add",
+        fill: placement.visible ? "backwards" : "forwards",
+    }));
+}
+// Registered from script rather than with @property, which Firefox ignores in a stylesheet
+// cross-origin to the document. Unregistered, the fade would snap instead of interpolating.
+function registerStageOpacity(engine) {
+    const css = engine.window.CSS;
+    if (stageOpacityRegistrations.has(engine.window) || typeof css?.registerProperty !== "function")
+        return;
+    stageOpacityRegistrations.add(engine.window);
+    try {
+        css.registerProperty({ name: STAGE_OPACITY_PROPERTY, syntax: "<number>", inherits: false, initialValue: "0" });
+    }
+    catch (error) {
+        engine.host.log("Stage opacity property was already registered", error);
+    }
+}
+function isStageRoleVisible(role) {
+    return role !== "queued" && role !== "gone";
+}
+function sameBox(a, b) {
+    if (a === null || b === null)
+        return a === b;
+    return a.x === b.x && a.y === b.y && a.width === b.width && a.height === b.height;
+}
+function applyStage(engine, timeS, instant) {
+    const container = engine.lyricsContainer;
+    if (!container)
+        return;
+    registerStageOpacity(engine);
+    const { elements, items } = stageElements(engine);
+    const roles = planStage(items, timeS);
+    const key = roles.join(",");
+    if (key === engine.stageKey && !instant)
+        return;
+    engine.stageKey = key;
+    const metrics = elements.map(element => engine.stageMetrics.get(element) ?? { height: 0, left: 0, width: 0, originX: 0 });
+    const { placements, box } = layoutStage(roles, items, metrics, elements.map(element => engine.stageY.get(element) ?? null), {
+        stageHeight: container.clientHeight,
+        gap: engine.stageFontSize * STAGE_GAP_EM,
+        activeScale: getCSSNumber(engine, container, "--blyrics-active-scale", 1),
+    });
+    // Only the elements whose place changed move. A line that stays where it is keeps its running
+    // animations, and one already hidden stays hidden without being animated again.
+    const moves = [];
+    elements.forEach((element, index) => {
+        const placement = placements[index];
+        const previousY = engine.stageY.get(element);
+        const wasVisible = element.dataset.stageRole !== undefined && isStageRoleVisible(element.dataset.stageRole);
+        const unchanged = previousY !== undefined && wasVisible === placement.visible && (!placement.visible || previousY === placement.y);
+        if (unchanged && !instant)
+            return;
+        moves.push({
+            element,
+            placement,
+            wasVisible,
+            fromY: currentTranslateY(engine, element, previousY ?? placement.y),
+            fromOpacity: Number(engine.window.getComputedStyle(element).opacity) || 0,
+        });
+    });
+    const reduced = engine.window.matchMedia(REDUCED_MOTION_QUERY).matches;
+    elements.forEach((element, index) => {
+        if (element.dataset.stageRole !== roles[index])
+            element.dataset.stageRole = roles[index];
+    });
+    for (const move of moves)
+        placeStageElement(engine, move, instant, reduced);
+    if (!sameBox(box, engine.stageBox)) {
+        engine.stageBox = box;
+        engine.host.onStageLayout?.(box);
+    }
+}
 /**
  * Renders one view against a tick with nothing left out.
  */
@@ -1860,6 +2130,9 @@ export function tickView(engine, currentTime, options) {
         return "ok";
     }
     if (hasUnsyncedLyrics(engine)) {
+        // The stage shows lines by their time, and unsynced lines have none.
+        if (engine.layout === "stage")
+            return "ok";
         if (!playbackClock.lastPlayState && isPlaying) {
             engine.scrollResumeTime = 0;
         }
@@ -1909,19 +2182,22 @@ export function tickView(engine, currentTime, options) {
             getCSSDurationInMs(engine, lyricsElement, "--blyrics-scroll-timing-offset") / 1000;
         const { config: animationConfig, scrollTiming } = getAnimationSettings(engine, lyricsElement);
         // Read layout values before the loop writes class changes, to avoid forced reflow
-        const tabRenderer = engine.host.getScrollElement();
-        if (!tabRenderer) {
+        const isStage = engine.layout === "stage";
+        const tabRenderer = isStage ? null : engine.host.getScrollElement();
+        if (!isStage && !tabRenderer) {
             clearVisibleLyricWillChange(engine);
             return "ok";
         }
-        if (tabRenderer !== engine.observedTabRenderer) {
+        if (tabRenderer && tabRenderer !== engine.observedTabRenderer) {
             setupTabRendererObserver(engine, tabRenderer);
         }
-        const tabRendererHeight = engine.cachedTabRendererHeight ?? tabRenderer.getBoundingClientRect().height;
+        const tabRendererHeight = tabRenderer
+            ? (engine.cachedTabRendererHeight ?? tabRenderer.getBoundingClientRect().height)
+            : 0;
         // Read before the loop's class writes so this layout read is batched and forces no mid-frame reflow.
-        let scrollTop = tabRenderer.scrollTop;
-        const maxScrollTop = Math.max(0, tabRenderer.scrollHeight - tabRenderer.clientHeight);
-        if (animationConfig.enabled.scroll) {
+        let scrollTop = tabRenderer?.scrollTop ?? 0;
+        const maxScrollTop = tabRenderer ? Math.max(0, tabRenderer.scrollHeight - tabRenderer.clientHeight) : 0;
+        if (!isStage && animationConfig.enabled.scroll) {
             updateVisibleLyricWillChange(engine, lines, scrollTop, engine.pendingLineScroll?.toScrollTop ?? scrollTop, tabRendererHeight);
         }
         else {
@@ -2064,6 +2340,11 @@ export function tickView(engine, currentTime, options) {
                 delete lyricsElement.dataset.creditsFocused;
             newLyricSelected = true;
         }
+        if (isStage || !tabRenderer) {
+            if (isStage)
+                applyStage(engine, currentTime, timeJumped);
+            return "ok";
+        }
         if (engine.scrollResumeTime < Date.now() || engine.scrollPos === -1) {
             if (activeElems.length == 0) {
                 activeElems.push(lines[0]);
@@ -2292,6 +2573,13 @@ function applyScrollPadding(engine) {
  *   nothing to work from once rendering resumes.
  */
 export function relayout(engine, measureLines) {
+    if (engine.layout === "stage") {
+        if (!measureLines || !engine.lyricsContainer)
+            return;
+        engine.cachedCreditsItem = measureTrailingItem(engine.lyricsContainer, CREDITS_CLASS);
+        measureStage(engine);
+        return;
+    }
     applyScrollPadding(engine);
     const scrollElement = engine.host.getScrollElement();
     if (scrollElement)
@@ -2348,7 +2636,7 @@ function lineDecorators(lineElement) {
  */
 function captureDecorationSlide(engine) {
     const container = engine.lyricsContainer;
-    if (!container || !decorationSlideAllowed(engine, container))
+    if (!container || engine.layout === "stage" || !decorationSlideAllowed(engine, container))
         return null;
     const before = engine.lines.map(line => ({
         line,

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/index.d.ts

@@ -10,3 +10,7 @@ export type { PartData } from "./inject.js";
 export type { LyricPart, LyricsRendererDebugSink, LyricsRendererOptions, LyricSyncType } from "./types.js";
 /** @public */
 export type { SetLyricsOptions } from "./view.js";
+/** @public */
+export type { LyricsLayout } from "./types.js";
+/** @public */
+export type { StageBox } from "./stage.js";