@braccato/core 1.12.6 → 1.13.1

package/README.md

@@ -176,6 +176,19 @@ before the theme is applied.
 }
 ```
 
+A view whose edges are hidden, for example faded out by a mask, declares that with `scroll-padding`
+on its scroll element. Active lines are then kept inside the band between the two insets instead of
+the full viewport. When several active lines do not fit, the latest line still being sung keeps its
+top in view, and an earlier line's tail or the next line's lookahead gives way. Give each inset as a
+length or a percentage of the viewport height; a `calc()` that mixes the two is ignored, as are
+insets that leave no band. The insets are measured on resize and relayout, not every tick.
+
+```css
+.pip-view .scroller {
+  scroll-padding-block: 12% 16%;
+}
+```
+
 ### Autoscroll grouping and animation
 
 `blyrics-early-scroll-consider-s` is a comment setting with an independent default of `0.54`

package/dist/README.md

@@ -176,6 +176,19 @@ before the theme is applied.
 }
 ```
 
+A view whose edges are hidden, for example faded out by a mask, declares that with `scroll-padding`
+on its scroll element. Active lines are then kept inside the band between the two insets instead of
+the full viewport. When several active lines do not fit, the latest line still being sung keeps its
+top in view, and an earlier line's tail or the next line's lookahead gives way. Give each inset as a
+length or a percentage of the viewport height; a `calc()` that mixes the two is ignored, as are
+insets that leave no band. The insets are measured on resize and relayout, not every tick.
+
+```css
+.pip-view .scroller {
+  scroll-padding-block: 12% 16%;
+}
+```
+
 ### Autoscroll grouping and animation
 
 `blyrics-early-scroll-consider-s` is a comment setting with an independent default of `0.54`

package/dist/engine.d.ts

