@braccato/core 0.1.6 → 1.0.0

package/dist/inject.d.ts

@@ -0,0 +1,37 @@
+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;
+export declare function isNearestLyricRtl(lyrics: Lyric[], fromIndex: number): boolean;
+export declare function deriveSyncType(lyrics: Lyric[]): LyricSyncType;
+export interface PartData {
+    /**
+     * Time of this part in seconds
+     */
+    time: number;
+    /**
+     * Duration of this part in seconds
+     */
+    duration: number;
+    lyricElement: HTMLElement;
+    animations: Animation[];
+}
+export type LineData = {
+    parts: PartData[];
+    isScrolled: boolean;
+    isAnimationPlayStatePlaying: boolean;
+    accumulatedOffsetMs: number;
+    isAnimating: boolean;
+    lastAnimSetupAt: number;
+    isSelected: boolean;
+    height: number;
+    position: number;
+} & PartData;
+export declare function newLineData(lyricElement: HTMLElement, startTimeMs: number, durationMs: number): LineData;
+export declare function applyDirection(element: HTMLElement, text: string): void;
+export declare function createLyricsLine(doc: Document, parts: LyricPart[], line: LineData, lyricElement: HTMLElement, options?: {
+    splitBackgroundLine: boolean;
+}): HTMLElement;
+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;

package/dist/inject.js

