@braccato/core 1.7.0 → 1.8.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.        |
@@ -365,3 +365,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.        |
@@ -365,3 +365,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/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;
@@ -215,7 +228,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;
@@ -244,10 +257,6 @@
 	width: fit-content;
 }
 
-.blyrics--romanized .blyrics-line-main {
-	display: inline;
-}
-
 .blyrics-rtl {
 	direction: rtl;
 }

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)
 	);

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.0",
+  "version": "1.8.0",
   "description": "Synchronized lyrics renderer with word-by-word animations",
   "type": "module",
   "license": "MIT",