@braccato/core 1.7.1 → 1.9.0

package/README.md

@@ -76,7 +76,7 @@ connects, and everything it was handed by then is applied at once.
 | Property        | Attribute      | Type                                | Default  | Description                                                                                                                              |
 | --------------- | -------------- | ----------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
 | `lyrics`        |                | `Lyric[] \| null`                   | `null`   | The song. Null means it was never given one, and an empty array clears the view, so there is a way to say both.                            |
-| `lyricsOptions` |                | `{ loaderVisible?, noLyrics? }`     | `{}`     | How the lines are built. `noLyrics` marks a message as a placeholder rather than a song, which keeps passive scrolling from drifting it.   |
+| `lyricsOptions` |                | `{ loaderVisible?, noLyrics?, language? }`     | `{}`     | How the lines are built. `noLyrics` marks a message as a placeholder rather than a song, which keeps passive scrolling from drifting it.   |
 | `source`        | `source`       | `string \| HTMLMediaElement \| null` | `null`  | A selector or the media element itself. See Following a media element.                                                                     |
 | `mediaElement`  |                | `HTMLMediaElement \| null` (get)    | `null`   | What `source` resolved to. Null while disconnected, and null for a selector that missed.                                                   |
 | `currentTime`   | `current-time` | `number`                            | `0`      | Playback position in **seconds**. Writing it renders the view again, so whoever holds the clock drives the lyrics by writing this.        |
@@ -150,6 +150,32 @@ stylesheet must not be able to configure the module by accident. An empty theme
 back to its default. The stylesheet itself goes into the document head under the
 `blyrics-custom-style` id.
 
+### Autoscroll grouping and animation
+
+`blyrics-early-scroll-consider-s` is a comment setting with an independent default of `0.54`
+seconds. When a lyric reaches its scroll time, the renderer includes nearby upcoming lines in
+its target calculation. Entering the lookahead window alone does not scroll. A line already
+included in a committed scroll does not scroll again when its own time arrives. Seeking,
+resuming autoscroll and relayout can still reposition the view.
+
+```css
+/* blyrics-early-scroll-consider-s = 0.54; */
+/* blyrics-line-scroll-duration = 750ms; */
+```
+
+New groups scroll immediately. Previous per-line `translate` animations continue and compose
+additively, so their duration does not block the next scroll. The line-scroll duration knobs
+control visual motion. The legacy `--blyrics-lyric-scroll-duration` variable and its
+`--blyrics-lyric-transition-duration` alias have been removed, along with the container transform
+transition. `blyrics-queue-scroll-ms` is ignored, and no timing equation needs balancing.
+Missing or invalid line durations fall back to an internal `750ms` duration; nonpositive resolved
+durations also use that fallback. Themes should set the line-scroll duration knobs directly
+instead of referencing the removed variables.
+
+Themes that previously relied on duration-derived lookahead should set their preferred
+`blyrics-early-scroll-consider-s` explicitly. The default remains close to the former default
+of approximately `0.54s`, but a custom animation duration no longer changes grouping.
+
 There is no `longWordThreshold`, `lineSyncedDelay` or `disableRichsync` property. Those are theme
 settings (`blyrics-long-word-threshold`, `blyrics-line-synced-animation-delay`,
 `blyrics-disable-richsync`), read from the stylesheet you already hand over. A theme that set one
@@ -365,3 +391,28 @@ repository and run `pnpm -C demo dev`, then open `http://localhost:5173/`.
 ## Licence
 
 MIT. See `LICENSE`.
+
+### Content language and CJK fonts
+
+Pass the source BCP 47 language to `renderer.setLyrics(lyrics, { language: "ja" })`
+(or `element.lyricsOptions = { language: "ja" }` before assigning lyrics). If language detection
+finishes later, `renderer.setLanguage("ja")` updates the existing lines and their measurements
+without replacing their DOM or animations. Repeating the same language (including equivalent spellings
+such as `ja-JP` and `ja_JP`) does not write to the DOM or measure again. Omitting the language on a
+new song clears the old hint.
+
+The renderer preserves Chinese script/region tags and uses kana or Hangul as a fallback when
+metadata is missing or contradicts the text. Han characters alone cannot identify a language;
+untagged Han-only lyrics remain unknown. Translation and romanization settings are not needed
+for this local inference.
+
+Use `injectTranslation(document, lineElement, text, "zh-Hant")` to label a translation separately
+from its source. The language argument is optional; unknown translations get `lang=""` so they
+do not inherit the original lyrics' language. Romanizations use the source language with `Latn`.
+
+Default font stacks now resolve on each lyric and decoration instead of only at the root. Hosts
+loading regional CJK web fonts should set `--noto-sans-universal` on these elements according to
+`:lang()`: a Japanese line and its Chinese translation can then choose different font subsets.
+`--blyrics-font-family` and `--blyrics-translated-font-family` remain explicit theme overrides.
+They are unset by default; custom CSS that reads them directly should use
+`var(--blyrics-font-family, var(--blyrics-default-font-family))` for the default stack.

package/dist/README.md