@@ -0,0 +1,376 @@
+// Builds what goes inside a lyric line: the main and background content lines, the bidi runs inside
+// them, the word groups and the timed word spans the sweep animates, and the two decorators that
+// hang a translation or a romanization off a line that is already built. `view.ts` builds the line
+// and the container around it.
+//
+// The structure emitted here is as much published contract as the names written into it.
+// `constants.ts` says why a class name cannot be renamed; the nesting is under the same rule,
+// because a marketplace theme selects on the shape as well as on the names.
+//
+// A part is not a word. Providers hand over parts that run to several words, and the unit the sweep
+// 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, 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";
+export let disableRichsync = registerThemeSetting("blyrics-disable-richsync", false, true);
+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);
+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;
+export function findNearestAgent(lyrics, fromIndex) {
+    // Look in the downwards direction first
+    for (let i = fromIndex + 1; i < lyrics.length; i++) {
+        if (!lyrics[i].isInstrumental && lyrics[i].agent) {
+            return lyrics[i].agent;
+        }
+    }
+    for (let i = fromIndex - 1; i >= 0; i--) {
+        if (!lyrics[i].isInstrumental && lyrics[i].agent) {
+            return lyrics[i].agent;
+        }
+    }
+    return undefined;
+}
+export function isNearestLyricRtl(lyrics, fromIndex) {
+    // Look in the downwards direction first
+    for (let i = fromIndex + 1; i < lyrics.length; i++) {
+        if (!lyrics[i].isInstrumental && lyrics[i].words?.trim()) {
+            return testRtl(lyrics[i].words);
+        }
+    }
+    for (let i = fromIndex - 1; i >= 0; i--) {
+        if (!lyrics[i].isInstrumental && lyrics[i].words?.trim()) {
+            return testRtl(lyrics[i].words);
+        }
+    }
+    return false;
+}
+// -- Lyric shape --------------------------------------------
+// A line whose parts are missing, empty or overridden by the theme is rebuilt as line synced words,
+// which carry no duration, so only pre-existing timed parts count as rich sync.
+export function deriveSyncType(lyrics) {
+    const hasTimedParts = !disableRichsync.getBooleanValue() &&
+        lyrics.some(item => !item.isInstrumental && item.parts?.some(part => part.durationMs !== 0) === true);
+    if (hasTimedParts)
+        return "richsync";
+    return lyrics.every(item => item.startTimeMs === 0) ? "none" : "synced";
+}
+function newPartData(part, span) {
+    return {
+        time: part.startTimeMs / 1000,
+        duration: part.durationMs / 1000,
+        lyricElement: span,
+        animations: [],
+    };
+}
+export function newLineData(lyricElement, startTimeMs, durationMs) {
+    return {
+        lyricElement,
+        time: startTimeMs / 1000,
+        duration: durationMs / 1000,
+        parts: [],
+        isScrolled: false,
+        isAnimationPlayStatePlaying: false,
+        accumulatedOffsetMs: 0,
+        isAnimating: false,
+        lastAnimSetupAt: 0,
+        isSelected: false,
+        height: -1,
+        position: -1,
+        animations: [],
+    };
+}
+function detectDirection(text) {
+    for (const char of text) {
+        if (RTL_SCRIPT_REGEX.test(char))
+            return "rtl";
+        if (LTR_SCRIPT_REGEX.test(char))
+            return "ltr";
+    }
+    return "auto";
+}
+export function applyDirection(element, text) {
+    const direction = detectDirection(text);
+    element.dir = "auto";
+    if (direction === "rtl") {
+        element.classList.add(RTL_CLASS);
+        element.dataset.direction = "rtl";
+    }
+    else if (direction === "ltr") {
+        element.dataset.direction = "ltr";
+    }
+}
+function applyBidiSensitivity(element, text) {
+    if (testRtl(text)) {
+        element.classList.add(BIDI_SENSITIVE_CLASS);
+    }
+}
+function splitPartIntoTokens(part) {
+    const chunks = part.words.match(/\s+|\S+/gu) ?? [];
+    if (chunks.length === 0)
+        return [];
+    const tokens = [];
+    let spaceChars = 0;
+    for (const chunk of chunks) {
+        if (SPACE_REGEX.test(chunk)) {
+            tokens.push({ kind: "space", text: chunk });
+            spaceChars += chunk.length;
+            continue;
+        }
+        tokens.push({
+            kind: "part",
+            text: chunk,
+            part: {
+                words: chunk,
+                isBackground: part.isBackground,
+                explicit: part.explicit,
+            },
+        });
+    }
+    const nonWhiteSpaceChars = part.words.length - spaceChars;
+    let cursor = 0;
+    return tokens.map(t => {
+        if (t.kind === "part") {
+            const startTimeMs = part.startTimeMs + Math.round((part.durationMs * cursor) / nonWhiteSpaceChars);
+            const endTimeMs = part.startTimeMs + Math.round((part.durationMs * (cursor + t.text.length)) / nonWhiteSpaceChars);
+            cursor += t.text.length;
+            return {
+                ...t,
+                part: {
+                    ...t.part,
+                    startTimeMs,
+                    durationMs: endTimeMs - startTimeMs,
+                },
+            };
+        }
+        return t;
+    });
+}
+function normalizeParts(parts) {
+    return parts.flatMap(splitPartIntoTokens);
+}
+function groupTokensByWord(tokens) {
+    const groups = [];
+    let current = null;
+    const flush = () => {
+        if (current && current.tokens.length > 0) {
+            groups.push(current);
+        }
+        current = null;
+    };
+    for (const token of tokens) {
+        if (token.kind === "space") {
+            flush();
+            groups.push(token);
+            continue;
+        }
+        const isBackground = token.part?.isBackground === true;
+        if (!current || current.isBackground !== isBackground) {
+            flush();
+            current = { text: "", isBackground, tokens: [] };
+        }
+        current.text += token.text;
+        current.tokens.push(token);
+    }
+    flush();
+    return groups;
+}
+function appendLongWordBreaks(doc, span, text, threshold) {
+    if (text.length <= threshold) {
+        span.textContent = text;
+        return false;
+    }
+    for (let i = 0; i < text.length; i += threshold) {
+        span.appendChild(doc.createTextNode(text.slice(i, i + threshold)));
+        if (i + threshold < text.length) {
+            span.appendChild(doc.createElement("wbr"));
+        }
+    }
+    return true;
+}
+function cloneTextWithBreaks(doc, source) {
+    const fragment = doc.createDocumentFragment();
+    for (const node of source.childNodes) {
+        fragment.appendChild(node.cloneNode(true));
+    }
+    return fragment;
+}
+function createTimedWordSpan(doc, part, wrapThreshold) {
+    const span = doc.createElement("span");
+    span.classList.add(WORD_CLASS);
+    span.dir = "auto";
+    if (part.durationMs === 0) {
+        span.classList.add(ZERO_DURATION_ANIMATION_CLASS);
+        span.classList.add(LINE_SYNCED_WORD_CLASS);
+    }
+    if (testRtl(part.words)) {
+        span.classList.add(RTL_CLASS);
+    }
+    if (part.durationMs > longWordThreshold.getNumberValue()) {
+        span.dataset.longWord = "true";
+    }
+    if (part.isBackground) {
+        span.classList.add(BACKGROUND_LYRIC_CLASS);
+    }
+    if (part.explicit) {
+        span.classList.add(EXPLICIT_WORD_CLASS);
+    }
+    const hasBreaks = appendLongWordBreaks(doc, span, part.words, wrapThreshold);
+    if (hasBreaks) {
+        const highlight = doc.createElement("span");
+        highlight.classList.add(WORD_HIGHLIGHT_CLASS);
+        highlight.setAttribute("aria-hidden", "true");
+        highlight.appendChild(cloneTextWithBreaks(doc, span));
+        span.appendChild(highlight);
+    }
+    span.dataset.time = String(part.startTimeMs / 1000);
+    span.dataset.duration = String(part.durationMs / 1000);
+    span.dataset.content = part.words;
+    span.style.setProperty("--blyrics-duration", part.durationMs + "ms");
+    return span;
+}
+function createWordGroup(doc, group, lineData) {
+    const wrapThreshold = Math.max(1, longWordWrapThreshold.getNumberValue());
+    const groupElement = doc.createElement("span");
+    groupElement.classList.add(WORD_GROUP_CLASS);
+    groupElement.dir = "auto";
+    groupElement.dataset.content = group.text;
+    if (group.text.length > wrapThreshold * 2) {
+        groupElement.classList.add(LONG_WORD_GROUP_CLASS);
+    }
+    if (group.isBackground) {
+        groupElement.classList.add(BACKGROUND_LYRIC_CLASS);
+    }
+    for (const token of group.tokens) {
+        if (token.kind === "space")
+            continue;
+        const span = createTimedWordSpan(doc, token.part, wrapThreshold);
+        lineData.parts.push(newPartData(token.part, span));
+        groupElement.appendChild(span);
+    }
+    return groupElement;
+}
+function createContentLine(doc, className, text) {
+    const line = doc.createElement("div");
+    line.classList.add(className);
+    applyDirection(line, text);
+    applyBidiSensitivity(line, text);
+    return line;
+}
+function createBidiRun(doc, text) {
+    const run = doc.createElement("span");
+    run.classList.add(BIDI_RUN_CLASS);
+    applyDirection(run, text);
+    return run;
+}
+export function createLyricsLine(doc, parts, line, lyricElement, options = { splitBackgroundLine: true }) {
+    const lineText = parts.map(part => part.words).join("");
+    const mainText = options.splitBackgroundLine
+        ? parts
+            .filter(part => part.isBackground !== true)
+            .map(part => part.words)
+            .join("")
+        : lineText;
+    const backgroundText = parts
+        .filter(part => part.isBackground === true)
+        .map(part => part.words)
+        .join("");
+    const main = createContentLine(doc, LINE_MAIN_CLASS, mainText);
+    const mainRun = createBidiRun(doc, mainText);
+    const groupedTokens = groupTokensByWord(normalizeParts(parts));
+    const backgroundLine = createContentLine(doc, BACKGROUND_LINE_CLASS, backgroundText);
+    const backgroundRun = createBidiRun(doc, backgroundText);
+    let hasBackground = false;
+    let pendingForegroundSpace = "";
+    let pendingBackgroundSpace = "";
+    main.appendChild(mainRun);
+    backgroundLine.appendChild(backgroundRun);
+    for (const item of groupedTokens) {
+        if ("kind" in item) {
+            // Is a RenderToken, not a WordGroup, only whitespace should enter this path
+            pendingForegroundSpace += item.text;
+            pendingBackgroundSpace += item.text;
+        }
+        else {
+            const shouldUseBackgroundLine = options.splitBackgroundLine && item.isBackground;
+            const target = shouldUseBackgroundLine ? backgroundRun : mainRun;
+            const pendingSpace = shouldUseBackgroundLine ? pendingBackgroundSpace : pendingForegroundSpace;
+            if (target.childNodes.length > 0 && pendingSpace.length > 0) {
+                target.appendChild(doc.createTextNode(pendingSpace));
+            }
+            target.appendChild(createWordGroup(doc, item, line));
+            if (shouldUseBackgroundLine) {
+                hasBackground = true;
+                pendingBackgroundSpace = "";
+            }
+            else {
+                pendingForegroundSpace = "";
+            }
+        }
+    }
+    lyricElement.appendChild(main);
+    if (hasBackground) {
+        lyricElement.appendChild(backgroundLine);
+    }
+    return main;
+}
+export function buildLineSyncedParts(item) {
+    const parts = [];
+    const tokens = item.words.match(/\s+|\S+/gu) ?? [];
+    let wordIndex = 0;
+    for (const token of tokens) {
+        const isSpace = SPACE_REGEX.test(token);
+        const startTimeMs = item.startTimeMs + wordIndex * lineSyncedAnimationDelay.getNumberValue();
+        parts.push({
+            startTimeMs,
+            words: token,
+            durationMs: 0,
+        });
+        if (!isSpace) {
+            wordIndex += 1;
+        }
+    }
+    return parts;
+}
+export function addSeekHandler(seek, lyricElement, allZero) {
+    if (allZero) {
+        lyricElement.style.cursor = "unset";
+        return;
+    }
+    lyricElement.addEventListener("click", event => {
+        const seekTime = getSeekTimeFromClick(event, lyricElement);
+        if (seekTime === null)
+            return;
+        seek(seekTime);
+    });
+}
+export function injectRomanization(doc, lyricElement, lineData, text, timedRomanization = null) {
+    if (lyricElement.querySelector(`.${ROMANIZED_LYRICS_CLASS}`))
+        return;
+    const romanizedLine = doc.createElement("div");
+    romanizedLine.classList.add(ROMANIZED_LYRICS_CLASS, CONTENT_LINE_CLASS);
+    romanizedLine.dir = "auto";
+    applyDirection(romanizedLine, text);
+    if (timedRomanization && timedRomanization.length > 0 && !disableRichsync.getBooleanValue()) {
+        createLyricsLine(doc, timedRomanization, lineData, romanizedLine, { splitBackgroundLine: false });
+    }
+    else {
+        romanizedLine.textContent = text;
+    }
+    lyricElement.appendChild(romanizedLine);
+}
+export function injectTranslation(doc, lyricElement, text) {
+    if (lyricElement.querySelector(`.${TRANSLATED_LYRICS_CLASS}`))
+        return;
+    const translatedLine = doc.createElement("div");
+    translatedLine.classList.add(TRANSLATED_LYRICS_CLASS, CONTENT_LINE_CLASS);
+    translatedLine.dir = "auto";
+    applyDirection(translatedLine, text);
+    translatedLine.textContent = text;
+    lyricElement.appendChild(translatedLine);
+}

