@braccato/core 1.6.3 → 1.7.0

package/README.md

@@ -213,6 +213,31 @@ The split multiplies the DOM per character and reruns the karaoke sweep per lett
 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.
 
+### Word state
+
+The renderer writes `data-word-state` on every word as the song crosses it, so a theme can tell a
+word being sung from one already sung or one not yet reached. It carries `upcoming` before the word
+starts, `active` while it is being sung, and `past` once it has finished, and it is written on both
+layers of a word, the base `.blyrics--word` and its highlight overlay, so a theme can key either. A
+word stays `active` for exactly as long as it is sung, so a transition on the flip is the whole of a
+per-word karaoke effect, the one ramansg/Max-Performance built before the swept overlay.
+
+```css
+.blyrics--word {
+  color: var(--blyrics-lyric-inactive-color);
+  transition: color 180ms ease;
+}
+
+.blyrics--word[data-word-state="active"],
+.blyrics--word[data-word-state="past"] {
+  color: var(--blyrics-lyric-active-color);
+}
+```
+
+It is written only when a word's state changes rather than every frame, so selecting on it costs a
+theme nothing per tick. A line synced word, which has no duration of its own, is `active` from its
+start until the next word begins.
+
 ### Class names
 
 These are published API rather than implementation. Renaming one costs a migration rather than a

package/dist/README.md

@@ -213,6 +213,31 @@ The split multiplies the DOM per character and reruns the karaoke sweep per lett
 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.
 
+### Word state
+
+The renderer writes `data-word-state` on every word as the song crosses it, so a theme can tell a
+word being sung from one already sung or one not yet reached. It carries `upcoming` before the word
+starts, `active` while it is being sung, and `past` once it has finished, and it is written on both
+layers of a word, the base `.blyrics--word` and its highlight overlay, so a theme can key either. A
+word stays `active` for exactly as long as it is sung, so a transition on the flip is the whole of a
+per-word karaoke effect, the one ramansg/Max-Performance built before the swept overlay.
+
+```css
+.blyrics--word {
+  color: var(--blyrics-lyric-inactive-color);
+  transition: color 180ms ease;
+}
+
+.blyrics--word[data-word-state="active"],
+.blyrics--word[data-word-state="past"] {
+  color: var(--blyrics-lyric-active-color);
+}
+```
+
+It is written only when a word's state changes rather than every frame, so selecting on it costs a
+theme nothing per tick. A line synced word, which has no duration of its own, is `active` from its
+start until the next word begins.
+
 ### Class names
 
 These are published API rather than implementation. Renaming one costs a migration rather than a

package/dist/constants.d.ts

@@ -9,6 +9,11 @@ export declare const ANIMATING_CLASS: "blyrics--animating";
 export declare const PAUSED_CLASS: "blyrics--paused";
 export declare const ZERO_DURATION_ANIMATION_CLASS: "blyrics-zero-dur-animate";
 export declare const USER_SCROLLING_CLASS: "blyrics-user-scrolling";
+export declare const WORD_STATE_ATTR: "data-word-state";
+export declare const WORD_STATE_UPCOMING: "upcoming";
+export declare const WORD_STATE_ACTIVE: "active";
+export declare const WORD_STATE_PAST: "past";
+export type WordState = typeof WORD_STATE_UPCOMING | typeof WORD_STATE_ACTIVE | typeof WORD_STATE_PAST;
 export declare const BACKGROUND_LYRIC_CLASS: "blyrics-background-lyric";
 export declare const EXPLICIT_WORD_CLASS: "blyrics-explicit";
 export declare const RTL_CLASS: "blyrics-rtl";

package/dist/constants.js

@@ -13,6 +13,10 @@ export const ANIMATING_CLASS = "blyrics--animating";
 export const PAUSED_CLASS = "blyrics--paused";
 export const ZERO_DURATION_ANIMATION_CLASS = "blyrics-zero-dur-animate";
 export const USER_SCROLLING_CLASS = "blyrics-user-scrolling";
+export const WORD_STATE_ATTR = "data-word-state";
+export const WORD_STATE_UPCOMING = "upcoming";
+export const WORD_STATE_ACTIVE = "active";
+export const WORD_STATE_PAST = "past";
 // -- Line and word variants --------------------------------------------
 export const BACKGROUND_LYRIC_CLASS = "blyrics-background-lyric";
 export const EXPLICIT_WORD_CLASS = "blyrics-explicit";