@@ -76,7 +76,7 @@ connects, and everything it was handed by then is applied at once.
 | Property        | Attribute      | Type                                | Default  | Description                                                                                                                              |
 | --------------- | -------------- | ----------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
 | `lyrics`        |                | `Lyric[] \| null`                   | `null`   | The song. Null means it was never given one, and an empty array clears the view, so there is a way to say both.                            |
-| `lyricsOptions` |                | `{ loaderVisible?, noLyrics? }`     | `{}`     | How the lines are built. `noLyrics` marks a message as a placeholder rather than a song, which keeps passive scrolling from drifting it.   |
+| `lyricsOptions` |                | `{ loaderVisible?, noLyrics?, language? }`     | `{}`     | How the lines are built. `noLyrics` marks a message as a placeholder rather than a song, which keeps passive scrolling from drifting it.   |
 | `source`        | `source`       | `string \| HTMLMediaElement \| null` | `null`  | A selector or the media element itself. See Following a media element.                                                                     |
 | `mediaElement`  |                | `HTMLMediaElement \| null` (get)    | `null`   | What `source` resolved to. Null while disconnected, and null for a selector that missed.                                                   |
 | `currentTime`   | `current-time` | `number`                            | `0`      | Playback position in **seconds**. Writing it renders the view again, so whoever holds the clock drives the lyrics by writing this.        |
@@ -150,6 +150,32 @@ stylesheet must not be able to configure the module by accident. An empty theme
 back to its default. The stylesheet itself goes into the document head under the
 `blyrics-custom-style` id.
 
+### Autoscroll grouping and animation
+
+`blyrics-early-scroll-consider-s` is a comment setting with an independent default of `0.54`
+seconds. When a lyric reaches its scroll time, the renderer includes nearby upcoming lines in
+its target calculation. Entering the lookahead window alone does not scroll. A line already
+included in a committed scroll does not scroll again when its own time arrives. Seeking,
+resuming autoscroll and relayout can still reposition the view.
+
+```css
+/* blyrics-early-scroll-consider-s = 0.54; */
+/* blyrics-line-scroll-duration = 750ms; */
+```
+
+New groups scroll immediately. Previous per-line `translate` animations continue and compose
+additively, so their duration does not block the next scroll. The line-scroll duration knobs
+control visual motion. The legacy `--blyrics-lyric-scroll-duration` variable and its
+`--blyrics-lyric-transition-duration` alias have been removed, along with the container transform
+transition. `blyrics-queue-scroll-ms` is ignored, and no timing equation needs balancing.
+Missing or invalid line durations fall back to an internal `750ms` duration; nonpositive resolved
+durations also use that fallback. Themes should set the line-scroll duration knobs directly
+instead of referencing the removed variables.
+
+Themes that previously relied on duration-derived lookahead should set their preferred
+`blyrics-early-scroll-consider-s` explicitly. The default remains close to the former default
+of approximately `0.54s`, but a custom animation duration no longer changes grouping.
+
 There is no `longWordThreshold`, `lineSyncedDelay` or `disableRichsync` property. Those are theme
 settings (`blyrics-long-word-threshold`, `blyrics-line-synced-animation-delay`,
 `blyrics-disable-richsync`), read from the stylesheet you already hand over. A theme that set one
@@ -365,3 +391,28 @@ repository and run `pnpm -C demo dev`, then open `http://localhost:5173/`.
 ## Licence
 
 MIT. See `LICENSE`.
+
+### Content language and CJK fonts
+
+Pass the source BCP 47 language to `renderer.setLyrics(lyrics, { language: "ja" })`
+(or `element.lyricsOptions = { language: "ja" }` before assigning lyrics). If language detection
+finishes later, `renderer.setLanguage("ja")` updates the existing lines and their measurements
+without replacing their DOM or animations. Repeating the same language (including equivalent spellings
+such as `ja-JP` and `ja_JP`) does not write to the DOM or measure again. Omitting the language on a
+new song clears the old hint.
+
+The renderer preserves Chinese script/region tags and uses kana or Hangul as a fallback when
+metadata is missing or contradicts the text. Han characters alone cannot identify a language;
+untagged Han-only lyrics remain unknown. Translation and romanization settings are not needed
+for this local inference.
+
+Use `injectTranslation(document, lineElement, text, "zh-Hant")` to label a translation separately
+from its source. The language argument is optional; unknown translations get `lang=""` so they
+do not inherit the original lyrics' language. Romanizations use the source language with `Latn`.
+
+Default font stacks now resolve on each lyric and decoration instead of only at the root. Hosts
+loading regional CJK web fonts should set `--noto-sans-universal` on these elements according to
+`:lang()`: a Japanese line and its Chinese translation can then choose different font subsets.
+`--blyrics-font-family` and `--blyrics-translated-font-family` remain explicit theme overrides.
+They are unset by default; custom CSS that reads them directly should use
+`var(--blyrics-font-family, var(--blyrics-default-font-family))` for the default stack.

package/dist/engine.d.ts