package/dist/instrumental.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Creates an HTML element representing an instrumental break in the lyrics.
+ *
+ * @param doc - Document the SVG nodes are created in
+ * @param container - Element to place instrumental parts into
+ * @param durationMs - Duration of the instrumental break in milliseconds
+ * @param lineIndex - Line index for unique SVG element IDs
+ * @returns HTMLDivElement representing the instrumental break
+ */
+export declare function createInstrumentalElement(doc: Document, container: HTMLDivElement, durationMs: number, lineIndex: number): HTMLDivElement;

package/dist/instrumental.js

@@ -0,0 +1,78 @@
+/**
+ * Creates an HTML element representing an instrumental break in the lyrics.
+ *
+ * @param doc - Document the SVG nodes are created in
+ * @param container - Element to place instrumental parts into
+ * @param durationMs - Duration of the instrumental break in milliseconds
+ * @param lineIndex - Line index for unique SVG element IDs
+ * @returns HTMLDivElement representing the instrumental break
+ */
+export function createInstrumentalElement(doc, container, durationMs, lineIndex) {
+    container.classList.add("blyrics--instrumental");
+    container.style.setProperty("--blyrics-duration", `${durationMs}ms`);
+    const svgNS = "http://www.w3.org/2000/svg";
+    const svg = doc.createElementNS(svgNS, "svg");
+    svg.classList.add("blyrics--instrumental-icon");
+    svg.setAttribute("viewBox", "0 0 24 24");
+    const defs = doc.createElementNS(svgNS, "defs");
+    const filterId = `blyrics-glow-${lineIndex}`;
+    const clipId = `blyrics-wave-clip-${lineIndex}`;
+    const filter = doc.createElementNS(svgNS, "filter");
+    filter.setAttribute("id", filterId);
+    filter.setAttribute("x", "-100%");
+    filter.setAttribute("y", "-100%");
+    filter.setAttribute("width", "300%");
+    filter.setAttribute("height", "300%");
+    const feGaussianBlur = doc.createElementNS(svgNS, "feGaussianBlur");
+    feGaussianBlur.setAttribute("in", "SourceGraphic");
+    feGaussianBlur.setAttribute("stdDeviation", "5");
+    feGaussianBlur.setAttribute("result", "blur");
+    filter.appendChild(feGaussianBlur);
+    const feColorMatrix = doc.createElementNS(svgNS, "feColorMatrix");
+    feColorMatrix.setAttribute("in", "blur");
+    feColorMatrix.setAttribute("type", "matrix");
+    feColorMatrix.setAttribute("values", "1 0 0 0 0  0 1 0 0 0  0 0 1 0 0  0 0 0 0.6 0");
+    feColorMatrix.setAttribute("result", "fadedBlur");
+    filter.appendChild(feColorMatrix);
+    const feMerge = doc.createElementNS(svgNS, "feMerge");
+    const feMergeNode1 = doc.createElementNS(svgNS, "feMergeNode");
+    feMergeNode1.setAttribute("in", "fadedBlur");
+    feMerge.appendChild(feMergeNode1);
+    const feMergeNode2 = doc.createElementNS(svgNS, "feMergeNode");
+    feMergeNode2.setAttribute("in", "SourceGraphic");
+    feMerge.appendChild(feMergeNode2);
+    filter.appendChild(feMerge);
+    defs.appendChild(filter);
+    const clipPath = doc.createElementNS(svgNS, "clipPath");
+    clipPath.setAttribute("id", clipId);
+    clipPath.classList.add("blyrics--wave-clip");
+    //  Create the Static Block (The deep fill)
+    // This sits at y=4 (the lowest point of the wave) and extends to bottom
+    const waveRect = doc.createElementNS(svgNS, "path");
+    waveRect.classList.add("blyrics--wave-rect");
+    waveRect.setAttribute("d", "M -4 3.9 L 30 3.9 L 30 30 L -4 30 Z");
+    clipPath.appendChild(waveRect);
+    // Create the Wavy Top
+    // This only contains the surface water. It closes at y=4.
+    const wavePath = doc.createElementNS(svgNS, "path");
+    wavePath.classList.add("blyrics--wave-path");
+    // Initial draw (matches the 0% keyframe below)
+    wavePath.setAttribute("d", "M -4 3 Q 1 2 5 3 Q 10 4 14 3 Q 18 2 22 3 Q 26 4 30 3 L 30 4 L -4 4 Z");
+    clipPath.appendChild(wavePath);
+    defs.appendChild(clipPath);
+    svg.appendChild(defs);
+    const bgPath = doc.createElementNS(svgNS, "path");
+    bgPath.classList.add("blyrics--instrumental-bg");
+    bgPath.setAttribute("d", "M10 21q-1.65 0-2.825-1.175T6 17t1.175-2.825T10 13q.575 0 1.063.138t.937.412V4q0-.425.288-.712T13 3h4q.425 0 .713.288T18 4v2q0 .425-.288.713T17 7h-3v10q0 1.65-1.175 2.825T10 21");
+    svg.appendChild(bgPath);
+    const g = doc.createElementNS(svgNS, "g");
+    g.setAttribute("filter", `url(#${filterId})`);
+    const fillPath = doc.createElementNS(svgNS, "path");
+    fillPath.classList.add("blyrics--instrumental-fill");
+    fillPath.setAttribute("clip-path", `url(#${clipId})`);
+    fillPath.setAttribute("d", "M10 21q-1.65 0-2.825-1.175T6 17t1.175-2.825T10 13q.575 0 1.063.138t.937.412V4q0-.425.288-.712T13 3h4q.425 0 .713.288T18 4v2q0 .425-.288.713T17 7h-3v10q0 1.65-1.175 2.825T10 21");
+    g.appendChild(fillPath);
+    svg.appendChild(g);
+    container.appendChild(svg);
+    return container;
+}