package/dist/engine.d.ts

@@ -127,6 +127,7 @@ export declare function getRenderedSyncType(engine: AnimationEngineInstance): Ly
  * hold are released along with it.
  */
 export declare function clearLyrics(engine: AnimationEngineInstance): void;
+export declare function updateWordStates(lineData: LineData, currentTime: number): void;
 type LineScrollSide = "above" | "active" | "below";
 interface LineScrollItem {
     lyricElement: HTMLElement;

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, ROMANIZED_LYRICS_CLASS, RTL_CLASS, TRANSLATED_LYRICS_CLASS, USER_SCROLLING_CLASS, } from "./constants.js";
+import { ANIMATING_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 { registerThemeSetting } from "./themeSettings.js";
 import { clamp, getRelativeLayoutBounds, positiveModulo, roundedMs, toMs } from "./util.js";
@@ -345,6 +345,26 @@ function clearLineStateClasses(lineData) {
         togglePartClass(part, PAUSED_CLASS, false);
     }
 }
+export function updateWordStates(lineData, currentTime) {
+    const parts = lineData.parts;
+    const lineEndTime = lineData.time + lineData.duration;
+    for (let i = 0; i < parts.length; i++) {
+        const part = parts[i];
+        const endTime = part.duration > 0 ? part.time + part.duration : (parts[i + 1]?.time ?? lineEndTime);
+        let state = WORD_STATE_PAST;
+        if (currentTime < part.time) {
+            state = WORD_STATE_UPCOMING;
+        }
+        else if (currentTime < endTime) {
+            state = WORD_STATE_ACTIVE;
+        }
+        if (part.wordState === state)
+            continue;
+        part.wordState = state;
+        part.lyricElement.setAttribute(WORD_STATE_ATTR, state);
+        part.highlightElement.setAttribute(WORD_STATE_ATTR, state);
+    }
+}
 const LINE_SYNCED_WORD_CLASS = "blyrics-line-synced-word";
 const INSTRUMENTAL_FILL_SELECTOR = ".blyrics--instrumental-fill";
 const INSTRUMENTAL_WAVE_CLIP_SELECTOR = ".blyrics--wave-clip";
@@ -1936,6 +1956,7 @@ export function tickView(engine, currentTime, options) {
                     if (isPlaying)
                         lineData.isAnimating = false; // reset the animation against current media time
                 }
+                updateWordStates(lineData, currentTime);
                 const nativeTimingSample = lineNativeTimingSample(lineData, currentTime);
                 let usedNativeTimingSampleForDrift = false;
                 lineData.accumulatedOffsetMs = lineData.accumulatedOffsetMs / ANIMATION_TIMING_ACCUMULATION_DECAY;
@@ -1984,11 +2005,15 @@ export function tickView(engine, currentTime, options) {
                     }
                     lineData.isSelected = false;
                     clearLineStateClasses(lineData);
+                    updateWordStates(lineData, currentTime);
                 }
                 else if (hasLineAnimations(lineData) && (timeJumped || currentTime > staleAnimationEndTime)) {
                     logAnimationCleanup(engine, timeJumped ? "time-jump-reset" : "stale-reset", lineData, index, currentTime, staleAnimationEndTime);
                     resetLineAnimationState(lineData);
                 }
+                if (timeJumped) {
+                    updateWordStates(lineData, currentTime);
+                }
             }
             return true;
         });

package/dist/inject.d.ts

@@ -1,3 +1,4 @@
+import { type WordState } from "./constants.js";
 import type { Lyric, LyricPart, LyricSyncType } from "./types.js";
 export declare let disableRichsync: import("./themeSettings.js").Setting;
 export declare function findNearestAgent(lyrics: Lyric[], fromIndex: number): string | undefined;
