@braccato/core 1.13.2 → 1.15.0

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

@@ -6,7 +6,6 @@ export declare const INSTRUMENTAL_WAVE_PATH_LOW = "M -4 3 Q 1 4 5 3 Q 10 2 14 3
  * @param doc - Document the SVG nodes are created in
  * @param container - Element to place instrumental parts into
  * @param durationMs - Duration of the instrumental break in milliseconds
- * @param lineIndex - Line index for unique SVG element IDs
  * @returns HTMLDivElement representing the instrumental break
  */
-export declare function createInstrumentalElement(doc: Document, container: HTMLDivElement, durationMs: number, lineIndex: number): HTMLDivElement;
+export declare function createInstrumentalElement(doc: Document, container: HTMLDivElement, durationMs: number): HTMLDivElement;

package/dist/instrumental.js

@@ -1,15 +1,16 @@
+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";
+let nextInstrumentalId = 0;
 /**
  * Creates an HTML element representing an instrumental break in the lyrics.
  *
  * @param doc - Document the SVG nodes are created in
  * @param container - Element to place instrumental parts into
  * @param durationMs - Duration of the instrumental break in milliseconds
- * @param lineIndex - Line index for unique SVG element IDs
  * @returns HTMLDivElement representing the instrumental break
  */
-export function createInstrumentalElement(doc, container, durationMs, lineIndex) {
+export function createInstrumentalElement(doc, container, durationMs) {
     container.classList.add("blyrics--instrumental");
     container.style.setProperty("--blyrics-duration", `${durationMs}ms`);
     const svgNS = "http://www.w3.org/2000/svg";
@@ -17,8 +18,11 @@ export function createInstrumentalElement(doc, container, durationMs, lineIndex)
     svg.classList.add("blyrics--instrumental-icon");
     svg.setAttribute("viewBox", "0 0 24 24");
     const defs = doc.createElementNS(svgNS, "defs");
-    const filterId = `blyrics-glow-${lineIndex}`;
-    const clipId = `blyrics-wave-clip-${lineIndex}`;
+    // Unique per document, not per view: two renderers sharing a document would otherwise resolve
+    // each other's url(#id) references.
+    const idSuffix = nextInstrumentalId++;
+    const filterId = `blyrics-glow-${idSuffix}`;
+    const clipId = `blyrics-wave-clip-${idSuffix}`;
     const filter = doc.createElementNS(svgNS, "filter");
     filter.setAttribute("id", filterId);
     filter.setAttribute("x", "-100%");
@@ -72,7 +76,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";
@@ -111,6 +112,7 @@ export function withHostDefaults(overrides, rendererWindow, currentMount) {
                     currentMount()?.dispatchEvent(new rendererWindow.CustomEvent(SEEK_EVENT, { detail: timeS, bubbles: true }));
                 }),
             log: given.log ?? noop,
+            onStageLayout: given.onStageLayout,
             debug: given.debug,
         },
         forgetScrollElement() {
@@ -138,7 +140,22 @@ export function createLyricsRenderer(rendererOptions) {
     let currentLyrics = [];
     let currentLanguage = "";
     const { host, forgetScrollElement } = withHostDefaults(rendererOptions.host, rendererWindow, () => mount);
-    const engine = createAnimationEngineInstance(rendererDocument, rendererWindow, host);
+    const engine = createAnimationEngineInstance(rendererDocument, rendererWindow, host, rendererOptions.layout ?? "scroll");
+    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 +279,7 @@ export function createLyricsRenderer(rendererOptions) {
                 noLyrics: options?.noLyrics ?? false,
                 songwriters: options?.songwriters,
             });
+            syncImagePaint();
             currentLyrics = lyrics;
             currentLanguage = normalizeLanguage(options?.language);
             measure();
@@ -284,6 +302,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 +339,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/stage.d.ts

@@ -0,0 +1,41 @@
+export type StageItemKind = "line" | "instrumental" | "credits";
+export type StageRole = "current" | "previous" | "queued" | "gone";
+export interface StageItem {
+    kind: StageItemKind;
+    /** Seconds. */
+    start: number;
+    /** Seconds. The credits hold the stage until the song ends, so theirs is infinite. */
+    end: number;
+}
+export declare const STAGE_LEAD_S = 0.5;
+export declare const STAGE_HANDOFF_S = 0.12;
+export declare const STAGE_OVERLAP_S = 0.15;
+export declare function overlapsPrevious(items: readonly StageItem[], index: number): boolean;
+export declare function stageEnterTimes(items: readonly StageItem[]): number[];
+export declare function planStage(items: readonly StageItem[], timeS: number): StageRole[];
+export interface StageMetrics {
+    height: number;
+    left: number;
+    width: number;
+    /** Where the item scales from horizontally: 0 left, 0.5 centre, 1 right. */
+    originX: number;
+}
+export interface StageGeometry {
+    stageHeight: number;
+    gap: number;
+    activeScale: number;
+}
+export interface StagePlacement {
+    y: number;
+    visible: boolean;
+}
+export interface StageBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export declare function layoutStage(roles: readonly StageRole[], items: readonly StageItem[], metrics: readonly StageMetrics[], previousY: readonly (number | null)[], geometry: StageGeometry): {
+    placements: StagePlacement[];
+    box: StageBox | null;
+};

package/dist/stage.js

@@ -0,0 +1,76 @@
+export const STAGE_LEAD_S = 0.5;
+export const STAGE_HANDOFF_S = 0.12;
+export const STAGE_OVERLAP_S = 0.15;
+export function overlapsPrevious(items, index) {
+    const previous = items[index - 1];
+    return previous !== undefined && previous.kind === "line" && items[index].start < previous.end - STAGE_OVERLAP_S;
+}
+export function stageEnterTimes(items) {
+    return items.map((item, index) => {
+        const early = item.start - STAGE_LEAD_S;
+        const previous = items[index - 1];
+        if (previous?.kind !== "line" || overlapsPrevious(items, index))
+            return early;
+        return Math.max(early, Math.min(previous.end, item.start) - STAGE_HANDOFF_S);
+    });
+}
+export function planStage(items, timeS) {
+    const enterTimes = stageEnterTimes(items);
+    let current = -1;
+    enterTimes.forEach((enterTime, index) => {
+        if (enterTime <= timeS)
+            current = index;
+    });
+    const roles = items.map((_, index) => index < current ? "gone" : index > current ? "queued" : "current");
+    if (current < 0)
+        return roles;
+    const previous = items[current - 1];
+    if (previous?.kind === "line" && overlapsPrevious(items, current) && timeS < previous.end) {
+        roles[current - 1] = "previous";
+    }
+    return roles;
+}
+function unionBox(box, next) {
+    if (box === null)
+        return next;
+    const x = Math.min(box.x, next.x);
+    const y = Math.min(box.y, next.y);
+    return {
+        x,
+        y,
+        width: Math.max(box.x + box.width, next.x + next.width) - x,
+        height: Math.max(box.y + box.height, next.y + next.height) - y,
+    };
+}
+export function layoutStage(roles, items, metrics, previousY, geometry) {
+    const { stageHeight, gap } = geometry;
+    const current = roles.indexOf("current");
+    const currentY = current >= 0 ? stageHeight - metrics[current].height : stageHeight;
+    const placements = roles.map((role, index) => {
+        const { height } = metrics[index];
+        switch (role) {
+            case "current":
+                return { y: currentY, visible: true };
+            case "previous":
+                return { y: currentY - gap - height, visible: true };
+            case "queued":
+                return { y: stageHeight - height + gap, visible: false };
+            case "gone":
+                return { y: previousY[index] ?? currentY, visible: false };
+        }
+    });
+    let box = null;
+    roles.forEach((role, index) => {
+        if ((role !== "current" && role !== "previous") || items[index].kind === "instrumental")
+            return;
+        const { height, left, width, originX } = metrics[index];
+        const scale = geometry.activeScale;
+        box = unionBox(box, {
+            x: left + width * originX * (1 - scale),
+            y: placements[index].y + (height * (1 - scale)) / 2,
+            width: width * scale,
+            height: height * scale,
+        });
+    });
+    return { placements, box };
+}

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/stage.css

@@ -0,0 +1,57 @@
+/* Stage layout: lines absolutely placed by the engine, sized to their text. Only layout is set here;
+   colour, type and animation stay with lyrics.css and the theme. */
+.blyrics-container[data-layout="stage"] {
+	position: absolute !important;
+	inset: 0;
+	padding: 0 !important;
+	overflow: visible;
+	pointer-events: none;
+}
+
+.blyrics-container[data-layout="stage"] > :is(.blyrics--line, .blyrics-credits) {
+	position: absolute !important;
+	top: 0;
+	right: 0;
+	left: 0;
+	width: fit-content;
+	max-width: 100%;
+	margin: 0 auto !important;
+	padding: 0.1em 0.25em !important;
+}
+
+/* Layered, so these important declarations outrank any unlayered important one a theme writes,
+   whatever its specificity: the stage alone decides which lines are seen. */
+@layer braccato-stage {
+	.blyrics-container[data-layout="stage"] > :is(.blyrics--line, .blyrics-credits) {
+		opacity: var(--blyrics-stage-opacity, 0) !important;
+	}
+
+	.blyrics-container[data-layout="stage"] > :is(.blyrics--line, .blyrics-credits):not([data-stage-visible]) {
+		visibility: hidden !important;
+	}
+}
+
+.blyrics-container[data-layout="stage"] > :not(.blyrics--line, .blyrics-credits) {
+	display: none !important;
+}
+
+.blyrics-container[data-layout="stage"] > * {
+	text-align: center;
+	transform-origin: center center !important;
+}
+
+/* A duet puts each singer on their own side, mirrored for right-to-left lines; everyone together
+   stays centred. */
+.blyrics-container[data-layout="stage"][data-stage-duet] > .blyrics--line:not([data-agent="v2"], [data-agent="v3"], [data-agent="v1000"]):not([data-direction="rtl"]),
+.blyrics-container[data-layout="stage"][data-stage-duet] > .blyrics--line:is([data-agent="v2"], [data-agent="v3"])[data-direction="rtl"] {
+	margin: 0 auto 0 0 !important;
+	text-align: left;
+	transform-origin: left center !important;
+}
+
+.blyrics-container[data-layout="stage"][data-stage-duet] > .blyrics--line:is([data-agent="v2"], [data-agent="v3"]):not([data-direction="rtl"]),
+.blyrics-container[data-layout="stage"][data-stage-duet] > .blyrics--line:not([data-agent="v2"], [data-agent="v3"], [data-agent="v1000"])[data-direction="rtl"] {
+	margin: 0 0 0 auto !important;
+	text-align: right;
+	transform-origin: right center !important;
+}

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

@@ -1,6 +1,7 @@
 import type { Lyric, LyricPart, LyricSyncType } from "@braccato/types";
 import type { AnimationTickStatus } from "./engine.js";
 import type { LineData } from "./inject.js";
+import type { StageBox } from "./stage.js";
 import type { SetLyricsOptions } from "./view.js";
 export type { Lyric, LyricPart, LyricSyncType };
 /**
@@ -77,8 +78,15 @@ export interface LyricsRendererHost {
      * Where the view's diagnostics go. The host owns the prefix and whether logging is on at all.
      */
     log(...args: unknown[]): void;
+    /**
+     * Stage layout only. Where the lines being sung sit, in the container's coordinates, or null when
+     * nothing sung is on stage. Called when it changes. A consumer draws its own backdrop from it,
+     * outside the container that themes style.
+     */
+    onStageLayout?(box: StageBox | null): void;
     debug?: LyricsRendererDebugSink;
 }