@@ -21,6 +21,8 @@ interface AnimEngineViewState {
     selectedElementIndex: number;
     wasUserScrolling: boolean;
     lastScrollElements: LineData[];
+    /** The line a committed scroll kept in view because the active lines overflowed the band. */
+    pinnedScrollLine: LineData | null;
     lastScrollDebugContext: {
         activeElms: LineData[];
         centers: number[];
@@ -39,6 +41,7 @@ export interface AnimationEngineInstance extends AnimEngineViewState {
     window: EngineWindow;
     host: LyricsRendererHost;
     cachedTabRendererHeight: number | null;
+    cachedScrollInsets: ScrollInsets;
     cachedFooterItem: LineScrollItem | null;
     cachedCreditsItem: LineScrollItem | null;
     creditsFocused: boolean;
@@ -287,6 +290,39 @@ export declare function setupLineCullObserver(engine: AnimationEngineInstance):
  * from, so the container is the term that says they are still there.
  */
 export declare function hasUnsyncedLyrics(engine: AnimationEngineInstance): boolean;
+export interface ScrollInsets {
+    readonly top: number;
+    readonly bottom: number;
+}
+/**
+ * The scroll element's `scroll-padding` is the part of its viewport a host has declared unreadable,
+ * such as an edge faded out by a mask. Insets that leave no band at all are ignored rather than
+ * obeyed, since there would be nowhere left to put a line.
+ */
+export declare function resolveScrollInsets(scrollPaddingTop: string, scrollPaddingBottom: string, viewportHeight: number): ScrollInsets;
+interface ScrollTargetLine {
+    readonly time: number;
+    readonly duration: number;
+    readonly position: number;
+    readonly height: number;
+}
+/**
+ * The line the singer is on: the latest one still being sung. An earlier line still running is a
+ * tail, such as a background echo or a held note, and a later one is still in its lookahead. A line
+ * stays active past its own end until the next one starts, so a started line only wins while it runs.
+ */
+export declare function findScrollAnchor<Line extends ScrollTargetLine>(sungLines: readonly Line[], scrollTime: number): Line;
+/**
+ * Where to scroll so the lines being sung sit around the target, inside the visible band. When they
+ * do not all fit, the anchor keeps its top in view and the rest give way. `overflowsBand` tells the
+ * caller the view is pinned to the anchor, and has to move on once that line ends.
+ *
+ * @param sungLines - In order, never empty. The last is the last active line.
+ */
+export declare function computeActiveLinesScrollTop(sungLines: readonly ScrollTargetLine[], anchor: ScrollTargetLine, viewportHeight: number, insets: ScrollInsets, targetOffset: number): {
+    scrollTop: number;
+    overflowsBand: boolean;
+};
 /**
  * "lyrics-missing" means this instance has nothing left to render. Whether that ends ticking is the
  * driver's call, not the instance's: one instance running dry must not silence another.

package/dist/engine.js

@@ -120,6 +120,7 @@ export function createAnimationEngineInstance(engineDocument, engineWindow, host
         selectedElementIndex: 0,
         wasUserScrolling: false,
         lastScrollElements: [],
+        pinnedScrollLine: null,
         lastScrollDebugContext: {
             activeElms: [],
             centers: [],
@@ -128,6 +129,7 @@ export function createAnimationEngineInstance(engineDocument, engineWindow, host
         passiveScrollAccumulatedTime: 0,
         passiveLastWallTime: 0,
         cachedTabRendererHeight: null,
+        cachedScrollInsets: NO_SCROLL_INSETS,
         cachedFooterItem: null,
         cachedCreditsItem: null,
         creditsFocused: false,
@@ -275,6 +277,7 @@ export function clearLyrics(engine) {
     }
     engine.skipScrollsDecayTimes = [];
     engine.lastScrollElements = [];
+    engine.pinnedScrollLine = null;
     engine.lastScrollDebugContext.activeElms = [];
     engine.lastScrollDebugContext.centers = [];
     engine.passiveScrollAccumulatedTime = 0;
@@ -1752,12 +1755,68 @@ function setupTabRendererObserver(engine, element) {
     engine.tabRendererResizeObserver = new engine.window.ResizeObserver(() => {
         dropPendingLineScroll(engine);
         if (element && element.isConnected) {
-            engine.cachedTabRendererHeight = element.getBoundingClientRect().height;
+            measureScrollViewport(engine, element);
         }
     });
     engine.tabRendererResizeObserver.observe(element);
     engine.observedTabRenderer = element;
-    engine.cachedTabRendererHeight = element.getBoundingClientRect().height;
+    measureScrollViewport(engine, element);
+}
+const NO_SCROLL_INSETS = { top: 0, bottom: 0 };
+function resolveScrollInset(value, viewportHeight) {
+    const amount = Number.parseFloat(value);
+    if (!Number.isFinite(amount) || amount <= 0)
+        return 0;
+    return value.trim().endsWith("%") ? (viewportHeight * amount) / 100 : amount;
+}
+/**
+ * The scroll element's `scroll-padding` is the part of its viewport a host has declared unreadable,
+ * such as an edge faded out by a mask. Insets that leave no band at all are ignored rather than
+ * obeyed, since there would be nowhere left to put a line.
+ */
+export function resolveScrollInsets(scrollPaddingTop, scrollPaddingBottom, viewportHeight) {
+    const top = resolveScrollInset(scrollPaddingTop, viewportHeight);
+    const bottom = resolveScrollInset(scrollPaddingBottom, viewportHeight);
+    return top + bottom < viewportHeight ? { top, bottom } : NO_SCROLL_INSETS;
+}
+function measureScrollViewport(engine, element) {
+    const height = element.getBoundingClientRect().height;
+    const { scrollPaddingTop, scrollPaddingBottom } = engine.window.getComputedStyle(element);
+    engine.cachedTabRendererHeight = height;
+    engine.cachedScrollInsets = resolveScrollInsets(scrollPaddingTop, scrollPaddingBottom, height);
+}
+/**
+ * The line the singer is on: the latest one still being sung. An earlier line still running is a
+ * tail, such as a background echo or a held note, and a later one is still in its lookahead. A line
+ * stays active past its own end until the next one starts, so a started line only wins while it runs.
+ */
+export function findScrollAnchor(sungLines, scrollTime) {
+    return (sungLines.findLast(line => line.time <= scrollTime && scrollTime < line.time + line.duration) ??
+        sungLines.findLast(line => line.time <= scrollTime) ??
+        sungLines[0]);
+}
+/**
+ * Where to scroll so the lines being sung sit around the target, inside the visible band. When they
+ * do not all fit, the anchor keeps its top in view and the rest give way. `overflowsBand` tells the
+ * caller the view is pinned to the anchor, and has to move on once that line ends.
+ *
+ * @param sungLines - In order, never empty. The last is the last active line.
+ */
+export function computeActiveLinesScrollTop(sungLines, anchor, viewportHeight, insets, targetOffset) {
+    const first = sungLines[0];
+    const last = sungLines[sungLines.length - 1];
+    const averageCentre = sungLines.reduce((total, line) => total + line.position + line.height / 2, 0) / sungLines.length;
+    const visibleBottom = viewportHeight - insets.bottom;
+    let scrollTop = averageCentre - targetOffset;
+    scrollTop = Math.max(scrollTop, last.position + last.height - visibleBottom);
+    scrollTop = Math.min(scrollTop, last.position - insets.top);
+    scrollTop = Math.min(scrollTop, first.position - insets.top);
+    scrollTop = Math.max(scrollTop, anchor.position + anchor.height - visibleBottom);
+    scrollTop = Math.min(scrollTop, anchor.position - insets.top);
+    return {
+        scrollTop,
+        overflowsBand: last.position + last.height - first.position > visibleBottom - insets.top,
+    };
 }
 /**
  * Fills in everything a caller left out of a tick. The tick reads each of these arithmetically, so
@@ -2012,28 +2071,24 @@ export function tickView(engine, currentTime, options) {
             // Offset so lyrics appear towards the center of the screen.
             const scrollPosOffset = tabRendererHeight * getTargetScrollRatio(engine, lyricsElement);
             let lastActiveLyric = activeElems[activeElems.length - 1];
-            let lyricPositions = activeElems
-                .filter((lineData, index) => {
-                // Ignore lyrics close to finishing unless it last active lyric
-                return (lyricScrollTime < lineData.time + lineData.duration - LYRIC_ENDING_THRESHOLD_S.getNumberValue() ||
-                    index == activeElems.length - 1);
-            })
-                // We subtract selectedLyricHeight / 2 to center the selected lyric line vertically within the offset region,
-                // so the lyric is not aligned at the very top of the offset but is visually centered.
-                .map(lineData => lineData.position + lineData.height / 2);
-            let avgPos = lyricPositions.reduce((accumulator, currentValue) => accumulator + currentValue, 0) / lyricPositions.length;
-            // Base position
-            let scrollPos = avgPos - scrollPosOffset;
-            // Make sure the first selected line is stays visible
-            scrollPos = Math.min(scrollPos, lyricPositions[0]);
-            // Make sure bottom of last active lyric is visible
-            scrollPos = Math.max(scrollPos, lastActiveLyric.position - tabRendererHeight + lastActiveLyric.height);
-            // Make sure top of last active lyric is visible.
-            scrollPos = Math.min(scrollPos, lastActiveLyric.position);
+            // Ignore lyrics close to finishing unless it is the last active lyric.
+            const sungLines = activeElems.filter((lineData, index) => lyricScrollTime < lineData.time + lineData.duration - LYRIC_ENDING_THRESHOLD_S.getNumberValue() ||
+                index == activeElems.length - 1);
+            const lyricPositions = sungLines.map(lineData => lineData.position + lineData.height / 2);
+            const scrollInsets = engine.cachedScrollInsets;
+            const scrollAnchor = findScrollAnchor(sungLines, lyricScrollTime);
+            const scrollTarget = computeActiveLinesScrollTop(sungLines, scrollAnchor, tabRendererHeight, scrollInsets, scrollPosOffset);
+            let scrollPos = scrollTarget.scrollTop;
+            const pinned = engine.pinnedScrollLine;
+            if (pinned &&
+                pinned !== scrollAnchor &&
+                (!sungLines.includes(pinned) || lyricScrollTime >= pinned.time + pinned.duration)) {
+                newLyricSelected = true;
+            }
             const credits = engine.cachedCreditsItem;
             if (engine.creditsFocused && credits && lastSungLine) {
                 // Tall credits would otherwise carry the last line out of view while it is still being sung.
-                scrollPos = Math.min(credits.position + credits.height / 2 - scrollPosOffset, lastSungLine.position);
+                scrollPos = Math.min(credits.position + credits.height / 2 - scrollPosOffset, lastSungLine.position - scrollInsets.top);
             }
             // Past either end the browser clamps the write and reports nothing, leaving the view aiming
             // at a position it never reached and re-aiming once per remaining line.
@@ -2123,6 +2178,7 @@ export function tickView(engine, currentTime, options) {
                 // 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.pinnedScrollLine = scrollTarget.overflowsBand ? scrollAnchor : null;
                 engine.lastScrollDebugContext.lyricScrollTime = lyricScrollTime;
                 engine.lastScrollDebugContext.centers = lyricPositions;
                 engine.lastScrollDebugContext.activeElms = activeElems;
@@ -2237,6 +2293,9 @@ function applyScrollPadding(engine) {
  */
 export function relayout(engine, measureLines) {
     applyScrollPadding(engine);
+    const scrollElement = engine.host.getScrollElement();
+    if (scrollElement)
+        measureScrollViewport(engine, scrollElement);
     if (!measureLines)
         return;
     const lyricsElement = engine.lyricsContainer;

package/dist/inject.js

@@ -14,7 +14,7 @@
 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";
+import { testJoiningScript, 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);
@@ -238,7 +238,7 @@ function createTimedWordSpan(doc, part, wrapThreshold, perLetter) {
             wordElement.classList.add(BACKGROUND_LYRIC_CLASS);
         if (part.explicit)
             wordElement.classList.add(EXPLICIT_WORD_CLASS);
-        if (perLetter) {
+        if (perLetter && !testJoiningScript(part.words)) {
             const collected = appendLetters(doc, wordElement, part.words);
             if (wordElement === span) {
                 letters = collected;

package/dist/text.d.ts

@@ -1,4 +1,5 @@
 export declare const testRtl: (text: string) => boolean;
+export declare const testJoiningScript: (text: string) => boolean;
 /**
  * Checks if a given string contains any non-Latin characters.
  * @param text The string to check.

package/dist/text.js

@@ -1,5 +1,6 @@
 // Script detection for the text the module renders. Pure string work, no DOM and no host state.
 export const testRtl = (text) => /[\p{Script=Arabic}\p{Script=Hebrew}\p{Script=Syriac}\p{Script=Thaana}]/u.test(text);
+export const testJoiningScript = (text) => /[\p{Script_Extensions=Arabic}\p{Script_Extensions=Syriac}\p{Script_Extensions=Nko}\p{Script_Extensions=Mongolian}\p{Script_Extensions=Adlam}\p{Script_Extensions=Mandaic}\p{Script_Extensions=Hanifi_Rohingya}]/u.test(text);
 /**
  * This regex is designed to detect any characters that are outside of the
  * standard "Basic Latin" and "Latin-1 Supplement" Unicode blocks, as well

package/package.json

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