@@ -19,10 +19,8 @@ interface AnimEngineViewState {
     scrollResumeTime: number;
     scrollPos: number;
     selectedElementIndex: number;
-    nextScrollAllowedTime: number;
     wasUserScrolling: boolean;
-    lastActiveElements: LineData[];
-    queuedScroll: boolean;
+    lastScrollElements: LineData[];
     lastScrollDebugContext: {
         activeElms: LineData[];
         centers: number[];
@@ -210,12 +208,7 @@ interface AnimationConfig {
         waveOscillationDurationMs: number;
         waveOscillationEasing: string;
     };
-    scroll: {
-        durationMs: number;
-        easing: string;
-    };
     lineScroll: {
-        durationMs: number;
         easing: string;
         differentialEffects: boolean;
     };
@@ -224,7 +217,6 @@ interface AnimationSettings {
     config: AnimationConfig;
     scrollTiming: {
         earlyScrollConsiderS: number;
-        queueScrollMs: number;
     };
 }
 export declare function noteVisibilityChange(engine: AnimationEngineInstance): void;

package/dist/engine.js

@@ -26,18 +26,11 @@ const PAUSING_LYRICS_SCROLL_LOG = "Pausing Lyrics Autoscroll Due to User Scroll"
 const USER_SCROLL_RESUME_DELAY_MS = 25000;
 const PASSIVE_USER_SCROLL_RESUME_DELAY_MS = 5000;
 const LYRIC_ENDING_THRESHOLD_S = registerThemeSetting("blyrics-lyric-ending-threshold-s", 0.5);
-const EARLY_SCROLL_CONSIDER = registerThemeSetting("blyrics-early-scroll-consider-s", 0.62);
-const QUEUE_SCROLL_THRESHOLD = registerThemeSetting("blyrics-queue-scroll-ms", 150);
+const EARLY_SCROLL_CONSIDER = registerThemeSetting("blyrics-early-scroll-consider-s", 0.54);
 const TIME_JUMP_THRESHOLD = 0.5;
 const REDUCED_MOTION_QUERY = "(prefers-reduced-motion: reduce)";
-const SCROLL_TIMING_RATIO_BASE_DURATION_MS = 750;
-const SCROLL_TIMING_RATIO_BASE_EARLY_SCROLL_CONSIDER_S = 0.62;
-const SCROLL_TIMING_RATIO_BASE_QUEUE_SCROLL_THRESHOLD_MS = 150;
-const MAX_AUTO_QUEUE_SCROLL_THRESHOLD_MS = 200;
 const SCROLL_PREPARE_LEAD_MS = 120;
-const SCROLL_TIMING_RATIO_BASE_TOTAL_MS = SCROLL_TIMING_RATIO_BASE_EARLY_SCROLL_CONSIDER_S * 1000 + SCROLL_TIMING_RATIO_BASE_QUEUE_SCROLL_THRESHOLD_MS;
-const SCROLL_TIMING_BUFFER_MS = SCROLL_TIMING_RATIO_BASE_TOTAL_MS - SCROLL_TIMING_RATIO_BASE_DURATION_MS;
-const AUTO_QUEUE_SCROLL_RATIO = SCROLL_TIMING_RATIO_BASE_QUEUE_SCROLL_THRESHOLD_MS / SCROLL_TIMING_RATIO_BASE_TOTAL_MS;
+const LINE_SCROLL_FALLBACK_DURATION_MS = 750;
 const SWIPE_LEAD_RATIO = registerThemeSetting("blyrics-swipe-lead-ratio", 0.1);
 const SWIPE_DURATION_RATIO = registerThemeSetting("blyrics-swipe-duration-ratio", 1.6);
 const ENABLE_DEBUG_RENDER = registerThemeSetting("blyrics-debug-renderer", false);
@@ -125,10 +118,8 @@ export function createAnimationEngineInstance(engineDocument, engineWindow, host
         scrollResumeTime: 0,
         scrollPos: 0,
         selectedElementIndex: 0,
-        nextScrollAllowedTime: 0,
         wasUserScrolling: false,
-        lastActiveElements: [],
-        queuedScroll: false,
+        lastScrollElements: [],
         lastScrollDebugContext: {
             activeElms: [],
             centers: [],
@@ -237,7 +228,6 @@ export function noteUserScroll(engine, isPassive) {
 export function noteContainerResize(engine, width, height) {
     if (width === engine.lyricWidth && height === engine.lyricHeight)
         return false;
-    engine.nextScrollAllowedTime = 0;
     return true;
 }
 /**
@@ -282,10 +272,9 @@ export function clearLyrics(engine) {
         line.isSelected = false;
     }
     engine.skipScrollsDecayTimes = [];
-    engine.lastActiveElements = [];
+    engine.lastScrollElements = [];
     engine.lastScrollDebugContext.activeElms = [];
     engine.lastScrollDebugContext.centers = [];
-    engine.queuedScroll = false;
     engine.passiveScrollAccumulatedTime = 0;
     engine.passiveLastWallTime = 0;
     stopPassiveScrollLoop(engine);
@@ -1198,7 +1187,6 @@ function isGlowRestingInvisible(glowTo) {
 }
 function readAnimationConfig(engine, lyricsElement) {
     const prefersReducedMotion = engine.window.matchMedia(REDUCED_MOTION_QUERY).matches;
-    const scrollDurationMs = getCSSDurationWithFallback(engine, lyricsElement, "--blyrics-lyric-scroll-duration", "650ms");
     const scrollEasing = getCSSValue(engine, lyricsElement, "--blyrics-lyric-scroll-timing-function", "cubic-bezier(0.86, 0, 0.2, 1)");
     return {
         enabled: {
@@ -1271,53 +1259,21 @@ function readAnimationConfig(engine, lyricsElement) {
             waveOscillationDurationMs: getCSSDurationWithFallback(engine, lyricsElement, "--blyrics-instrumental-wave-oscillation-duration", "1.25s"),
             waveOscillationEasing: getCSSValue(engine, lyricsElement, "--blyrics-instrumental-wave-oscillation-easing", "ease-in-out"),
         },
-        scroll: {
-            durationMs: scrollDurationMs,
-            easing: scrollEasing,
-        },
         lineScroll: {
-            durationMs: scrollDurationMs,
             easing: scrollEasing,
             differentialEffects: !prefersReducedMotion,
         },
     };
 }
-function readScrollTiming(scrollDurationMs) {
-    const totalMs = Math.max(0, scrollDurationMs + SCROLL_TIMING_BUFFER_MS);
-    const earlyScrollConsiderWasSet = EARLY_SCROLL_CONSIDER.isManuallySet();
-    const queueScrollWasSet = QUEUE_SCROLL_THRESHOLD.isManuallySet();
-    if (earlyScrollConsiderWasSet && queueScrollWasSet) {
-        return {
-            earlyScrollConsiderS: Math.max(0, EARLY_SCROLL_CONSIDER.getNumberValue()),
-            queueScrollMs: Math.max(0, QUEUE_SCROLL_THRESHOLD.getNumberValue()),
-        };
-    }
-    if (earlyScrollConsiderWasSet) {
-        const earlyScrollConsiderS = Math.max(0, EARLY_SCROLL_CONSIDER.getNumberValue());
-        return {
-            earlyScrollConsiderS,
-            queueScrollMs: Math.min(Math.max(0, totalMs - earlyScrollConsiderS * 1000), MAX_AUTO_QUEUE_SCROLL_THRESHOLD_MS),
-        };
-    }
-    if (queueScrollWasSet) {
-        const queueScrollMs = Math.max(0, QUEUE_SCROLL_THRESHOLD.getNumberValue());
-        return {
-            earlyScrollConsiderS: Math.max(0, (totalMs - queueScrollMs) / 1000),
-            queueScrollMs,
-        };
-    }
-    const queueScrollMs = Math.min(totalMs * AUTO_QUEUE_SCROLL_RATIO, MAX_AUTO_QUEUE_SCROLL_THRESHOLD_MS);
-    return {
-        earlyScrollConsiderS: Math.max(0, (totalMs - queueScrollMs) / 1000),
-        queueScrollMs,
-    };
+function readScrollTiming() {
+    return { earlyScrollConsiderS: Math.max(0, EARLY_SCROLL_CONSIDER.getNumberValue()) };
 }
 function getAnimationSettings(engine, lyricsElement) {
     if (!engine.cachedAnimationSettings) {
         const config = readAnimationConfig(engine, lyricsElement);
         engine.cachedAnimationSettings = {
             config,
-            scrollTiming: readScrollTiming(config.scroll.durationMs),
+            scrollTiming: readScrollTiming(),
         };
     }
     return engine.cachedAnimationSettings;
@@ -1557,9 +1513,9 @@ function prepareLineScrollOffsets(engine, lines, activeLineIndex, scrollDeltaPx,
     const misses = requests.filter(request => !request.timing);
     if (misses.length > 0) {
         const missItems = misses.map(request => request.item);
-        const durations = batchResolveLineScrollProperty(engine, missItems, "transition-duration", item => lineScrollDurationProperty(item.side, config.lineScroll.durationMs, config.lineScroll.differentialEffects), style => {
+        const durations = batchResolveLineScrollProperty(engine, missItems, "transition-duration", item => lineScrollDurationProperty(item.side, LINE_SCROLL_FALLBACK_DURATION_MS, config.lineScroll.differentialEffects), style => {
             const durationMs = toMs(style.transitionDuration.split(",")[0].trim());
-            return durationMs > 0 ? durationMs : config.lineScroll.durationMs;
+            return durationMs > 0 ? durationMs : LINE_SCROLL_FALLBACK_DURATION_MS;
         });
         const startEasings = batchResolveLineScrollProperty(engine, missItems, "transition-timing-function", item => lineScrollEasingProperty(item.side, "start", config.lineScroll.easing, config.lineScroll.differentialEffects), style => style.transitionTimingFunction.trim() || config.lineScroll.easing);
         const endEasings = batchResolveLineScrollProperty(engine, missItems, "transition-timing-function", item => lineScrollEasingProperty(item.side, "end", config.lineScroll.easing, config.lineScroll.differentialEffects), style => style.transitionTimingFunction.trim() || config.lineScroll.easing);
@@ -1918,7 +1874,7 @@ export function tickView(engine, currentTime, options) {
             if (lyricScrollTime >= time - scrollTiming.earlyScrollConsiderS &&
                 (lyricScrollTime < nextTime || lyricScrollTime < time + lineData.duration)) {
                 activeElems.push(lineData);
-                if (!engine.lastActiveElements.includes(lineData) && lyricScrollTime >= time) {
+                if (!engine.lastScrollElements.includes(lineData) && lyricScrollTime >= time) {
                     newLyricSelected = true;
                 }
                 // const timeDelta = lyricScrollTime - time;
@@ -2032,8 +1988,6 @@ export function tickView(engine, currentTime, options) {
             if (activeElems.length == 0) {
                 activeElems.push(lines[0]);
             }
-            engine.lastActiveElements = activeElems.filter(elm => lyricScrollTime >= elm.time // remove elements that haven't reached their scroll time yet.
-            );
             // Offset so lyrics appear towards the center of the screen.
             const scrollPosOffset = tabRendererHeight * SCROLL_POS_OFFSET_RATIO.getNumberValue();
             let lastActiveLyric = activeElems[activeElems.length - 1];
@@ -2134,39 +2088,34 @@ export function tickView(engine, currentTime, options) {
                 !engine.wasUserScrolling &&
                 timeUntilUpcomingScrollMs > 0 &&
                 timeUntilUpcomingScrollMs <= SCROLL_PREPARE_LEAD_MS &&
-                Date.now() > engine.nextScrollAllowedTime &&
+                !engine.lastScrollElements.includes(lastActiveLyric) &&
                 Math.abs(scrollTop - scrollPos) > 2) {
                 updateVisibleLyricWillChange(engine, lines, scrollTop, scrollPos, tabRendererHeight);
                 prepareUpcomingLineScroll(engine, getLineScrollItems(engine, lines), lastActiveLyric, scrollPos - scrollTop, scrollTop, scrollPos, tabRendererHeight, animationConfig);
             }
-            if (engine.wasUserScrolling || newLyricSelected || engine.queuedScroll) {
-                if (Date.now() > engine.nextScrollAllowedTime) {
-                    engine.queuedScroll = false;
-                    engine.lastScrollDebugContext.lyricScrollTime = lyricScrollTime;
-                    engine.lastScrollDebugContext.centers = lyricPositions;
-                    engine.lastScrollDebugContext.activeElms = activeElems;
-                    if (smoothScroll && Math.abs(scrollTop - scrollPos) > 2) {
-                        const scrollDeltaPx = scrollPos - scrollTop;
-                        if (animationConfig.enabled.scroll) {
-                            updateVisibleLyricWillChange(engine, lines, scrollTop, scrollPos, tabRendererHeight);
-                            const lineScrollItems = getLineScrollItems(engine, lines);
-                            commitOrPrepareLineScroll(engine, lineScrollItems, lastActiveLyric, scrollDeltaPx, scrollTop, scrollPos, tabRendererHeight, animationConfig);
-                            engine.nextScrollAllowedTime = animationConfig.scroll.durationMs + Date.now() + 20;
-                        }
-                    }
-                    else {
-                        dropPendingLineScroll(engine);
+            if (engine.wasUserScrolling || newLyricSelected) {
+                // Remember future lines only when their group is committed, so they cannot scroll
+                // again at their start. Entering the lookahead window alone does not commit a group.
+                engine.lastScrollElements = activeElems;
+                engine.lastScrollDebugContext.lyricScrollTime = lyricScrollTime;
+                engine.lastScrollDebugContext.centers = lyricPositions;
+                engine.lastScrollDebugContext.activeElms = activeElems;
+                if (smoothScroll && Math.abs(scrollTop - scrollPos) > 2) {
+                    const scrollDeltaPx = scrollPos - scrollTop;
+                    if (animationConfig.enabled.scroll) {
+                        updateVisibleLyricWillChange(engine, lines, scrollTop, scrollPos, tabRendererHeight);
+                        const lineScrollItems = getLineScrollItems(engine, lines);
+                        commitOrPrepareLineScroll(engine, lineScrollItems, lastActiveLyric, scrollDeltaPx, scrollTop, scrollPos, tabRendererHeight, animationConfig);
                     }
-                    scrollTop = scrollPos;
-                    engine.scrollPos = scrollTop;
-                    tabRenderer.scrollTop = scrollTop;
-                    engine.skipScrolls += 1;
-                    engine.skipScrollsDecayTimes.push(Date.now() + 2000);
                 }
-                else if (engine.nextScrollAllowedTime - Date.now() < scrollTiming.queueScrollMs || timeJumped) {
-                    // just missed out on being able to scroll, queue this once we finish our current lyric
-                    engine.queuedScroll = true;
+                else {
+                    dropPendingLineScroll(engine);
                 }
+                scrollTop = scrollPos;
+                engine.scrollPos = scrollTop;
+                tabRenderer.scrollTop = scrollTop;
+                engine.skipScrolls += 1;
+                engine.skipScrollsDecayTimes.push(Date.now() + 2000);
             }
         }
         if (engine.wasUserScrolling && engine.scrollResumeTime < Date.now()) {

package/dist/inject.d.ts

@@ -43,4 +43,4 @@ export declare function createLyricsLine(doc: Document, parts: LyricPart[], line
 export declare function buildLineSyncedParts(item: Lyric): LyricPart[];
 export declare function addSeekHandler(seek: (timeS: number) => void, lyricElement: HTMLElement, allZero: boolean): void;
 export declare function injectRomanization(doc: Document, lyricElement: HTMLElement, lineData: LineData, text: string, timedRomanization?: LyricPart[] | null): void;
-export declare function injectTranslation(doc: Document, lyricElement: HTMLElement, text: string): void;
+export declare function injectTranslation(doc: Document, lyricElement: HTMLElement, text: string, language?: string | null): void;

package/dist/inject.js

@@ -11,6 +11,7 @@
 // animates is one word, so every part is split on whitespace with its timing pro-rated across the
 // split by character count. A line that arrives with no timed parts at all is rebuilt the same way
 // into zero duration words, so line synced lyrics reach the DOM the sweep already knows.
+import { normalizeLanguage } from "./language.js";
 import { BACKGROUND_LINE_CLASS, BACKGROUND_LYRIC_CLASS, BIDI_RUN_CLASS, BIDI_SENSITIVE_CLASS, CONTENT_LINE_CLASS, EXPLICIT_WORD_CLASS, HIGHLIGHT_RUN_CLASS, LETTER_CLASS, LINE_MAIN_CLASS, LINE_SYNCED_WORD_CLASS, LONG_WORD_GROUP_CLASS, ROMANIZED_LYRICS_CLASS, RTL_CLASS, TRANSLATED_LYRICS_CLASS, WORD_CLASS, WORD_GROUP_CLASS, WORD_HIGHLIGHT_CLASS, WORD_HIGHLIGHT_LETTERED_CLASS, WORD_STATE_ATTR, WORD_STATE_UPCOMING, ZERO_DURATION_ANIMATION_CLASS, } from "./constants.js";
 import { getSeekTimeFromClick } from "./seek.js";
 import { testRtl } from "./text.js";
@@ -405,6 +406,8 @@ export function injectRomanization(doc, lyricElement, lineData, text, timedRoman
     const romanizedLine = doc.createElement("div");
     romanizedLine.classList.add(ROMANIZED_LYRICS_CLASS, CONTENT_LINE_CLASS);
     romanizedLine.dir = "auto";
+    const language = normalizeLanguage(lyricElement.lang);
+    romanizedLine.lang = `${language ? new Intl.Locale(language).language : "und"}-Latn`;
     applyDirection(romanizedLine, text);
     if (timedRomanization && timedRomanization.length > 0 && !disableRichsync.getBooleanValue()) {
         createLyricsLine(doc, timedRomanization, lineData, romanizedLine, { splitBackgroundLine: false });
@@ -415,12 +418,13 @@ export function injectRomanization(doc, lyricElement, lineData, text, timedRoman
     const translation = lyricElement.querySelector(`.${TRANSLATED_LYRICS_CLASS}`);
     lyricElement.insertBefore(romanizedLine, translation);
 }
-export function injectTranslation(doc, lyricElement, text) {
+export function injectTranslation(doc, lyricElement, text, language) {
     if (lyricElement.querySelector(`.${TRANSLATED_LYRICS_CLASS}`))
         return;
     const translatedLine = doc.createElement("div");
     translatedLine.classList.add(TRANSLATED_LYRICS_CLASS, CONTENT_LINE_CLASS);
     translatedLine.dir = "auto";
+    translatedLine.lang = normalizeLanguage(language);
     applyDirection(translatedLine, text);
     translatedLine.textContent = text;
     lyricElement.appendChild(translatedLine);

package/dist/language.d.ts

@@ -0,0 +1,9 @@
+interface LyricText {
+    words: string;
+    isInstrumental?: boolean;
+}
+export declare function normalizeLanguage(language?: string | null): string;
+export declare function resolveLyricLanguages(lyrics: readonly LyricText[], sourceLanguage?: string | null): string[];
+/** Tags only lyric content, leaving the host UI and source footer in their own language. */
+export declare function applyLyricLanguage(element: HTMLElement, language?: string | null): void;
+export {};

package/dist/language.js

@@ -0,0 +1,47 @@
+import { ROMANIZED_LYRICS_CLASS } from "./constants.js";
+export function normalizeLanguage(language) {
+    if (!language || language === "auto" || language === "und")
+        return "";
+    try {
+        return Intl.getCanonicalLocales(language.trim().replaceAll("_", "-"))[0] ?? "";
+    }
+    catch {
+        return "";
+    }
+}
+function detectCjkLanguage(text) {
+    if (/[\p{Script=Hiragana}\p{Script=Katakana}]/u.test(text))
+        return "ja";
+    if (/\p{Script=Hangul}/u.test(text))
+        return "ko";
+    // Han alone cannot distinguish Japanese, Korean, or the Chinese writing systems.
+    return null;
+}
+function isCjkLanguage(language) {
+    return /^(ja|ko|zh|yue)(-|$)|-(Hans|Hant)(-|$)/i.test(language);
+}
+export function resolveLyricLanguages(lyrics, sourceLanguage) {
+    const language = normalizeLanguage(sourceLanguage);
+    const hints = lyrics.map(line => (line.isInstrumental ? null : detectCjkLanguage(line.words)));
+    const songHints = new Set(hints.filter(hint => hint !== null));
+    const songHint = songHints.size === 1 ? [...songHints][0] : "";
+    const fallback = isCjkLanguage(language) ? language : songHint || language;
+    return lyrics.map((line, index) => {
+        if (line.isInstrumental)
+            return "";
+        const hint = hints[index];
+        if (hint && fallback.split("-")[0] !== hint)
+            return hint;
+        if (/\p{Script=Han}/u.test(line.words) && !isCjkLanguage(fallback))
+            return "";
+        return fallback;
+    });
+}
+/** Tags only lyric content, leaving the host UI and source footer in their own language. */
+export function applyLyricLanguage(element, language) {
+    const normalized = normalizeLanguage(language);
+    element.lang = normalized;
+    const romanization = element.querySelector(`.${ROMANIZED_LYRICS_CLASS}`);
+    if (romanization)
+        romanization.lang = `${normalized ? new Intl.Locale(normalized).language : "und"}-Latn`;
+}

package/dist/renderer.js

@@ -12,6 +12,7 @@
 import { CUSTOM_THEME_STYLE_ID } from "./constants.js";
 import { clearLyrics, clearOnScreenLyrics as clearEngineOnScreenLyrics, clearStyleCaches as clearEngineStyleCaches, createAnimationEngineInstance, getRenderedLines, getRenderedSyncType, hasUnsyncedLyrics, noteContainerResize, noteUserScroll as noteEngineUserScroll, noteVisibilityChange as noteEngineVisibilityChange, relayout, resetScrollResume, resolveTickOptions, retickFromPlaybackClock as retickEngineFromPlaybackClock, scheduleLyricPositionUpdate as scheduleEngineLyricPositionUpdate, tickView, } from "./engine.js";
 import { parseThemeConfig, setThemeSettings } from "./themeSettings.js";
+import { applyLyricLanguage, normalizeLanguage, resolveLyricLanguages } from "./language.js";
 import { setLyrics as buildLyricsView } from "./view.js";
 /**
  * What the default `seek` dispatches at the mount. A consumer that gave the renderer no way to
@@ -134,6 +135,8 @@ export function createLyricsRenderer(rendererOptions) {
     // Only the theme element this renderer created, which is the only one it may take away again.
     let createdThemeStyleElement = null;
     let isDestroyed = false;
+    let currentLyrics = [];
+    let currentLanguage = "";
     const { host, forgetScrollElement } = withHostDefaults(rendererOptions.host, rendererWindow, () => mount);
     const engine = createAnimationEngineInstance(rendererDocument, rendererWindow, host);
     /**
@@ -165,6 +168,8 @@ export function createLyricsRenderer(rendererOptions) {
         stopObservingContainer();
         engine.lyricsContainer?.remove();
         clearLyrics(engine);
+        currentLyrics = [];
+        currentLanguage = "";
     }
     /**
      * Watches the built container for the layout it settles into. The guard is what stops this
@@ -252,13 +257,25 @@ export function createLyricsRenderer(rendererOptions) {
             clearBuiltView();
             mount = nextMount;
             buildLyricsView(engine, nextMount, lyrics, {
+                language: options?.language,
                 loaderVisible: options?.loaderVisible ?? false,
                 noLyrics: options?.noLyrics ?? false,
             });
+            currentLyrics = lyrics;
+            currentLanguage = normalizeLanguage(options?.language);
             measure();
             if (engine.lyricsContainer)
                 observeContainer(engine.lyricsContainer);
         },
+        setLanguage(language) {
+            const normalized = normalizeLanguage(language);
+            if (isDestroyed || currentLyrics.length === 0 || normalized === currentLanguage)
+                return;
+            currentLanguage = normalized;
+            const languages = resolveLyricLanguages(currentLyrics, normalized);
+            getRenderedLines(engine).forEach((line, index) => applyLyricLanguage(line.lyricElement, languages[index]));
+            measure();
+        },
         setTheme(css) {
             if (isDestroyed)
                 return false;

package/dist/styles/lyrics.css

@@ -1,6 +1,19 @@
+/* Resolve the default stack at each language boundary. A root-level var() would freeze
+   the host's language-specific fallback before the lyric/translation language is known.
+   Theme overrides remain inherited through --blyrics-font-family. */
+.blyrics--line,
+.blyrics--translated,
+.blyrics--romanized {
+	--blyrics-default-font-family:
+		Satoshi, var(--noto-sans-universal, "Noto Sans"), Avenir, -apple-system,
+		BlinkMacSystemFont, Segoe UI, Roboto, Oxygen, Ubuntu, Cantarell, Open Sans,
+		Helvetica Neue, sans-serif;
+	font-family: var(--blyrics-font-family, var(--blyrics-default-font-family));
+}
+
 /* Main container styles */
 .blyrics-container {
-	font-family: var(--blyrics-font-family);
+	font-family: var(--blyrics-font-family, var(--blyrics-default-font-family));
 	font-size: var(--blyrics-font-size);
 	font-weight: var(--blyrics-font-weight);
 	isolation: isolate;
@@ -8,8 +21,6 @@
 	padding-bottom: calc(var(--blyrics-padding-bottom));
 	padding-top: 2rem;
 	position: relative !important;
-	transition: transform var(--blyrics-lyric-scroll-duration)
-		var(--blyrics-lyric-scroll-timing-function) 0s;
 	will-change: transform;
 	z-index: 1;
 }
@@ -215,7 +226,7 @@
 		cubic-bezier(0.25, 1, 0.5, 1) both;
 	color: var(--blyrics-translated-color);
 	display: block;
-	font-family: var(--blyrics-translated-font-family);
+	font-family: var(--blyrics-translated-font-family, var(--blyrics-font-family, var(--blyrics-default-font-family)));
 	font-size: var(--blyrics-translated-font-size);
 	font-weight: var(--blyrics-translated-font-weight);
 	line-height: 1.1;

package/dist/styles/variables.css

@@ -36,7 +36,7 @@
 	   so that a standalone consumer without it still falls through to the rest of this stack; the
 	   CJK, Devanagari, Arabic, Hebrew and Thai coverage is what such a consumer gives up either
 	   way. */
-	--blyrics-font-family:
+	--blyrics-default-font-family:
 		Satoshi, var(--noto-sans-universal, "Noto Sans"), Avenir, -apple-system,
 		BlinkMacSystemFont, Segoe UI, Roboto, Oxygen, Ubuntu, Cantarell, Open Sans,
 		Helvetica Neue, sans-serif;
@@ -46,7 +46,6 @@
 
 	--blyrics-translated-font-size: 2rem;
 	--blyrics-translated-font-weight: 600;
-	--blyrics-translated-font-family: var(--blyrics-font-family);
 	--blyrics-translated-color: color(
 		display-p3 1 1 1 / var(--blyrics-translated-opacity, 0.6)
 	);
@@ -144,11 +143,7 @@
 	--blyrics-background-blur: 100px;
 	--blyrics-background-saturate: 2;
 
-	/* Lyric Transition Properties */
-	--blyrics-lyric-scroll-duration: var(
-		--blyrics-lyric-transition-duration,
-		650ms
-	);
+	/* Shared lyric scroll easing */
 	--blyrics-lyric-scroll-timing-function: var(
 		--blyrics-lyric-transition-timing-function,
 		cubic-bezier(0.86, 0, 0.2, 1)

package/dist/types.d.ts

@@ -109,6 +109,8 @@ export interface LyricsRenderer {
     setLyrics(lyrics: Lyric[], options?: Partial<SetLyricsOptions> & {
         mount?: HTMLElement;
     }): void;
+    /** Updates a late-detected source language and layout without rebuilding lines or animations. */
+    setLanguage(language?: string | null): void;
     /**
      * Applies a compiled theme. The `blyrics-*` configuration in its comments becomes the module's
      * theme settings, and the stylesheet itself is applied to the document this renderer builds in.

package/dist/view.d.ts

@@ -1,6 +1,8 @@
 import { type AnimationEngineInstance } from "./engine.js";
 import type { Lyric } from "./types.js";
 export interface SetLyricsOptions {
+    /** BCP 47 language of the original lyrics. Kana/Hangul provide a fallback when omitted. */
+    language?: string | null;
     /**
      * Whether the loader is still covering the view. Recorded on the container for CSS to key on.
      */

package/dist/view.js

@@ -13,6 +13,7 @@ import { LINE_CLASS, LYRICS_CLASS, RTL_CLASS } from "./constants.js";
 import { setupLineCullObserver } from "./engine.js";
 import { addSeekHandler, applyDirection, buildLineSyncedParts, createLyricsLine, deriveSyncType, disableRichsync, findNearestAgent, isNearestLyricRtl, newLineData, } from "./inject.js";
 import { createInstrumentalElement } from "./instrumental.js";
+import { applyLyricLanguage, resolveLyricLanguages } from "./language.js";
 const INITIAL_SKIP_SCROLLS = 2;
 const SKIP_SCROLL_DECAY_MS = 2000;
 function buildInstrumentalLine(doc, lyricElement, lyrics, lineIndex) {
@@ -58,6 +59,7 @@ export function setLyrics(engine, mount, lyrics, options) {
     const seek = (timeS) => engine.host.seek(timeS);
     const lines = [];
     const syncType = deriveSyncType(lyrics);
+    const languages = resolveLyricLanguages(lyrics, options.language);
     for (const [lineIndex, lyricItem] of lyrics.entries()) {
         const lyricElement = doc.createElement("div");
         const line = newLineData(lyricElement, lyricItem.startTimeMs, lyricItem.durationMs);
@@ -66,6 +68,7 @@ export function setLyrics(engine, mount, lyrics, options) {
         lyricElement.dataset.lineNumber = String(lineIndex);
         lyricElement.classList.add(LINE_CLASS);
         lyricElement.dir = "auto";
+        applyLyricLanguage(lyricElement, languages[lineIndex]);
         addSeekHandler(seek, lyricElement, allZero);
         lines.push(line);
         if (lyricItem.isInstrumental) {

package/package.json

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