@braccato/core 1.3.0 → 1.5.0

package/README.md

@@ -186,6 +186,33 @@ frequency. Both must use the same commands in the same order with the same numbe
 browser only interpolates two paths smoothly when their command sequences match, and a mismatched
 pair snaps at the halfway point instead of flowing.
 
+### Letter wave (experimental)
+
+On by default; a theme opts out with `/* blyrics-letter-wave = false; */`. It splits every word into
+per-letter spans and, as the word is sung, floats each letter up and eases it most of the way back on
+a small stagger, so a wave travels through the word. It layers on top of the word wobble rather than
+replacing it: the word keeps whatever `--blyrics-word-wobble-*` does and the letters ride on top, so
+it composes with the default `scaleX` pop and reduces to just the letters when a theme sets its wobble
+to identity. It follows `--blyrics-animate-word-wobble`, so reduced motion turns it off with the rest.
+
+A word held past `blyrics-long-word-threshold` (the same `data-long-word` the glow keys off) also
+swells each letter with a transient scale at the crest.
+
+```css
+.blyrics-container {
+  --blyrics-letter-wave-transform: translateY(-0.05em); /* crest lift */
+  --blyrics-letter-wave-settle: translateY(-0.02em); /* rest the crest eases back to */
+  --blyrics-letter-wave-emphasis-scale: 1.11; /* long-word letter swell, 1 turns it off */
+  --blyrics-letter-wave-duration: 0.9s;
+  --blyrics-letter-wave-rise-easing: ease-in-out;
+  --blyrics-letter-wave-fall-easing: ease-out;
+}
+```
+
+The split multiplies the DOM per character and reruns the karaoke sweep per letter, so a theme that
+does not want the cost turns it off with `/* blyrics-letter-wave = false; */`. `blyrics-letter-wave`
+reloads the lines when it changes, the way every build-time setting does.
+
 ### Class names
 
 These are published API rather than implementation. Renaming one costs a migration rather than a
@@ -235,7 +262,11 @@ package's stylesheets are yours to load for the same reason.
 `@braccato/core` is the facade and registers nothing. `createLyricsRenderer(options)` returns one
 `LyricsRenderer`: give it lyrics, tick it, and it owns the DOM it builds and every re-measurement
 that DOM needs. `resetPlaybackClock`, `resumeAllAutoscroll`, `injectRomanization` and
-`injectTranslation` are published beside it, for what one instance cannot answer for on its own.
+`injectTranslation` are published beside it, for what one instance cannot answer for on its own. Hang
+one onto a built line and call `renderer.scheduleLyricPositionUpdate` the way you already would to
+catch the layout up: the hung line floats into place while the lines around it slide to make room,
+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.
 
 `@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.

package/dist/README.md

@@ -186,6 +186,33 @@ frequency. Both must use the same commands in the same order with the same numbe
 browser only interpolates two paths smoothly when their command sequences match, and a mismatched
 pair snaps at the halfway point instead of flowing.
 
+### Letter wave (experimental)
+
+On by default; a theme opts out with `/* blyrics-letter-wave = false; */`. It splits every word into
+per-letter spans and, as the word is sung, floats each letter up and eases it most of the way back on
+a small stagger, so a wave travels through the word. It layers on top of the word wobble rather than
+replacing it: the word keeps whatever `--blyrics-word-wobble-*` does and the letters ride on top, so
+it composes with the default `scaleX` pop and reduces to just the letters when a theme sets its wobble
+to identity. It follows `--blyrics-animate-word-wobble`, so reduced motion turns it off with the rest.
+
+A word held past `blyrics-long-word-threshold` (the same `data-long-word` the glow keys off) also
+swells each letter with a transient scale at the crest.
+
+```css
+.blyrics-container {
+  --blyrics-letter-wave-transform: translateY(-0.05em); /* crest lift */
+  --blyrics-letter-wave-settle: translateY(-0.02em); /* rest the crest eases back to */
+  --blyrics-letter-wave-emphasis-scale: 1.11; /* long-word letter swell, 1 turns it off */
+  --blyrics-letter-wave-duration: 0.9s;
+  --blyrics-letter-wave-rise-easing: ease-in-out;
+  --blyrics-letter-wave-fall-easing: ease-out;
+}
+```
+
+The split multiplies the DOM per character and reruns the karaoke sweep per letter, so a theme that
+does not want the cost turns it off with `/* blyrics-letter-wave = false; */`. `blyrics-letter-wave`
+reloads the lines when it changes, the way every build-time setting does.
+
 ### Class names
 
 These are published API rather than implementation. Renaming one costs a migration rather than a
@@ -235,7 +262,11 @@ package's stylesheets are yours to load for the same reason.
 `@braccato/core` is the facade and registers nothing. `createLyricsRenderer(options)` returns one
 `LyricsRenderer`: give it lyrics, tick it, and it owns the DOM it builds and every re-measurement
 that DOM needs. `resetPlaybackClock`, `resumeAllAutoscroll`, `injectRomanization` and
-`injectTranslation` are published beside it, for what one instance cannot answer for on its own.
+`injectTranslation` are published beside it, for what one instance cannot answer for on its own. Hang
+one onto a built line and call `renderer.scheduleLyricPositionUpdate` the way you already would to
+catch the layout up: the hung line floats into place while the lines around it slide to make room,
+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.
 
 `@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.