@@ -20,6 +21,7 @@ export interface PartData extends AnimationData {
     letterElements?: HTMLElement[];
     highlightLetterElements?: HTMLElement[];
     glowSuppressed?: boolean;
+    wordState: WordState;
 }
 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, 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, 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, WORD_HIGHLIGHT_LETTERED_CLASS, WORD_STATE_ATTR, WORD_STATE_UPCOMING, ZERO_DURATION_ANIMATION_CLASS, } from "./constants.js";
 import { getSeekTimeFromClick } from "./seek.js";
 import { testRtl } from "./text.js";
 import { registerThemeSetting } from "./themeSettings.js";
@@ -20,6 +20,7 @@ let lineSyncedAnimationDelay = registerThemeSetting("blyrics-line-synced-animati
 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 graphemeSegmenter = new Intl.Segmenter(undefined, { granularity: "grapheme" });
 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;
@@ -70,6 +71,7 @@ function newPartData(part, span, highlight, letterElements, highlightLetterEleme
         letterElements,
         highlightLetterElements,
         animations: [],
+        wordState: WORD_STATE_UPCOMING,
     };
 }
 export function newLineData(lyricElement, startTimeMs, durationMs) {
@@ -199,7 +201,7 @@ function appendLongWordBreaks(doc, span, text, threshold) {
     return true;
 }
 function appendLetters(doc, wordElement, text) {
-    const chars = [...text];
+    const chars = [...graphemeSegmenter.segment(text)].map(segment => segment.segment);
     wordElement.style.setProperty("--letters", String(chars.length));
     // Width of the reveal mask's soft edge as a percentage of its (n+2)-letter-wide box, so the fade
     // spans the same 0.1*letters of a letter that the old gradient did. See the mask rule in lyrics.css.
@@ -249,6 +251,7 @@ function createTimedWordSpan(doc, part, wrapThreshold, perLetter) {
         wordElement.dataset.time = String(part.startTimeMs / 1000);
         wordElement.dataset.duration = String(part.durationMs / 1000);
         wordElement.dataset.content = part.words;
+        wordElement.setAttribute(WORD_STATE_ATTR, WORD_STATE_UPCOMING);
         wordElement.style.setProperty("--blyrics-duration", part.durationMs + "ms");
     }
     return { span, highlight, letters, highlightLetters };
@@ -298,6 +301,15 @@ function createHighlightRun(doc, text) {
     run.setAttribute("aria-hidden", "true");
     return run;
 }
+// A background gap must carry the background size too, or it renders full-size and the gap looks oversized.
+function createSpaceNode(doc, text, isBackground) {
+    if (!isBackground)
+        return doc.createTextNode(text);
+    const span = doc.createElement("span");
+    span.classList.add(BACKGROUND_LYRIC_CLASS);
+    span.textContent = text;
+    return span;
+}
 export function createLyricsLine(doc, parts, line, lyricElement, options = { splitBackgroundLine: true }) {
     const lineText = parts.map(part => part.words).join("");
     const mainText = options.splitBackgroundLine
@@ -336,8 +348,8 @@ export function createLyricsLine(doc, parts, line, lyricElement, options = { spl
             const highlightRun = shouldUseBackgroundLine ? backgroundHighlightRun : mainHighlightRun;
             const pendingSpace = shouldUseBackgroundLine ? pendingBackgroundSpace : pendingForegroundSpace;
             if (target.childNodes.length > 0 && pendingSpace.length > 0) {
-                target.appendChild(doc.createTextNode(pendingSpace));
-                highlightRun.appendChild(doc.createTextNode(pendingSpace));
+                target.appendChild(createSpaceNode(doc, pendingSpace, shouldUseBackgroundLine));
+                highlightRun.appendChild(createSpaceNode(doc, pendingSpace, shouldUseBackgroundLine));
             }
             const { lyricGroup, highlightGroup } = createWordGroup(doc, item, line);
             target.appendChild(lyricGroup);
@@ -400,7 +412,8 @@ export function injectRomanization(doc, lyricElement, lineData, text, timedRoman
     else {
         romanizedLine.textContent = text;
     }
-    lyricElement.appendChild(romanizedLine);
+    const translation = lyricElement.querySelector(`.${TRANSLATED_LYRICS_CLASS}`);
+    lyricElement.insertBefore(romanizedLine, translation);
 }
 export function injectTranslation(doc, lyricElement, text) {
     if (lyricElement.querySelector(`.${TRANSLATED_LYRICS_CLASS}`))

package/package.json

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