@braccato/core 1.4.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

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

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

@@ -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"),

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[];

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: [],
     };
 }
@@ -195,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";
@@ -214,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]) {
@@ -240,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;

package/dist/styles/variables.css

@@ -110,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%);

package/package.json

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