@braccato/core 1.14.0 → 1.15.0

package/README.md

@@ -345,14 +345,15 @@ refactor. Import them from `@braccato/core/constants` instead of typing them out
 
 ## Stylesheets
 
-Three sheets ship with the package, and loading them is yours, the way any package's CSS is. Leave
+Four sheets ship with the package, and loading them is yours, the way any package's CSS is. Leave
 them out and you get lines that are in the document and unstyled, rather than lines that are missing.
 
 | File                                     | What it carries                                                                                                        |
 | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
-| `@braccato/core/styles/variables.css`    | Every `--blyrics-*` default. It goes first, because the other two read from it.                                           |
+| `@braccato/core/styles/variables.css`    | Every `--blyrics-*` default. It goes first, because the others read from it.                                              |
 | `@braccato/core/styles/lyrics.css`       | The container, the lines, the words and the sweep, plus two `@property` registrations the word animation interpolates through. |
 | `@braccato/core/styles/instrumental.css` | The waveform that fills a bar nobody sings over, and the animation that walks it.                                          |
+| `@braccato/core/styles/stage.css`        | Placement for the stage layout, and nothing else. Only a renderer created with `layout: "stage"` needs it.                  |
 
 One thing they do not do for you. The module measures the room the first and last lines need to reach
 the view's target scroll position and writes it on the root as `--blyrics-padding-top` and
@@ -382,6 +383,26 @@ catch the layout up: the hung line floats into place while the lines around it s
 rather than the rest of the lyric jumping down. `--blyrics-animate-decoration-entry` set to `0` drops
 both for an instant insert, and reduced-motion does the same.
 
+`createLyricsRenderer({ layout: "stage" })` builds a view for subtitles over a video: one line at a
+time, and only while it is being sung. It fills its nearest positioned ancestor. There is no scroll
+element to hand it, no scroll padding written and no line culling. Unsynced lyrics show nothing, because
+a stage places lines by their time and unsynced lines have none.
+
+The engine owns where a line is and whether you can see it. It moves each line with a `translate` Web
+Animation and fades it through `--blyrics-stage-opacity`, blurring it slightly on the way in and out so
+one line reads as turning into the next. Each line carries `data-stage-role` (`current`, `previous`,
+`queued` or `gone`) and the container carries `data-layout="stage"`. `stage.css` sets a stage line's
+`opacity` from that property with `!important` inside a cascade layer, and keeps the line
+`visibility: hidden` until it is marked `data-stage-visible`. Layered important declarations outrank
+unlayered ones whatever their specificity, so a theme that forces `opacity: 1 !important` on active
+lines, which some do, can neither reveal a queued line nor hold one that is leaving. In a duet (any line sung by `v2` or `v3`) the
+container also gets `data-stage-duet` and each singer keeps to their side, mirrored for right-to-left
+lines; lines for everyone stay centred.
+
+Everything else is the theme's. Lines are styled exactly as they would be in a scrolling view.
+`host.onStageLayout(box)` reports the box around the sung lines in the container's coordinates, or null
+when nothing sung is on stage, so you can draw a backdrop outside the container the theme styles.
+
 `@braccato/core/element` registers `<braccato-lyrics>`, and `<better-lyrics>` beside it, on import.
 Registration is a side effect, which is why it is entered separately.
 
@@ -429,7 +450,10 @@ swapping `audio.src` between songs without playing goes on reporting the old pos
 
 Two renderers in one document write over each other, so the module supports one. It is a constraint
 rather than a setting, and it is stated rather than enforced: none of the points where two of them
-collide is a crash.
+collide is a crash. A stage renderer is the exception. It writes no scroll padding, so it can sit in
+the same document as a scrolling one, with three rules: give both the same theme, tick both with the
+same time and wall time in the same frame (whichever ticks first is the one that sees a seek), and if
+the stage renderer applied the theme first, destroy it first, because its `<style>` element goes with it.
 
 Two things are written per document and belong to whichever renderer wrote them last: the theme's
 `<style>` element, and the scroll padding on the root. Two more are per bundle, because a settings

package/dist/README.md

@@ -345,14 +345,15 @@ refactor. Import them from `@braccato/core/constants` instead of typing them out
 
 ## Stylesheets
 
-Three sheets ship with the package, and loading them is yours, the way any package's CSS is. Leave
+Four sheets ship with the package, and loading them is yours, the way any package's CSS is. Leave
 them out and you get lines that are in the document and unstyled, rather than lines that are missing.
 
 | File                                     | What it carries                                                                                                        |
 | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
-| `@braccato/core/styles/variables.css`    | Every `--blyrics-*` default. It goes first, because the other two read from it.                                           |
+| `@braccato/core/styles/variables.css`    | Every `--blyrics-*` default. It goes first, because the others read from it.                                              |
 | `@braccato/core/styles/lyrics.css`       | The container, the lines, the words and the sweep, plus two `@property` registrations the word animation interpolates through. |
 | `@braccato/core/styles/instrumental.css` | The waveform that fills a bar nobody sings over, and the animation that walks it.                                          |
+| `@braccato/core/styles/stage.css`        | Placement for the stage layout, and nothing else. Only a renderer created with `layout: "stage"` needs it.                  |
 
 One thing they do not do for you. The module measures the room the first and last lines need to reach
 the view's target scroll position and writes it on the root as `--blyrics-padding-top` and
@@ -382,6 +383,26 @@ catch the layout up: the hung line floats into place while the lines around it s
 rather than the rest of the lyric jumping down. `--blyrics-animate-decoration-entry` set to `0` drops
 both for an instant insert, and reduced-motion does the same.
 