package/dist/constants.d.ts

@@ -2,6 +2,7 @@ export declare const LYRICS_WRAPPER_ID: "blyrics-wrapper";
 export declare const LYRICS_CLASS: "blyrics-container";
 export declare const LINE_CLASS: "blyrics--line";
 export declare const WORD_CLASS: "blyrics--word";
+export declare const LETTER_CLASS: "blyrics--letter";
 export declare const FOOTER_CLASS: "blyrics-footer";
 export declare const CURRENT_LYRICS_CLASS: "blyrics--active";
 export declare const ANIMATING_CLASS: "blyrics--animating";

package/dist/constants.js

@@ -5,6 +5,7 @@ export const LYRICS_WRAPPER_ID = "blyrics-wrapper";
 export const LYRICS_CLASS = "blyrics-container";
 export const LINE_CLASS = "blyrics--line";
 export const WORD_CLASS = "blyrics--word";
+export const LETTER_CLASS = "blyrics--letter";
 export const FOOTER_CLASS = "blyrics-footer";
 // -- Playback state --------------------------------------------
 export const CURRENT_LYRICS_CLASS = "blyrics--active";

package/dist/engine.d.ts

@@ -175,6 +175,14 @@ interface AnimationConfig {
         wobblePeakOffset: number;
         wobbleSettleOffset: number;
     };