package/dist/renderer.d.ts

@@ -0,0 +1,29 @@
+import type { LyricsRenderer, LyricsRendererHost, LyricsRendererOptions } from "./types.js";
+/**
+ * Fills in every host member the consumer left out, so the host is an extension point rather than a
+ * cost of entry. The mount is read at call time rather than captured: `setLyrics` may be given a
+ * different one, and both defaults that use it have to follow.
+ *
+ * Each member is resolved on its own rather than spread over the defaults. A host assembled from
+ * optional pieces carries members that are present and undefined, which typecheck, and spreading
+ * one of those leaves the renderer holding nothing where it expects a function.
+ *
+ * The invalidator comes back alongside the host because the memo behind the default scroll element
+ * has no way to notice it went stale on its own.
+ *
+ * Exported for `renderer.selfcheck.ts` and not published from `index.ts`. A consumer reaches these
+ * defaults by leaving host members out, so nothing outside needs to name them; what does need to is
+ * the check that every one of them is still here and still answering.
+ */
+export declare function withHostDefaults(overrides: Partial<LyricsRendererHost> | undefined, rendererWindow: Window & typeof globalThis, currentMount: () => HTMLElement | null): {
+    host: LyricsRendererHost;
+    forgetScrollElement: () => void;
+};
+/**
+ * Builds a lyrics view and keeps it measured. Line positions are read once, when the lines are
+ * built, and everything the engine scrolls by comes from that reading, so a layout that settles
+ * afterwards leaves the whole song scrolling to stale targets. Three things settle afterwards: the
+ * container's own size, the document's font faces, and the window. This owns all three, because
+ * both of the views in this extension went into production having missed at least one of them.
+ */
+export declare function createLyricsRenderer(rendererOptions: LyricsRendererOptions): LyricsRenderer;