+`createLyricsRenderer({ layout: "stage" })` builds a view for subtitles over a video: one line at a
+time, and only while it is being sung. It fills its nearest positioned ancestor. There is no scroll
+element to hand it, no scroll padding written and no line culling. Unsynced lyrics show nothing, because
+a stage places lines by their time and unsynced lines have none.
+
+The engine owns where a line is and whether you can see it. It moves each line with a `translate` Web
+Animation and fades it through `--blyrics-stage-opacity`, blurring it slightly on the way in and out so
+one line reads as turning into the next. Each line carries `data-stage-role` (`current`, `previous`,
+`queued` or `gone`) and the container carries `data-layout="stage"`. `stage.css` sets a stage line's
+`opacity` from that property with `!important` inside a cascade layer, and keeps the line
+`visibility: hidden` until it is marked `data-stage-visible`. Layered important declarations outrank
+unlayered ones whatever their specificity, so a theme that forces `opacity: 1 !important` on active
+lines, which some do, can neither reveal a queued line nor hold one that is leaving. In a duet (any line sung by `v2` or `v3`) the
+container also gets `data-stage-duet` and each singer keeps to their side, mirrored for right-to-left
+lines; lines for everyone stay centred.
+
+Everything else is the theme's. Lines are styled exactly as they would be in a scrolling view.
+`host.onStageLayout(box)` reports the box around the sung lines in the container's coordinates, or null
+when nothing sung is on stage, so you can draw a backdrop outside the container the theme styles.
+
 `@braccato/core/element` registers `<braccato-lyrics>`, and `<better-lyrics>` beside it, on import.
 Registration is a side effect, which is why it is entered separately.
 
@@ -429,7 +450,10 @@ swapping `audio.src` between songs without playing goes on reporting the old pos
 
 Two renderers in one document write over each other, so the module supports one. It is a constraint
 rather than a setting, and it is stated rather than enforced: none of the points where two of them
-collide is a crash.
+collide is a crash. A stage renderer is the exception. It writes no scroll padding, so it can sit in
+the same document as a scrolling one, with three rules: give both the same theme, tick both with the
+same time and wall time in the same frame (whichever ticks first is the one that sees a seek), and if
+the stage renderer applied the theme first, destroy it first, because its `<style>` element goes with it.
 
 Two things are written per document and belong to whichever renderer wrote them last: the theme's
 `<style>` element, and the scroll padding on the root. Two more are per bundle, because a settings

package/dist/engine.d.ts

@@ -1,5 +1,6 @@
 import type { LineData } from "./inject.js";
-import type { LyricsRendererHost, LyricSyncType, ResolvedTickOptions, TickOptions } from "./types.js";
+import { type StageBox, type StageMetrics } from "./stage.js";
+import type { LyricsLayout, LyricsRendererHost, LyricSyncType, ResolvedTickOptions, TickOptions } from "./types.js";
 /**
  * Everything that belongs to a single rendered lyrics view: one scroll container, one selection,
  * one set of pending scroll work.
@@ -69,6 +70,15 @@ export interface AnimationEngineInstance extends AnimEngineViewState {
     pendingLyricsUpdateFrame: number | null;
     learnedAnimationTimingOffsetMs: number;
     animationTimingVisibilityLogUntil: number;
+    layout: LyricsLayout;
+    stageKey: string;
+    stageBox: StageBox | null;
+    stageMetrics: Map<HTMLElement, StageMetrics>;
+    stageY: Map<HTMLElement, number>;
+    stageMoves: Map<HTMLElement, Animation>;
+    stageFades: Map<HTMLElement, Animation>;
+    stageBlurs: Map<HTMLElement, Animation>;
+    stageFontSize: number;
     /**
      * Releases everything the instance holds on its window: the reduced motion listener, the tab
      * renderer observer and any frame it still has queued.
@@ -80,7 +90,7 @@ export interface AnimationEngineInstance extends AnimEngineViewState {
  * deliberately not used inside the tick, which runs per frame and per line.
  */
 export declare function forEveryLiveView(runOperation: (engine: AnimationEngineInstance) => void): void;
-export declare function createAnimationEngineInstance(engineDocument: Document, engineWindow: EngineWindow, host: LyricsRendererHost): AnimationEngineInstance;
+export declare function createAnimationEngineInstance(engineDocument: Document, engineWindow: EngineWindow, host: LyricsRendererHost, layout?: LyricsLayout): AnimationEngineInstance;
 /**
  * Forgets the last player snapshot, so the next tick is treated as the first one of a new song
  * rather than as a jump away from the previous one.
@@ -338,6 +348,7 @@ export type AnimationTickStatus = "ok" | "lyrics-missing";
  * matching no line at all.
  */
 export declare function resolveTickOptions(options: TickOptions): ResolvedTickOptions;
+export declare function measureStage(engine: AnimationEngineInstance): void;
 /**
  * Renders one view against a tick with nothing left out.
  */

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) {
@@ -1485,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;
@@ -1901,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.
  */
@@ -1920,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;
         }
@@ -1969,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 {
@@ -2124,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]);
@@ -2352,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)
@@ -2408,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/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";

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,16 +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";
@@ -18,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%");

package/dist/renderer.js

@@ -112,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() {
@@ -139,7 +140,7 @@ 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() {

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/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/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

@@ -18,7 +18,7 @@ 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) {
@@ -106,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";

package/package.json

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