+    letterWave: {
+        transform: string;
+        settle: string;
+        emphasisScale: string;
+        durationMs: number;
+        riseEasing: string;
+        fallEasing: string;
+    };
     instrumental: {
         fillFadeDurationMs: number;
         fillFadeEasing: string;

package/dist/engine.js

@@ -16,7 +16,7 @@
 // playback clock the last tick wrote. Their unit is a bundle rather than a document, and this
 // module is bundled into the isolated world and the page world separately, so those are two clocks
 // that never meet. `themeSettings.ts` holds the third thing under that rule.
-import { ANIMATING_CLASS, CURRENT_LYRICS_CLASS, FOOTER_CLASS, LINE_CLASS, PAUSED_CLASS, USER_SCROLLING_CLASS, } from "./constants.js";
+import { ANIMATING_CLASS, CURRENT_LYRICS_CLASS, FOOTER_CLASS, LINE_CLASS, PAUSED_CLASS, ROMANIZED_LYRICS_CLASS, TRANSLATED_LYRICS_CLASS, USER_SCROLLING_CLASS, } from "./constants.js";
 import { INSTRUMENTAL_WAVE_PATH_HIGH, INSTRUMENTAL_WAVE_PATH_LOW } from "./instrumental.js";
 import { registerThemeSetting } from "./themeSettings.js";
 import { clamp, getRelativeLayoutBounds, positiveModulo, roundedMs, toMs } from "./util.js";
@@ -755,9 +755,6 @@ function startWordAnimations(engine, part, config, currentTime, appliedTimingOff
                 offset: config.word.wobblePeakOffset,
                 easing: config.word.wobblePeakEasing,
             },
-            // The two offsets are read and clamped independently, so a theme is free to settle
-            // before it peaks. animate() rejects offsets that go backwards, and that throw would
-            // orphan the highlight animations above, which are not tracked until the end.
             {
                 transform: config.word.wobbleSettle,
                 offset: Math.max(config.word.wobblePeakOffset, config.word.wobbleSettleOffset),
@@ -770,8 +767,6 @@ function startWordAnimations(engine, part, config, currentTime, appliedTimingOff
             fill: "forwards",
         };
         const wobbleStartMs = correctedAnimationTimeMs(wordTimeMs, appliedTimingOffsetMs, config.word.wobbleDurationMs);
-        // The wobble is a paint transform, so the highlight copy must carry it too or the active
-        // sweep drifts off the word.
         for (const wordElement of [part.lyricElement, part.highlightElement]) {
             const animation = trackLyricAnimationTiming(engine, wordElement.animate(wobbleKeyframes, wobbleOptions), {
                 appliedTimingOffsetMs,
@@ -780,6 +775,40 @@ function startWordAnimations(engine, part, config, currentTime, appliedTimingOff
             animation.currentTime = wobbleStartMs;
             wobbleAnimations.push(animation);
         }
+        const letters = part.letterElements;
+        if (letters && letters.length > 0) {
+            const emphasise = part.lyricElement?.dataset.longWord === "true";
+            const emphasisPeak = emphasise ? ` scale(${config.letterWave.emphasisScale})` : "";
+            const emphasisRest = emphasise ? " scale(1)" : "";
+            const floatKeyframes = [
+                { transform: `translateY(0)${emphasisRest}`, easing: config.letterWave.riseEasing },
+                {
+                    transform: `${config.letterWave.transform}${emphasisPeak}`,
+                    offset: 0.4,
+                    easing: config.letterWave.fallEasing,
+                },
+                { transform: `${config.letterWave.settle}${emphasisRest}` },
+            ];
+            const letterCount = letters.length;
+            const staggerMs = timedDurationMs > 0 ? timedDurationMs / 2.5 / letterCount : 0;
+            const cascadeDurationMs = config.letterWave.durationMs + (letterCount - 1) * staggerMs;
+            const floatStartMs = correctedAnimationTimeMs(wordTimeMs, appliedTimingOffsetMs, cascadeDurationMs);
+            for (const set of [part.letterElements, part.highlightLetterElements]) {
+                set?.forEach((letterElement, index) => {
+                    const options = {
+                        duration: config.letterWave.durationMs,
+                        delay: index * staggerMs,
+                        fill: "forwards",
+                    };
+                    const animation = trackLyricAnimationTiming(engine, letterElement.animate(floatKeyframes, options), {
+                        appliedTimingOffsetMs,
+                        offsetMs: 0,
+                    });
+                    animation.currentTime = floatStartMs;
+                    wobbleAnimations.push(animation);
+                });
+            }
+        }
     }
     part.animations = [...highlightAnimations.animations, ...wobbleAnimations];
 }
@@ -1007,6 +1036,14 @@ function readAnimationConfig(engine, lyricsElement) {
             wobblePeakOffset: getCSSOffset(engine, lyricsElement, "--blyrics-word-wobble-peak-offset", 0.125),
             wobbleSettleOffset: getCSSOffset(engine, lyricsElement, "--blyrics-word-wobble-settle-offset", 0.75),
         },
+        letterWave: {
+            transform: getCSSValue(engine, lyricsElement, "--blyrics-letter-wave-transform", "translateY(-0.06em)"),
+            settle: getCSSValue(engine, lyricsElement, "--blyrics-letter-wave-settle", "translateY(-0.05em)"),
+            emphasisScale: getCSSValue(engine, lyricsElement, "--blyrics-letter-wave-emphasis-scale", "1.08"),
+            durationMs: getCSSDurationWithFallback(engine, lyricsElement, "--blyrics-letter-wave-duration", "0.9s"),
+            riseEasing: getCSSValue(engine, lyricsElement, "--blyrics-letter-wave-rise-easing", "ease-in-out"),
+            fallEasing: getCSSValue(engine, lyricsElement, "--blyrics-letter-wave-fall-easing", "ease-in-out"),
+        },
         instrumental: {
             fillFadeDurationMs: getCSSDurationWithFallback(engine, lyricsElement, "--blyrics-instrumental-fill-fade-duration", "150ms"),
             fillFadeEasing: getCSSValue(engine, lyricsElement, "--blyrics-instrumental-fill-fade-easing", "ease"),
@@ -1930,10 +1967,61 @@ export function relayout(engine, measureLines) {
         const bounds = getRelativeLayoutBounds(lyricsElement, line.lyricElement);
         line.position = bounds.y;
         line.height = bounds.height;
+        line.decorations = new Map(lineDecorators(line.lyricElement).map(element => [element, getRelativeLayoutBounds(lyricsElement, element).y]));
     }
     engine.wasUserScrolling = true; // trigger rescrolls
     engine.host.debug?.resize();
 }
+// -- Decoration slide --------------------------
+const DECORATION_SLIDE_MS = 350;
+const DECORATION_SLIDE_EASING = "cubic-bezier(0.25, 1, 0.5, 1)";
+const DECORATION_MIN_SHIFT_PX = 0.5;
+function slideElementBy(element, dy) {
+    element.animate({ translate: [`0 ${dy}px`, "0 0"] }, { duration: DECORATION_SLIDE_MS, easing: DECORATION_SLIDE_EASING, composite: "add" });
+}
+function decorationSlideAllowed(engine, container) {
+    if (engine.window.matchMedia(REDUCED_MOTION_QUERY).matches)
+        return false;
+    return (engine.window.getComputedStyle(container).getPropertyValue("--blyrics-animate-decoration-entry").trim() !== "0");
+}
+function lineDecorators(lineElement) {
+    return [
+        ...lineElement.querySelectorAll(`.${ROMANIZED_LYRICS_CLASS}`),
+        ...lineElement.querySelectorAll(`.${TRANSLATED_LYRICS_CLASS}`),
+    ];
+}
+/**
+ * Snapshots where the lines and their decorators sit now, so the remeasure that follows can slide
+ * each one from there to wherever a streamed decoration just pushed it. Returns null when nothing
+ * should animate, and otherwise a function to call once the new layout is measured: the line rides
+ * its own shift and a decorator rides only the part of its shift its line did not already carry, so
+ * a survivor whose line held still still slides into the gap a removed sibling left.
+ */
+function captureDecorationSlide(engine) {
+    const container = engine.lyricsContainer;
+    if (!container || !decorationSlideAllowed(engine, container))
+        return null;
+    const before = engine.lines.map(line => ({
+        line,
+        position: line.position,
+        decorations: new Map(line.decorations),
+    }));
+    return () => {
+        for (const { line, position, decorations } of before) {
+            const lineShift = position - line.position;
+            if (Math.abs(lineShift) >= DECORATION_MIN_SHIFT_PX)
+                slideElementBy(line.lyricElement, lineShift);
+            for (const [element, was] of decorations) {
+                const now = line.decorations.get(element);
+                if (now === undefined)
+                    continue;
+                const shift = was - now - lineShift;
+                if (Math.abs(shift) >= DECORATION_MIN_SHIFT_PX)
+                    slideElementBy(element, shift);
+            }
+        }
+    };
+}
 // -- Debounced Lyrics Update --------------------------
 function cancelLyricPositionUpdate(engine) {
     if (engine.pendingLyricsUpdateFrame === null)
@@ -1971,7 +2059,9 @@ export function scheduleLyricPositionUpdate(engine, isViewRendering, retick) {
     engine.pendingLyricsUpdateFrame = engine.window.requestAnimationFrame(() => {
         engine.pendingLyricsUpdateFrame = null;
         const isRendering = isViewRendering();
+        const playSlide = isRendering ? captureDecorationSlide(engine) : null;
         relayout(engine, isRendering);
+        playSlide?.();
         if (!isRendering)
             return;
         retick();

package/dist/inject.d.ts

@@ -17,6 +17,8 @@ export interface AnimationData {
 }
 export interface PartData extends AnimationData {
     highlightElement: HTMLElement;
+    letterElements?: HTMLElement[];
+    highlightLetterElements?: HTMLElement[];
 }
 export type LineData = {
     parts: PartData[];
@@ -28,6 +30,7 @@ export type LineData = {
     isSelected: boolean;
     height: number;
     position: number;
+    decorations: Map<HTMLElement, number>;
 } & AnimationData;
 export declare function newLineData(lyricElement: HTMLElement, startTimeMs: number, durationMs: number): LineData;
 export declare function applyDirection(element: HTMLElement, text: string): void;

package/dist/inject.js

@@ -11,7 +11,7 @@
 // animates is one word, so every part is split on whitespace with its timing pro-rated across the
 // split by character count. A line that arrives with no timed parts at all is rebuilt the same way
 // into zero duration words, so line synced lyrics reach the DOM the sweep already knows.
-import { BACKGROUND_LINE_CLASS, BACKGROUND_LYRIC_CLASS, BIDI_RUN_CLASS, BIDI_SENSITIVE_CLASS, CONTENT_LINE_CLASS, EXPLICIT_WORD_CLASS, HIGHLIGHT_RUN_CLASS, LINE_MAIN_CLASS, LINE_SYNCED_WORD_CLASS, LONG_WORD_GROUP_CLASS, ROMANIZED_LYRICS_CLASS, RTL_CLASS, TRANSLATED_LYRICS_CLASS, WORD_CLASS, WORD_GROUP_CLASS, WORD_HIGHLIGHT_CLASS, ZERO_DURATION_ANIMATION_CLASS, } from "./constants.js";
+import { 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, ZERO_DURATION_ANIMATION_CLASS, } from "./constants.js";
 import { getSeekTimeFromClick } from "./seek.js";
 import { testRtl } from "./text.js";
 import { registerThemeSetting } from "./themeSettings.js";
@@ -19,6 +19,7 @@ export let disableRichsync = registerThemeSetting("blyrics-disable-richsync", fa
 let lineSyncedAnimationDelay = registerThemeSetting("blyrics-line-synced-animation-delay", 50, true);
 let longWordThreshold = registerThemeSetting("blyrics-long-word-threshold", 1500, true);
 let longWordWrapThreshold = registerThemeSetting("blyrics-long-word-wrap-threshold", 10, true);
+let letterWave = registerThemeSetting("blyrics-letter-wave", true, true);
 const RTL_SCRIPT_REGEX = /[\p{Script=Arabic}\p{Script=Hebrew}\p{Script=Syriac}\p{Script=Thaana}]/u;
 const LTR_SCRIPT_REGEX = /[\p{Script=Latin}\p{Script=Greek}\p{Script=Cyrillic}\p{Script=Han}\p{Script=Hangul}\p{Script=Hiragana}\p{Script=Katakana}]/u;
 const SPACE_REGEX = /^\s+$/u;
@@ -60,12 +61,14 @@ export function deriveSyncType(lyrics) {
         return "richsync";
     return lyrics.every(item => item.startTimeMs === 0) ? "none" : "synced";
 }
-function newPartData(part, span, highlight) {
+function newPartData(part, span, highlight, letterElements, highlightLetterElements) {
     return {
         time: part.startTimeMs / 1000,
         duration: part.durationMs / 1000,
         lyricElement: span,
         highlightElement: highlight,
+        letterElements,
+        highlightLetterElements,
         animations: [],
     };
 }
@@ -83,6 +86,7 @@ export function newLineData(lyricElement, startTimeMs, durationMs) {
         isSelected: false,
         height: -1,
         position: -1,
+        decorations: new Map(),
         animations: [],
     };
 }
@@ -194,10 +198,24 @@ function appendLongWordBreaks(doc, span, text, threshold) {
     }
     return true;
 }
-function createTimedWordSpan(doc, part, wrapThreshold) {
+function appendLetters(doc, wordElement, text) {
+    const chars = [...text];
+    wordElement.style.setProperty("--letters", String(chars.length));
+    return chars.map((char, index) => {
+        const letter = doc.createElement("span");
+        letter.classList.add(LETTER_CLASS);
+        letter.style.setProperty("--letter-index", String(index));
+        letter.textContent = char;
+        wordElement.appendChild(letter);
+        return letter;
+    });
+}
+function createTimedWordSpan(doc, part, wrapThreshold, perLetter) {
     const span = doc.createElement("span");
     const highlight = doc.createElement("span");
     highlight.classList.add(WORD_HIGHLIGHT_CLASS);
+    let letters;
+    let highlightLetters;
     for (const wordElement of [span, highlight]) {
         wordElement.classList.add(WORD_CLASS);
         wordElement.dir = "auto";
@@ -213,16 +231,26 @@ function createTimedWordSpan(doc, part, wrapThreshold) {
             wordElement.classList.add(BACKGROUND_LYRIC_CLASS);
         if (part.explicit)
             wordElement.classList.add(EXPLICIT_WORD_CLASS);
-        appendLongWordBreaks(doc, wordElement, part.words, wrapThreshold);
+        if (perLetter) {
+            const collected = appendLetters(doc, wordElement, part.words);
+            if (wordElement === span)
+                letters = collected;
+            else
+                highlightLetters = collected;
+        }
+        else {
+            appendLongWordBreaks(doc, wordElement, part.words, wrapThreshold);
+        }
         wordElement.dataset.time = String(part.startTimeMs / 1000);
         wordElement.dataset.duration = String(part.durationMs / 1000);
         wordElement.dataset.content = part.words;
         wordElement.style.setProperty("--blyrics-duration", part.durationMs + "ms");
     }
-    return { span, highlight };
+    return { span, highlight, letters, highlightLetters };
 }
 function createWordGroup(doc, group, lineData) {
     const wrapThreshold = Math.max(1, longWordWrapThreshold.getNumberValue());
+    const perLetter = letterWave.getBooleanValue();
     const lyricGroup = doc.createElement("span");
     const highlightGroup = doc.createElement("span");
     for (const groupElement of [lyricGroup, highlightGroup]) {
@@ -239,8 +267,8 @@ function createWordGroup(doc, group, lineData) {
     for (const token of group.tokens) {
         if (token.kind === "space")
             continue;
-        const { span, highlight } = createTimedWordSpan(doc, token.part, wrapThreshold);
-        lineData.parts.push(newPartData(token.part, span, highlight));
+        const { span, highlight, letters, highlightLetters } = createTimedWordSpan(doc, token.part, wrapThreshold, perLetter);
+        lineData.parts.push(newPartData(token.part, span, highlight, letters, highlightLetters));
         lyricGroup.appendChild(span);
         highlightGroup.appendChild(highlight);
     }

package/dist/styles/lyrics.css

@@ -117,13 +117,13 @@
 
 @property --lyric-transition-amount-start {
 	syntax: "<number>";
-	inherits: false;
+	inherits: true;
 	initial-value: -0.2;
 }
 
 @property --lyric-transition-amount-end {
 	syntax: "<number>";
-	inherits: false;
+	inherits: true;
 	initial-value: -0.1;
 }
 
@@ -157,6 +157,25 @@
 	);
 }
 
+.blyrics--letter {
+	display: inline-block;
+}
+
+.blyrics-word-highlight:has(.blyrics--letter) {
+	background-image: none;
+}
+
+.blyrics-word-highlight .blyrics--letter {
+	background-image: linear-gradient(
+		90deg,
+		var(--blyrics-lyric-active-color)
+			calc(100% * (var(--lyric-transition-amount-start) * var(--letters, 1) - var(--letter-index, 0))),
+		#00000000
+			calc(100% * (var(--lyric-transition-amount-end) * var(--letters, 1) - var(--letter-index, 0)) + 1px)
+	);
+	background-clip: text;
+}
+
 [blyrics-alt-hover] .blyrics--word:hover {
 	text-decoration: underline;
 	text-underline-offset: 0.15em;
@@ -184,6 +203,8 @@
 
 .blyrics--translated,
 .blyrics--romanized {
+	animation: blyrics-decoration-in calc(var(--blyrics-animate-decoration-entry) * 0.35s)
+		cubic-bezier(0.25, 1, 0.5, 1) both;
 	color: var(--blyrics-translated-color);
 	display: block;
 	font-family: var(--blyrics-translated-font-family);
@@ -197,6 +218,13 @@
 	white-space: normal;
 }
 
+@keyframes blyrics-decoration-in {
+	from {
+		opacity: 0;
+		transform: translateY(-0.4em);
+	}
+}
+
 .blyrics--romanized {
 	background: rgba(255, 255, 255, 0.05);
 	border: 1px solid rgba(255, 255, 255, 0.1);

package/dist/styles/variables.css

@@ -63,6 +63,7 @@
 	--blyrics-animate-highlight-fade: 1;
 	--blyrics-animate-scroll: 1;
 	--blyrics-animate-instrumental: 1;
+	--blyrics-animate-decoration-entry: 1;
 
 	--blyrics-loader-transition-duration: 0.6s;
 	--blyrics-loader-transition-easing: cubic-bezier(0.22, 1, 0.36, 1);
@@ -109,6 +110,13 @@
 	--blyrics-word-wobble-peak-easing: ease-in-out;
 	--blyrics-word-wobble-end-easing: ease-out;
 
+	--blyrics-letter-wave-transform: translateY(-0.05em);
+	--blyrics-letter-wave-settle: translateY(-0.02em);
+	--blyrics-letter-wave-emphasis-scale: 1.11;
+	--blyrics-letter-wave-duration: 0.9s;
+	--blyrics-letter-wave-rise-easing: ease-in-out;
+	--blyrics-letter-wave-fall-easing: ease-out;
+
 	--blyrics-instrumental-fill-fade-duration: 150ms;
 	--blyrics-instrumental-fill-fade-easing: ease;
 	--blyrics-instrumental-fill-transform-from: translateY(78%);
@@ -176,6 +184,7 @@
 		--blyrics-animate-line-scale: 0;
 		--blyrics-animate-word-wobble: 0;
 		--blyrics-animate-instrumental: 0;
+		--blyrics-animate-decoration-entry: 0;
 
 		--blyrics-scale: 1;
 		--blyrics-active-scale: 1;

package/dist/types.d.ts

@@ -163,9 +163,14 @@ export interface LyricsRenderer {
      */
     clearOnScreenLyrics(): boolean;
     /**
-     * Re-measures the lines on the next frame and renders the view again against them. The predicate
-     * is the caller's half of whether that frame does anything, and only that half: whether the lines
-     * are on the screen to be measured at all is the renderer's own question, and it asks it itself.
+     * Re-measures the lines on the next frame and renders the view again against them. This is the door
+     * a consumer knocks on after streaming in a translation or romanization, and it is what slides the
+     * lines the new decoration moved from where they were to where it put them, together with any
+     * surviving decorator that shifted within its own line, so the rest of the lyric eases down rather
+     * than jumping. The slide honours reduced motion and `--blyrics-animate-decoration-entry`; with
+     * either off the lines are re-measured with no slide. The predicate is the caller's half of whether
+     * that frame does anything, and only that half: whether the lines are on the screen to be measured
+     * at all is the renderer's own question, and it asks it itself.
      *
      * @param isTicking - Whether whoever drives this view is still driving it, asked on the frame
      *   rather than now. A driver that has stopped is one whose lines may no longer be rendered, and

package/package.json

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