+export type LyricsLayout = "scroll" | "stage";
 export interface LyricsRendererOptions {
     document: Document;
     window: Window;
@@ -92,6 +100,8 @@ export interface LyricsRendererOptions {
      * nothing at all.
      */
     host?: Partial<LyricsRendererHost>;
+    /** `"scroll"` (default) is the scrolling lyrics view. `"stage"` shows only what is being sung. */
+    layout?: LyricsLayout;
 }
 /**
  * One rendered lyrics view, and everything it takes to keep it measured. The consumer owns the

package/dist/view.js

@@ -12,12 +12,13 @@
 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;
 const SKIP_SCROLL_DECAY_MS = 2000;
 function buildInstrumentalLine(doc, lyricElement, lyrics, lineIndex) {
-    createInstrumentalElement(doc, lyricElement, lyrics[lineIndex].durationMs, lineIndex);
+    createInstrumentalElement(doc, lyricElement, lyrics[lineIndex].durationMs);
     lyricElement.dataset.instrumental = "true";
     const agent = findNearestAgent(lyrics, lineIndex);
     if (agent) {
@@ -105,6 +106,12 @@ export function setLyrics(engine, mount, lyrics, options) {
     engine.skipScrollsDecayTimes = Array.from({ length: INITIAL_SKIP_SCROLLS }, () => Date.now() + SKIP_SCROLL_DECAY_MS);
     engine.scrollResumeTime = 0;
     container.dataset.sync = syncType;
+    if (engine.layout === "stage") {
+        container.dataset.layout = "stage";
+        if (lyrics.some(item => item.agent === "v2" || item.agent === "v3")) {
+            container.dataset.stageDuet = "";
+        }
+    }
     container.dataset.loaderVisible = String(options.loaderVisible);
     if (options.noLyrics) {
         container.dataset.noLyrics = "true";
@@ -112,6 +119,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.15.0",
   "description": "Synchronized lyrics renderer with word-by-word animations",
   "type": "module",
   "license": "MIT",